docs: reorganize docs by type and add layout guidance (#2567)

* refactor(docs): reorganize docs by type and locale * chore(docs): add docs layout lint target and contributor guidance Introduce a lint-docs script and Makefile target for common documentation naming and placement checks. Expand docs/README.md with layout and translation conventions, and update CONTRIBUTING.md to point contributors to the new docs guidance and validation step. * docs: add section index pages and fix localized doc links - add reader navigation to docs/README.md - add index pages for guides, reference, operations, security, architecture, and migration - update localized project README links to prefer existing translated docs * docs: fix broken wecom link in Malay README
2026-06-12 18:08:54 +00:00 · 2026-04-17 18:51:07 +08:00
parent 2708c834d0 16d174e124
commit 15a3560533
177 changed files with 1152 additions and 725 deletions
@@ -35,6 +35,8 @@ We are committed to maintaining a welcoming and respectful community. Be kind, c

 For substantial new features, please open an issue first to discuss the design before writing code. This prevents wasted effort and ensures alignment with the project's direction.

+For documentation contributions, prefer the layout and naming conventions in [`docs/README.md`](docs/README.md). Run `make lint-docs` after adding or moving Markdown files to catch common consistency issues early.
+
 ---

 ## Getting Started
@@ -64,7 +66,7 @@ For substantial new features, please open an issue first to discuss the design b
 ```bash
 make build       # Build binary (runs go generate first)
 make generate    # Run go generate only
-make check       # Full pre-commit check: deps + fmt + vet + test
+make check       # Full pre-commit check: deps + fmt + vet + test + docs consistency checks
 ```

 ### Running Tests
@@ -81,9 +83,10 @@ go test -bench=. -benchmem -run='^$' ./...  # Run benchmarks
 make fmt   # Format code
 make vet   # Static analysis
 make lint  # Full linter run
+make lint-docs  # Check common documentation layout and naming conventions
 ```

-All CI checks must pass before a PR can be merged. Run `make check` locally before pushing to catch issues early.
+All CI checks must pass before a PR can be merged. Run `make check` locally before pushing to catch issues early, including the common docs consistency checks from `make lint-docs`.

 ---

@@ -1,4 +1,4 @@
-.PHONY: all build install uninstall clean help test build-all
+.PHONY: all build install uninstall clean help test build-all lint-docs

 # Build variables
 BINARY_NAME=picoclaw
@@ -308,9 +308,14 @@ test: generate
 fmt:
 	@$(GOLANGCI_LINT) fmt

+## lint-docs: Check common documentation layout and naming conventions
+lint-docs:
+	@./scripts/lint-docs.sh
+
 ## lint: Run linters
 lint:
 	@$(GOLANGCI_LINT) run --build-tags $(GO_BUILD_TAGS)
+	@./scripts/lint-docs.sh

 ## fix: Fix linting issues
 fix:
@@ -326,8 +331,8 @@ update-deps:
 	@$(GO) get -u ./...
 	@$(GO) mod tidy

-## check: Run vet, fmt, and verify dependencies
-check: deps fmt vet test
+## check: Run deps, fmt, vet, tests, and docs consistency checks
+check: deps fmt vet test lint-docs

 ## run: Build and run picoclaw
 run: build
@@ -18,7 +18,7 @@
    <a href="https://discord.gg/V4sAZ9XWpN"><img src="https://img.shields.io/badge/Discord-Community-4c60eb?style=flat&logo=discord&logoColor=white" alt="Discord"></a>
  </p>

-[中文](README.zh.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | **English**
+[中文](docs/project/README.zh.md) | [日本語](docs/project/README.ja.md) | [한국어](docs/project/README.ko.md) | [Português](docs/project/README.pt-br.md) | [Tiếng Việt](docs/project/README.vi.md) | [Français](docs/project/README.fr.md) | [Italiano](docs/project/README.it.md) | [Bahasa Indonesia](docs/project/README.id.md) | [Malay](docs/project/README.ms.md) | **English**

 </div>

@@ -112,7 +112,7 @@ _*Recent builds may use 10-20MB due to rapid PR merges. Resource optimization is

 </div>

-> **[Hardware Compatibility List](docs/hardware-compatibility.md)** — See all tested boards, from $5 RISC-V to Raspberry Pi to Android phones. Your board not listed? Submit a PR!
+> **[Hardware Compatibility List](docs/guides/hardware-compatibility.md)** — See all tested boards, from $5 RISC-V to Raspberry Pi to Android phones. Your board not listed? Submit a PR!

 <p align="center">
 <img src="assets/hardware-banner.jpg" alt="PicoClaw Hardware Compatibility" width="100%">
@@ -309,6 +309,7 @@ Use the TUI menus to: **1)** Configure a Provider -> **2)** Configure a Channel

 For detailed TUI documentation, see [docs.picoclaw.io](https://docs.picoclaw.io).

+<a id="-run-on-old-android-phones"></a>
 ### 📱 Android

 Give your decade-old phone a second life! Turn it into a smart AI Assistant with PicoClaw.
@@ -379,7 +380,7 @@ This creates `~/.picoclaw/config.json` and the workspace directory.

 > See `config/config.example.json` in the repo for a complete configuration template with all available options.
 >
-> Please note: config.example.json format is version 0, with sensitive codes in it, and will be auto migrated to version 1+, then, the config.json will only store insensitive data, the sensitive codes will be stored in .security.yml, if you need manually modify the codes, please see `docs/security_configuration.md` for more details.
+> Please note: config.example.json format is version 0, with sensitive codes in it, and will be auto migrated to version 1+, then, the config.json will only store insensitive data, the sensitive codes will be stored in .security.yml, if you need manually modify the codes, please see `docs/security/security_configuration.md` for more details.


 **3. Chat**
@@ -458,7 +459,7 @@ PicoClaw supports 30+ LLM providers through the `model_list` configuration. Use
 }
 ```

-For full provider configuration details, see [Providers & Models](docs/providers.md).
+For full provider configuration details, see [Providers & Models](docs/guides/providers.md).

 </details>

@@ -470,8 +471,8 @@ Talk to your PicoClaw through 18+ messaging platforms:
 |---------|-------|----------|------|
 | **Telegram** | Easy (bot token) | Long polling | [Guide](docs/channels/telegram/README.md) |
 | **Discord** | Easy (bot token + intents) | WebSocket | [Guide](docs/channels/discord/README.md) |
-| **WhatsApp** | Easy (QR scan or bridge URL) | Native / Bridge | [Guide](docs/chat-apps.md#whatsapp) |
-| **Weixin** | Easy (Native QR scan) | iLink API | [Guide](docs/chat-apps.md#weixin) |
+| **WhatsApp** | Easy (QR scan or bridge URL) | Native / Bridge | [Guide](docs/guides/chat-apps.md#whatsapp) |
+| **Weixin** | Easy (Native QR scan) | iLink API | [Guide](docs/guides/chat-apps.md#weixin) |
 | **QQ** | Easy (AppID + AppSecret) | WebSocket | [Guide](docs/channels/qq/README.md) |
 | **Slack** | Easy (bot + app token) | Socket Mode | [Guide](docs/channels/slack/README.md) |
 | **Matrix** | Medium (homeserver + token) | Sync API | [Guide](docs/channels/matrix/README.md) |
@@ -480,7 +481,7 @@ Talk to your PicoClaw through 18+ messaging platforms:
 | **LINE** | Medium (credentials + webhook) | Webhook | [Guide](docs/channels/line/README.md) |
 | **WeCom** | Easy (QR login or manual) | WebSocket | [Guide](docs/channels/wecom/README.md) |
 | **VK** | Easy (group token) | Long Poll | [Guide](docs/channels/vk/README.md) |
-| **IRC** | Medium (server + nick) | IRC protocol | [Guide](docs/chat-apps.md#irc) |
+| **IRC** | Medium (server + nick) | IRC protocol | [Guide](docs/guides/chat-apps.md#irc) |
 | **OneBot** | Medium (WebSocket URL) | OneBot v11 | [Guide](docs/channels/onebot/README.md) |
 | **MaixCam** | Easy (enable) | TCP socket | [Guide](docs/channels/maixcam/README.md) |
 | **Pico** | Easy (enable) | Native protocol | Built-in |
@@ -488,9 +489,9 @@ Talk to your PicoClaw through 18+ messaging platforms:

 > All webhook-based channels share a single Gateway HTTP server (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). Feishu uses WebSocket/SDK mode and does not use the shared HTTP server.

-> Log verbosity is controlled by `gateway.log_level` (default: `warn`). Supported values: `debug`, `info`, `warn`, `error`, `fatal`. Can also be set via `PICOCLAW_LOG_LEVEL`. See [Configuration](docs/configuration.md#gateway-log-level) for details.
+> Log verbosity is controlled by `gateway.log_level` (default: `warn`). Supported values: `debug`, `info`, `warn`, `error`, `fatal`. Can also be set via `PICOCLAW_LOG_LEVEL`. See [Configuration](docs/guides/configuration.md#gateway-log-level) for details.

-For detailed channel setup instructions, see [Chat Apps Configuration](docs/chat-apps.md).
+For detailed channel setup instructions, see [Chat Apps Configuration](docs/guides/chat-apps.md).

 ## 🔧 Tools

@@ -510,7 +511,7 @@ PicoClaw can search the web to provide up-to-date information. Configure in `too

 ### ⚙️ Other Tools

-PicoClaw includes built-in tools for file operations, code execution, scheduling, and more. See [Tools Configuration](docs/tools_configuration.md) for details.
+PicoClaw includes built-in tools for file operations, code execution, scheduling, and more. See [Tools Configuration](docs/reference/tools_configuration.md) for details.

 ## 🎯 Skills

@@ -547,7 +548,7 @@ Add to your `config.json`:

 `tools.skills.github.*` is deprecated. Use `tools.skills.registries.github.*` instead.

-For more details, see [Tools Configuration - Skills](docs/tools_configuration.md#skills-tool).
+For more details, see [Tools Configuration - Skills](docs/reference/tools_configuration.md#skills-tool).

 ## 🔗 MCP (Model Context Protocol)

@@ -570,7 +571,7 @@ PicoClaw natively supports [MCP](https://modelcontextprotocol.io/) — connect a
 }
 ```

-For full MCP configuration (stdio, SSE, HTTP transports, Tool Discovery), see [Tools Configuration - MCP](docs/tools_configuration.md#mcp-tool).
+For full MCP configuration (stdio, SSE, HTTP transports, Tool Discovery), see [Tools Configuration - MCP](docs/reference/tools_configuration.md#mcp-tool).

 ## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> Join the Agent Social Network

@@ -607,7 +608,7 @@ PicoClaw supports scheduled reminders and recurring tasks through the `cron` too
 * **Recurring tasks**: "Remind me every 2 hours" -> triggers every 2 hours
 * **Cron expressions**: "Remind me at 9am daily" -> uses cron expression

-See [docs/cron.md](docs/cron.md) for current schedule types, execution modes, command-job gates, and persistence details.
+See [docs/reference/cron.md](docs/reference/cron.md) for current schedule types, execution modes, command-job gates, and persistence details.

 ## 📚 Documentation

@@ -615,18 +616,18 @@ For detailed guides beyond this README:

 | Topic | Description |
 |-------|-------------|
-| [Docker & Quick Start](docs/docker.md) | Docker Compose setup, Launcher/Agent modes |
-| [Chat Apps](docs/chat-apps.md) | All 17+ channel setup guides |
-| [Configuration](docs/configuration.md) | Environment variables, workspace layout, security sandbox |
-| [Scheduled Tasks and Cron Jobs](docs/cron.md) | Cron schedule types, deliver modes, command gates, job storage |
-| [Providers & Models](docs/providers.md) | 30+ LLM providers, model routing, model_list configuration |
-| [Spawn & Async Tasks](docs/spawn-tasks.md) | Quick tasks, long tasks with spawn, async sub-agent orchestration |
-| [Hooks](docs/hooks/README.md) | Event-driven hook system: observers, interceptors, approval hooks |
-| [Steering](docs/steering.md) | Inject messages into a running agent loop between tool calls |
-| [SubTurn](docs/subturn.md) | Subagent coordination, concurrency control, lifecycle |
-| [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions |
-| [Tools Configuration](docs/tools_configuration.md) | Per-tool enable/disable, exec policies, MCP, Skills |
-| [Hardware Compatibility](docs/hardware-compatibility.md) | Tested boards, minimum requirements |
+| [Docker & Quick Start](docs/guides/docker.md) | Docker Compose setup, Launcher/Agent modes |
+| [Chat Apps](docs/guides/chat-apps.md) | All 17+ channel setup guides |
+| [Configuration](docs/guides/configuration.md) | Environment variables, workspace layout, security sandbox |
+| [Scheduled Tasks and Cron Jobs](docs/reference/cron.md) | Cron schedule types, deliver modes, command gates, job storage |
+| [Providers & Models](docs/guides/providers.md) | 30+ LLM providers, model routing, model_list configuration |
+| [Spawn & Async Tasks](docs/guides/spawn-tasks.md) | Quick tasks, long tasks with spawn, async sub-agent orchestration |
+| [Hooks](docs/architecture/hooks/README.md) | Event-driven hook system: observers, interceptors, approval hooks |
+| [Steering](docs/architecture/steering.md) | Inject messages into a running agent loop between tool calls |
+| [SubTurn](docs/architecture/subturn.md) | Subagent coordination, concurrency control, lifecycle |
+| [Troubleshooting](docs/operations/troubleshooting.md) | Common issues and solutions |
+| [Tools Configuration](docs/reference/tools_configuration.md) | Per-tool enable/disable, exec policies, MCP, Skills |
+| [Hardware Compatibility](docs/guides/hardware-compatibility.md) | Tested boards, minimum requirements |

 ## 🤝 Contribute & Roadmap

@@ -0,0 +1,132 @@
+# PicoClaw Documentation
+
+PicoClaw documentation is organized by document type first and language second.
+
+This file describes the recommended documentation layout, how translated files should be named, and what `make lint-docs` currently checks locally.
+
+These conventions are intended as contributor guidance for new or moved docs. Existing docs may still have historical exceptions, and `make lint-docs` only checks a common subset of the patterns described here.
+
+## Reader Navigation
+
+If you are browsing docs rather than reorganizing them, start with these directory indexes:
+
+- [Guides](guides/README.md): setup, configuration, provider, and workflow guides.
+- [Reference](reference/README.md): precise configuration and behavior reference.
+- [Operations](operations/README.md): debugging and troubleshooting material.
+- [Security](security/README.md): security-focused guides and controls.
+- [Architecture](architecture/README.md): implementation notes and internal design docs.
+- [Migration](migration/README.md): upgrade and migration notes.
+
+For channel-specific setup, start with [Chat Apps Configuration](guides/chat-apps.md) and then drill into `docs/channels/<name>/README.md` as needed.
+
+## Principles
+
+- Choose the document type directory first. Do not create language buckets such as `docs/zh/` or `docs/fr/`.
+- Keep each translated document next to its English source document.
+- Use English as the base filename with no locale suffix.
+- Use lowercase locale suffixes for translations, for example `configuration.zh.md` or `README.pt-br.md`.
+- Keep module-specific docs next to the code they describe instead of moving them into `docs/`.
+
+## Recommended Directories
+
+- `README.md`: English project entry document at the repository root.
+- `docs/project/`: translated project entry documents such as `README.zh.md` and `CONTRIBUTING.zh.md`.
+- `docs/guides/`: setup and usage guides.
+- `docs/reference/`: reference material and detailed configuration docs.
+- `docs/operations/`: debugging and troubleshooting docs.
+- `docs/security/`: security-related documentation.
+- `docs/architecture/`: architecture and internal design notes.
+- `docs/channels/`: channel-specific integration guides.
+- `docs/design/`: design proposals and investigations.
+- `docs/migration/`: migration notes.
+
+## Recommended Naming
+
+- English documents use the base filename:
+  - `README.md`
+  - `configuration.md`
+- Translations use `.<locale>.md`:
+  - `README.zh.md`
+  - `configuration.fr.md`
+  - `README.pt-br.md`
+- Code-adjacent translated READMEs follow the same rule:
+  - `pkg/audio/asr/README.zh.md`
+  - `pkg/isolation/README.zh.md`
+
+## Common Patterns To Avoid
+
+- Root-level translated entry docs such as `README.zh.md` or `CONTRIBUTING.fr.md`
+  - Use `docs/project/README.zh.md` or `docs/project/CONTRIBUTING.fr.md` instead.
+- Language directories under `docs/` such as `docs/zh/`, `docs/ZH/`, `docs/ja/`, or `docs/fr/`
+  - Use `docs/<type>/<name>.<locale>.md` instead.
+- Nested locale buckets such as `docs/guides/zh/configuration.md` or `docs/channels/telegram/zh/README.md`
+  - Keep translations beside the English source file instead.
+- Legacy translation filenames such as `README_zh.md` or `README_CN.md`
+  - Use `README.zh.md`.
+- Non-canonical locale suffixes such as `configuration_zh.md` or `configuration.ZH.md`
+  - Use lowercase `.<locale>.md`, for example `configuration.zh.md`.
+
+## Translation Placement
+
+- For docs under `docs/guides`, `docs/reference`, `docs/operations`, `docs/security`, `docs/architecture`, `docs/channels`, and `docs/migration`, keep translations beside the English source file.
+- For project entry translations, keep translated files in `docs/project/` and keep the English source in the repository root.
+- In most cases, each translated file should have an English source document:
+  - `docs/guides/configuration.zh.md` usually sits beside `docs/guides/configuration.md`
+  - `docs/project/README.zh.md` usually corresponds to `README.md`
+- Exception: `docs/design/` may contain locale-specific working notes without an English source document. The naming rules still apply there.
+
+## Code-Adjacent Docs
+
+Keep documentation next to the implementation when it primarily describes a package, command, example, or subproject.
+
+Examples:
+
+- `pkg/**/README.md`
+- `cmd/**/README.md`
+- `web/README.md`
+- `examples/**/README.md`
+
+These files still follow the same translation naming rules.
+
+## Adding a New Document
+
+1. Pick the correct document type directory.
+2. Create the English source file first.
+3. Add translated siblings after the English source exists when that source is part of the same docs set.
+4. Update links from existing docs when the new doc becomes a navigation target.
+5. Run `make lint-docs` locally when adding or moving docs.
+
+## Examples
+
+- New setup guide:
+  - `docs/guides/launcher-setup.md`
+  - `docs/guides/launcher-setup.zh.md`
+- New security guide:
+  - `docs/security/token-rotation.md`
+- New translated package README:
+  - `pkg/channels/README.zh.md`
+
+## Validation
+
+Run:
+
+```bash
+make lint-docs
+```
+
+The local docs linter currently checks these common cases:
+
+- no root-level translated `README` or `CONTRIBUTING` files
+- no `docs/<locale>/` language buckets, regardless of case
+- no nested locale buckets under typed docs directories
+- no legacy `README_*.md` filenames
+- no non-canonical translation-like filenames such as `_zh.md` or `.ZH.md`
+- no extra Markdown files directly under `docs/` except `docs/README.md`
+- every translated Markdown file has a matching English source file
+  - except for locale-specific working notes under `docs/design/`
+
+`make lint-docs` is a local consistency check for common naming and placement mistakes. It helps contributors stay close to the recommended layout, but it is not intended to describe every acceptable documentation pattern in the repository.
+
+When a check fails, `make lint-docs` prints the failing path, the reason, and a suggested fix.
+
+If you change these recommendations or want the local linter to reflect them more closely, update this file and `scripts/lint-docs.sh` together.
@@ -0,0 +1,10 @@
+# Architecture
+
+Internal architecture notes for major runtime mechanisms and subsystem design.
+
+- [Steering](steering.md): injecting messages into a running agent loop between tool calls.
+- [SubTurn Mechanism](subturn.md): sub-agent coordination, concurrency control, and lifecycle handling.
+- [Hook System Guide](hooks/README.md): current hook architecture and protocol details.
+- [Agent Refactor](agent-refactor/README.md): notes and checkpoints for the agent refactor work.
+
+For proposal-style or exploratory docs, also see [`../design/`](../design/).
@@ -1,4 +1,4 @@
-> Retour au [README](../../../README.fr.md)
+> Retour au [README](../../project/README.fr.md)

 # DingTalk

@@ -1,4 +1,4 @@
-> [README](../../../README.ja.md) に戻る
+> [README](../../project/README.ja.md) に戻る

 # DingTalk

@@ -1,4 +1,4 @@
-> Voltar ao [README](../../../README.pt-br.md)
+> Voltar ao [README](../../project/README.pt-br.md)

 # DingTalk

@@ -1,4 +1,4 @@
-> Quay lại [README](../../../README.vi.md)
+> Quay lại [README](../../project/README.vi.md)

 # DingTalk

@@ -1,4 +1,4 @@
-> 返回 [README](../../../README.zh.md)
+> 返回 [README](../../project/README.zh.md)

 # 钉钉

@@ -1,4 +1,4 @@
-> Retour au [README](../../../README.fr.md)
+> Retour au [README](../../project/README.fr.md)

 # Discord

@@ -1,4 +1,4 @@
-> [README](../../../README.ja.md) に戻る
+> [README](../../project/README.ja.md) に戻る

 # Discord

@@ -1,4 +1,4 @@
-> Voltar ao [README](../../../README.pt-br.md)
+> Voltar ao [README](../../project/README.pt-br.md)

 # Discord

@@ -1,4 +1,4 @@
-> Quay lại [README](../../../README.vi.md)
+> Quay lại [README](../../project/README.vi.md)

 # Discord

@@ -1,4 +1,4 @@
-> 返回 [README](../../../README.zh.md)
+> 返回 [README](../../project/README.zh.md)

 # Discord

@@ -1,4 +1,4 @@
-> Retour au [README](../../../README.fr.md)
+> Retour au [README](../../project/README.fr.md)

 # Feishu

@@ -1,4 +1,4 @@
-> [README](../../../README.ja.md) に戻る
+> [README](../../project/README.ja.md) に戻る

 # 飛書（Feishu）

@@ -1,4 +1,4 @@
-> Voltar ao [README](../../../README.pt-br.md)
+> Voltar ao [README](../../project/README.pt-br.md)

 # Feishu

@@ -1,4 +1,4 @@
-> Quay lại [README](../../../README.vi.md)
+> Quay lại [README](../../project/README.vi.md)

 # Feishu

@@ -1,4 +1,4 @@
-> 返回 [README](../../../README.zh.md)
+> 返回 [README](../../project/README.zh.md)

 # 飞书

@@ -1,4 +1,4 @@
-> Retour au [README](../../../README.fr.md)
+> Retour au [README](../../project/README.fr.md)

 # Line

@@ -1,4 +1,4 @@
-> [README](../../../README.ja.md) に戻る
+> [README](../../project/README.ja.md) に戻る

 # Line

@@ -1,4 +1,4 @@
-> Voltar ao [README](../../../README.pt-br.md)
+> Voltar ao [README](../../project/README.pt-br.md)

 # Line

@@ -1,4 +1,4 @@
-> Quay lại [README](../../../README.vi.md)
+> Quay lại [README](../../project/README.vi.md)

 # Line

@@ -1,4 +1,4 @@
-> 返回 [README](../../../README.zh.md)
+> 返回 [README](../../project/README.zh.md)

 # Line

@@ -1,4 +1,4 @@
-> Retour au [README](../../../README.fr.md)
+> Retour au [README](../../project/README.fr.md)

 # MaixCam

@@ -1,4 +1,4 @@
-> [README](../../../README.ja.md) に戻る
+> [README](../../project/README.ja.md) に戻る

 # MaixCam

@@ -1,4 +1,4 @@
-> Voltar ao [README](../../../README.pt-br.md)
+> Voltar ao [README](../../project/README.pt-br.md)

 # MaixCam

@@ -1,4 +1,4 @@
-> Quay lại [README](../../../README.vi.md)
+> Quay lại [README](../../project/README.vi.md)

 # MaixCam

@@ -1,4 +1,4 @@
-> 返回 [README](../../../README.zh.md)
+> 返回 [README](../../project/README.zh.md)

 # MaixCam

@@ -1,4 +1,4 @@
-> Retour au [README](../../../README.fr.md)
+> Retour au [README](../../project/README.fr.md)

 # Guide de configuration du canal Matrix

@@ -1,4 +1,4 @@
-> [README](../../../README.ja.md) に戻る
+> [README](../../project/README.ja.md) に戻る

 # Matrix チャンネル設定ガイド

@@ -1,4 +1,4 @@
-> Voltar ao [README](../../../README.pt-br.md)
+> Voltar ao [README](../../project/README.pt-br.md)

 # Guia de Configuração do Canal Matrix

@@ -1,4 +1,4 @@
-> Quay lại [README](../../../README.vi.md)
+> Quay lại [README](../../project/README.vi.md)

 # Hướng dẫn Cấu hình Kênh Matrix

@@ -1,4 +1,4 @@
-> 返回 [README](../../../README.zh.md)
+> 返回 [README](../../project/README.zh.md)

 # Matrix 通道配置指南

@@ -1,4 +1,4 @@
-> Retour au [README](../../../README.fr.md)
+> Retour au [README](../../project/README.fr.md)

 # OneBot

@@ -1,4 +1,4 @@
-> [README](../../../README.ja.md) に戻る
+> [README](../../project/README.ja.md) に戻る

 # OneBot

@@ -1,4 +1,4 @@
-> Voltar ao [README](../../../README.pt-br.md)
+> Voltar ao [README](../../project/README.pt-br.md)

 # OneBot

@@ -1,4 +1,4 @@
-> Quay lại [README](../../../README.vi.md)
+> Quay lại [README](../../project/README.vi.md)

 # OneBot

@@ -1,4 +1,4 @@
-> 返回 [README](../../../README.zh.md)
+> 返回 [README](../../project/README.zh.md)

 # OneBot

@@ -1,4 +1,4 @@
-> Retour au [README](../../../README.fr.md)
+> Retour au [README](../../project/README.fr.md)

 # QQ

@@ -1,4 +1,4 @@
-> [README](../../../README.ja.md) に戻る
+> [README](../../project/README.ja.md) に戻る

 # QQ

@@ -1,4 +1,4 @@
-> Voltar ao [README](../../../README.pt-br.md)
+> Voltar ao [README](../../project/README.pt-br.md)

 # QQ

@@ -1,4 +1,4 @@
-> Quay lại [README](../../../README.vi.md)
+> Quay lại [README](../../project/README.vi.md)

 # QQ

@@ -1,4 +1,4 @@
-> 返回 [README](../../../README.zh.md)
+> 返回 [README](../../project/README.zh.md)

 # QQ

@@ -1,4 +1,4 @@
-> Retour au [README](../../../README.fr.md)
+> Retour au [README](../../project/README.fr.md)

 # Slack

@@ -1,4 +1,4 @@
-> [README](../../../README.ja.md) に戻る
+> [README](../../project/README.ja.md) に戻る

 # Slack

@@ -1,4 +1,4 @@
-> Voltar ao [README](../../../README.pt-br.md)
+> Voltar ao [README](../../project/README.pt-br.md)

 # Slack

@@ -1,4 +1,4 @@
-> Quay lại [README](../../../README.vi.md)
+> Quay lại [README](../../project/README.vi.md)

 # Slack

@@ -1,4 +1,4 @@
-> 返回 [README](../../../README.zh.md)
+> 返回 [README](../../project/README.zh.md)

 # Slack

@@ -1,4 +1,4 @@
-> Retour au [README](../../../README.fr.md)
+> Retour au [README](../../project/README.fr.md)

 # Telegram

@@ -1,4 +1,4 @@
-> [README](../../../README.ja.md) に戻る
+> [README](../../project/README.ja.md) に戻る

 # Telegram

@@ -2,7 +2,7 @@

 # Telegram

-The Telegram channel uses long polling via the Telegram Bot API for bot-based communication. It supports text messages, media attachments (photos, voice, audio, documents), voice transcription ([setup](../../providers.md#voice-transcription)), and built-in command handling.
+The Telegram channel uses long polling via the Telegram Bot API for bot-based communication. It supports text messages, media attachments (photos, voice, audio, documents), voice transcription ([setup](../../guides/providers.md#voice-transcription)), and built-in command handling.

 ## Configuration

@@ -1,4 +1,4 @@
-> Voltar ao [README](../../../README.pt-br.md)
+> Voltar ao [README](../../project/README.pt-br.md)

 # Telegram

@@ -1,4 +1,4 @@
-> Quay lại [README](../../../README.vi.md)
+> Quay lại [README](../../project/README.vi.md)

 # Telegram

@@ -1,8 +1,8 @@
-> 返回 [README](../../../README.zh.md)
+> 返回 [README](../../project/README.zh.md)

 # Telegram

-Telegram Channel 通过 Telegram 机器人 API 使用长轮询实现基于机器人的通信。它支持文本消息、媒体附件（照片、语音、音频、文档）、语音转录（配置见[提供商与模型配置](../../zh/providers.md#语音转录)），以及内置命令处理器。
+Telegram Channel 通过 Telegram 机器人 API 使用长轮询实现基于机器人的通信。它支持文本消息、媒体附件（照片、语音、音频、文档）、语音转录（配置见[提供商与模型配置](../../guides/providers.zh.md#语音转录)），以及内置命令处理器。

 ## 配置

@@ -101,7 +101,7 @@ The VK channel supports both voice message reception and text-to-speech capabili
 - **ASR (Automatic Speech Recognition)**: Voice messages can be transcribed to text using configured voice models
 - **TTS (Text-to-Speech)**: Text responses can be converted to voice messages

-To enable voice transcription, configure a voice model in your providers setup. See [Voice Transcription](../../providers.md#voice-transcription) for details.
+To enable voice transcription, configure a voice model in your providers setup. See [Voice Transcription](../../guides/providers.md#voice-transcription) for details.

 ### Group Chat Support

@@ -1,4 +1,4 @@
-> Retour au [README](../../../README.fr.md)
+> Retour au [README](../../project/README.fr.md)

 # WeCom

@@ -1,4 +1,4 @@
-> [README](../../../README.ja.md) に戻る
+> [README](../../project/README.ja.md) に戻る

 # WeCom

@@ -1,4 +1,4 @@
-> Voltar ao [README](../../../README.pt-br.md)
+> Voltar ao [README](../../project/README.pt-br.md)

 # WeCom

@@ -1,4 +1,4 @@
-> Quay lại [README](../../../README.vi.md)
+> Quay lại [README](../../project/README.vi.md)

 # WeCom

@@ -1,4 +1,4 @@
-> 返回 [README](../../../README.zh.md)
+> 返回 [README](../../project/README.zh.md)

 # 企业微信（WeCom）

@@ -1,4 +1,4 @@
-> Retour au [README](../../README.fr.md)
+> Retour au [README](../project/README.fr.md)

 # Utiliser le fournisseur Antigravity dans PicoClaw

@@ -1,4 +1,4 @@
-> [README](../../README.ja.md) に戻る
+> [README](../project/README.ja.md) に戻る

 # PicoClaw で Antigravity プロバイダーを使用する

@@ -1,4 +1,4 @@
-> Voltar ao [README](../../README.pt-br.md)
+> Voltar ao [README](../project/README.pt-br.md)

 # Usando o provedor Antigravity no PicoClaw

@@ -1,4 +1,4 @@
-> Quay lại [README](../../README.vi.md)
+> Quay lại [README](../project/README.vi.md)

 # Sử dụng nhà cung cấp Antigravity trong PicoClaw

@@ -1,4 +1,4 @@
-> 返回 [README](../../README.zh.md)
+> 返回 [README](../project/README.zh.md)

 # 在 PicoClaw 中使用 Antigravity 提供商

@@ -0,0 +1,13 @@
+# Guides
+
+Task-oriented guides for setup, configuration, and common PicoClaw workflows.
+
+- [Docker & Quick Start Guide](docker.md): install and run PicoClaw with Docker or the launcher.
+- [Configuration Guide](configuration.md): environment variables, workspace layout, routing, and sandbox settings.
+- [Chat Apps Configuration](chat-apps.md): supported chat platforms and channel-specific setup paths.
+- [Providers & Model Configuration](providers.md): `model_list`, providers, and model routing.
+- [Spawn & Async Tasks](spawn-tasks.md): background work, long-running tasks, and sub-agent orchestration.
+- [PicoClaw Hardware Compatibility List](hardware-compatibility.md): tested boards and platform notes.
+- [Using Antigravity Provider in PicoClaw](ANTIGRAVITY_USAGE.md): Google Cloud Code Assist setup and usage.
+
+Translations usually live beside the English source when available.
@@ -1,6 +1,6 @@
 # 💬 Configuration des Applications de Chat

-> Retour au [README](../../README.fr.md)
+> Retour au [README](../project/README.fr.md)

 ## 💬 Applications de Chat

@@ -19,7 +19,7 @@ Communiquez avec votre PicoClaw via Telegram, Discord, WhatsApp, Matrix, QQ, Din
 | **QQ**               | ⭐⭐ Moyen         | API bot officielle, communauté chinoise               | [Documentation](../channels/qq/README.fr.md)                                                                    |
 | **DingTalk**         | ⭐⭐ Moyen         | Mode Stream (pas d'IP publique requise), entreprise   | [Documentation](../channels/dingtalk/README.fr.md)                                                              |
 | **LINE**             | ⭐⭐⭐ Avancé      | HTTPS Webhook requis                                  | [Documentation](../channels/line/README.fr.md)                                                                  |
-| **WeCom (企业微信)** | ⭐⭐⭐ Avancé      | Bot groupe (Webhook), app personnalisée (API), AI Bot | [Bot](../channels/wecom/wecom_bot/README.fr.md) / [App](../channels/wecom/wecom_app/README.fr.md) / [AI Bot](../channels/wecom/wecom_aibot/README.fr.md) |
+| **WeCom (企业微信)** | ⭐⭐⭐ Avancé      | Bot groupe (Webhook), app personnalisée (API), AI Bot | [Guide](../channels/wecom/README.fr.md) |
 | **Feishu (飞书)**    | ⭐⭐⭐ Avancé      | Collaboration entreprise, fonctionnalités riches      | [Documentation](../channels/feishu/README.fr.md)                                                                |
 | **IRC**              | ⭐⭐ Moyen         | Serveur + configuration TLS                           | [Documentation](#irc) |
 | **OneBot**           | ⭐⭐ Moyen         | Compatible NapCat/Go-CQHTTP, écosystème communautaire | [Documentation](../channels/onebot/README.fr.md)                                                                |
@@ -391,7 +391,7 @@ PicoClaw prend en charge trois types d'intégration WeCom :
 **Option 2 : WeCom App (Application personnalisée)** - Plus de fonctionnalités, messagerie proactive, chat privé uniquement
 **Option 3 : WeCom AI Bot (Bot IA)** - Bot IA officiel, réponses en streaming, prend en charge les discussions de groupe et privées

-Voir le [Guide de Configuration WeCom AI Bot](../channels/wecom/wecom_aibot/README.fr.md) pour les instructions détaillées.
+Voir le [Guide de Configuration WeCom](../channels/wecom/README.fr.md) pour les instructions détaillées.

 **Configuration rapide - WeCom Bot :**

@@ -1,6 +1,6 @@
 # 💬 チャットアプリ設定

-> [README](../../README.ja.md) に戻る
+> [README](../project/README.ja.md) に戻る

 ## 💬 チャットアプリ連携

@@ -21,7 +21,7 @@ PicoClaw は複数のチャットプラットフォームをサポートして
 | **QQ**               | ⭐⭐ 中程度        | 公式ボット API、中国コミュニティ向け       | [ドキュメント](../channels/qq/README.ja.md)                                                                   |
 | **DingTalk**         | ⭐⭐ 中程度        | Stream モード（公開 IP 不要）、企業向け    | [ドキュメント](../channels/dingtalk/README.ja.md)                                                             |
 | **LINE**             | ⭐⭐⭐ やや難      | HTTPS Webhook が必要                       | [ドキュメント](../channels/line/README.ja.md)                                                                 |
-| **WeCom (企業微信)** | ⭐⭐⭐ やや難      | グループ Bot (Webhook)、カスタムアプリ (API)、AI Bot 対応 | [Bot](../channels/wecom/wecom_bot/README.ja.md) / [App](../channels/wecom/wecom_app/README.ja.md) / [AI Bot](../channels/wecom/wecom_aibot/README.ja.md) |
+| **WeCom (企業微信)** | ⭐⭐⭐ やや難      | グループ Bot (Webhook)、カスタムアプリ (API)、AI Bot 対応 | [ガイド](../channels/wecom/README.ja.md) |
 | **Feishu (飛書)**    | ⭐⭐⭐ やや難      | エンタープライズコラボレーション、機能豊富 | [ドキュメント](../channels/feishu/README.ja.md)                                                               |
 | **IRC**              | ⭐⭐ 中程度        | サーバー + TLS 設定                        | [ドキュメント](#irc) |
 | **OneBot**           | ⭐⭐ 中程度        | NapCat/Go-CQHTTP 互換、コミュニティエコシステム充実 | [ドキュメント](../channels/onebot/README.ja.md)                                                               |
@@ -502,7 +502,7 @@ PicoClaw は 3 種類の WeCom 統合をサポートしています：
 **方式 2: カスタムアプリ (App)** — より多機能、プロアクティブメッセージング、プライベートチャットのみ
 **方式 3: AI Bot** — 公式 AI Bot、ストリーミング返信、グループ・プライベートチャット対応

-詳細なセットアップ手順は [WeCom AI Bot 設定ガイド](../channels/wecom/wecom_aibot/README.ja.md) を参照してください。
+詳細なセットアップ手順は [WeCom 設定ガイド](../channels/wecom/README.ja.md) を参照してください。

 **クイックセットアップ — グループ Bot：**

@@ -10,20 +10,20 @@ Talk to your picoclaw through Telegram, Discord, WhatsApp, Matrix, QQ, DingTalk,

 | Channel              | Difficulty         | Description                                           | Documentation                                                                                                    |
 | -------------------- | ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| **Telegram**         | ⭐ Easy            | Recommended, voice-to-text, long polling (no public IP needed) | [Docs](channels/telegram/README.md)                                                                  |
-| **Discord**          | ⭐ Easy            | Socket Mode, group/DM support, rich bot ecosystem     | [Docs](channels/discord/README.md)                                                                           |
+| **Telegram**         | ⭐ Easy            | Recommended, voice-to-text, long polling (no public IP needed) | [Docs](../channels/telegram/README.md)                                                                  |
+| **Discord**          | ⭐ Easy            | Socket Mode, group/DM support, rich bot ecosystem     | [Docs](../channels/discord/README.md)                                                                           |
 | **WhatsApp**         | ⭐ Easy            | Native (QR scan) or Bridge URL                        | [Docs](#whatsapp)                                                                                                |
 | **Weixin**           | ⭐ Easy            | Native QR scan (Tencent iLink API)                    | [Docs](#weixin)                                                                            |
-| **Slack**            | ⭐ Easy            | **Socket Mode** (no public IP needed), enterprise     | [Docs](channels/slack/README.md)                                                                             |
-| **Matrix**           | ⭐⭐ Medium        | Federated protocol, self-hosting supported            | [Docs](channels/matrix/README.md)                                                                            |
-| **QQ**               | ⭐⭐ Medium        | Official bot API, Chinese community                   | [Docs](channels/qq/README.md)                                                                                |
-| **DingTalk**         | ⭐⭐ Medium        | Stream mode (no public IP needed), enterprise         | [Docs](channels/dingtalk/README.md)                                                                          |
-| **LINE**             | ⭐⭐⭐ Advanced    | HTTPS Webhook required                                | [Docs](channels/line/README.md)                                                                              |
-| **WeCom (企业微信)** | ⭐⭐⭐ Advanced    | Official AI Bot over WebSocket, streaming + media     | [Docs](channels/wecom/README.md) |
-| **Feishu (飞书)**    | ⭐⭐⭐ Advanced    | Enterprise collaboration, feature-rich                | [Docs](channels/feishu/README.md)                                                                            |
+| **Slack**            | ⭐ Easy            | **Socket Mode** (no public IP needed), enterprise     | [Docs](../channels/slack/README.md)                                                                             |
+| **Matrix**           | ⭐⭐ Medium        | Federated protocol, self-hosting supported            | [Docs](../channels/matrix/README.md)                                                                            |
+| **QQ**               | ⭐⭐ Medium        | Official bot API, Chinese community                   | [Docs](../channels/qq/README.md)                                                                                |
+| **DingTalk**         | ⭐⭐ Medium        | Stream mode (no public IP needed), enterprise         | [Docs](../channels/dingtalk/README.md)                                                                          |
+| **LINE**             | ⭐⭐⭐ Advanced    | HTTPS Webhook required                                | [Docs](../channels/line/README.md)                                                                              |
+| **WeCom (企业微信)** | ⭐⭐⭐ Advanced    | Official AI Bot over WebSocket, streaming + media     | [Docs](../channels/wecom/README.md) |
+| **Feishu (飞书)**    | ⭐⭐⭐ Advanced    | Enterprise collaboration, feature-rich                | [Docs](../channels/feishu/README.md)                                                                            |
 | **IRC**              | ⭐⭐ Medium        | Server + TLS configuration                            | [Docs](#irc)                                                                                                     |
-| **OneBot**           | ⭐⭐ Medium        | NapCat/Go-CQHTTP compatible, community ecosystem      | [Docs](channels/onebot/README.md)                                                                            |
-| **MaixCam**          | ⭐ Easy            | Hardware integration channel for Sipeed AI cameras    | [Docs](channels/maixcam/README.md)                                                                           |
+| **OneBot**           | ⭐⭐ Medium        | NapCat/Go-CQHTTP compatible, community ecosystem      | [Docs](../channels/onebot/README.md)                                                                            |
+| **MaixCam**          | ⭐ Easy            | Hardware integration channel for Sipeed AI cameras    | [Docs](../channels/maixcam/README.md)                                                                           |
 | **Pico**             | ⭐ Easy            | Native PicoClaw protocol channel                      |                                                                                                                  |

 <a id="telegram"></a>
@@ -331,7 +331,7 @@ picoclaw gateway
 picoclaw gateway
 ```

-For full options (`device_id`, `join_on_invite`, `group_trigger`, `placeholder`, `reasoning_channel_id`), see [Matrix Channel Configuration Guide](channels/matrix/README.md).
+For full options (`device_id`, `join_on_invite`, `group_trigger`, `placeholder`, `reasoning_channel_id`), see [Matrix Channel Configuration Guide](../channels/matrix/README.md).

 </details>

@@ -392,7 +392,7 @@ picoclaw gateway
 PicoClaw now exposes WeCom as a single AI Bot channel over WebSocket.
 No public webhook callback URL is required.

-See [WeCom Configuration Guide](channels/wecom/README.md) for the full configuration reference and migration notes.
+See [WeCom Configuration Guide](../channels/wecom/README.md) for the full configuration reference and migration notes.

 **Quick Setup - Recommended**

@@ -472,7 +472,7 @@ picoclaw gateway

 Open Feishu, search for your bot name, and start chatting. You can also add the bot to a group — use `group_trigger.mention_only: true` to only respond when @mentioned.

-For full options, see [Feishu Channel Configuration Guide](channels/feishu/README.md).
+For full options, see [Feishu Channel Configuration Guide](../channels/feishu/README.md).

 </details>

@@ -1,6 +1,6 @@
 # 💬 Konfigurasi Aplikasi Sembang

-> Kembali ke [README](../../README.my.md)
+> Kembali ke [README](../project/README.ms.md)

 ## 💬 Aplikasi Sembang

@@ -279,7 +279,7 @@ picoclaw gateway
 picoclaw gateway
 ```

-Untuk pilihan penuh (`device_id`, `join_on_invite`, `group_trigger`, `placeholder`, `reasoning_channel_id`), lihat [Panduan Konfigurasi Saluran Matrix](docs/channels/matrix/README.md).
+Untuk pilihan penuh (`device_id`, `join_on_invite`, `group_trigger`, `placeholder`, `reasoning_channel_id`), lihat [Panduan Konfigurasi Saluran Matrix](../channels/matrix/README.md).

 </details>

@@ -341,7 +341,7 @@ PicoClaw menyokong tiga jenis integrasi WeCom:
 **Pilihan 2: WeCom App (Custom App)** - Lebih banyak ciri, pemesejan proaktif, sembang peribadi sahaja
 **Pilihan 3: WeCom AI Bot (AI Bot)** - AI Bot rasmi, balasan streaming, menyokong sembang kumpulan & peribadi

-Lihat [Panduan Konfigurasi WeCom AI Bot](docs/channels/wecom/wecom_aibot/README.zh.md) untuk arahan penyediaan terperinci.
+Lihat [Panduan Konfigurasi WeCom](../channels/wecom/README.zh.md) untuk arahan penyediaan terperinci.

 **Quick Setup - WeCom Bot:**

@@ -1,6 +1,6 @@
 # 💬 Configuração de Aplicativos de Chat

-> Voltar ao [README](../../README.pt-br.md)
+> Voltar ao [README](../project/README.pt-br.md)

 ## 💬 Aplicativos de Chat

@@ -19,7 +19,7 @@ Converse com seu picoclaw através do Telegram, Discord, WhatsApp, Matrix, QQ, D
 | **QQ**               | ⭐⭐ Médio         | API bot oficial, comunidade chinesa                   | [Documentação](../channels/qq/README.pt-br.md)                                                                  |
 | **DingTalk**         | ⭐⭐ Médio         | Modo Stream (sem IP público), empresarial             | [Documentação](../channels/dingtalk/README.pt-br.md)                                                            |
 | **LINE**             | ⭐⭐⭐ Avançado    | HTTPS Webhook obrigatório                             | [Documentação](../channels/line/README.pt-br.md)                                                                |
-| **WeCom (企业微信)** | ⭐⭐⭐ Avançado    | Bot de grupo (Webhook), app personalizado (API), AI Bot | [Bot](../channels/wecom/wecom_bot/README.pt-br.md) / [App](../channels/wecom/wecom_app/README.pt-br.md) / [AI Bot](../channels/wecom/wecom_aibot/README.pt-br.md) |
+| **WeCom (企业微信)** | ⭐⭐⭐ Avançado    | Bot de grupo (Webhook), app personalizado (API), AI Bot | [Guia](../channels/wecom/README.pt-br.md) |
 | **Feishu (飞书)**    | ⭐⭐⭐ Avançado    | Colaboração empresarial, rico em recursos             | [Documentação](../channels/feishu/README.pt-br.md)                                                              |
 | **IRC**              | ⭐⭐ Médio         | Servidor + configuração TLS                           | [Documentação](#irc) |
 | **OneBot**           | ⭐⭐ Médio         | Compatível com NapCat/Go-CQHTTP, ecossistema comunitário | [Documentação](../channels/onebot/README.pt-br.md)                                                           |
@@ -416,7 +416,7 @@ O PicoClaw suporta três tipos de integração WeCom:
 **Opção 2: WeCom App (App Personalizado)** - Mais recursos, mensagens proativas, apenas chat privado
 **Opção 3: WeCom AI Bot (AI Bot)** - AI Bot oficial, respostas em streaming, suporta chat de grupo e privado

-Veja o [Guia de Configuração do WeCom AI Bot](../channels/wecom/wecom_aibot/README.pt-br.md) para instruções detalhadas de configuração.
+Veja o [Guia de Configuração do WeCom](../channels/wecom/README.pt-br.md) para instruções detalhadas de configuração.

 **Configuração Rápida - WeCom Bot:**

@@ -1,6 +1,6 @@
 # 💬 Cấu Hình Ứng Dụng Chat

-> Quay lại [README](../../README.vi.md)
+> Quay lại [README](../project/README.vi.md)

 ## 💬 Ứng Dụng Chat

@@ -19,7 +19,7 @@ Trò chuyện với picoclaw của bạn qua Telegram, Discord, WhatsApp, Matrix
 | **QQ**               | ⭐⭐ Trung bình    | API bot chính thức, cộng đồng Trung Quốc              | [Tài liệu](../channels/qq/README.vi.md)                                                                         |
 | **DingTalk**         | ⭐⭐ Trung bình    | Chế độ Stream (không cần IP công khai), doanh nghiệp  | [Tài liệu](../channels/dingtalk/README.vi.md)                                                                   |
 | **LINE**             | ⭐⭐⭐ Nâng cao    | Yêu cầu HTTPS Webhook                                 | [Tài liệu](../channels/line/README.vi.md)                                                                       |
-| **WeCom (企业微信)** | ⭐⭐⭐ Nâng cao    | Bot nhóm (Webhook), ứng dụng tùy chỉnh (API), AI Bot | [Bot](../channels/wecom/wecom_bot/README.vi.md) / [App](../channels/wecom/wecom_app/README.vi.md) / [AI Bot](../channels/wecom/wecom_aibot/README.vi.md) |
+| **WeCom (企业微信)** | ⭐⭐⭐ Nâng cao    | Bot nhóm (Webhook), ứng dụng tùy chỉnh (API), AI Bot | [Hướng dẫn](../channels/wecom/README.vi.md) |
 | **Feishu (飞书)**    | ⭐⭐⭐ Nâng cao    | Cộng tác doanh nghiệp, nhiều tính năng                | [Tài liệu](../channels/feishu/README.vi.md)                                                                     |
 | **IRC**              | ⭐⭐ Trung bình    | Máy chủ + cấu hình TLS                                | [Tài liệu](#irc) |
 | **OneBot**           | ⭐⭐ Trung bình    | Tương thích NapCat/Go-CQHTTP, hệ sinh thái cộng đồng  | [Tài liệu](../channels/onebot/README.vi.md)                                                                     |
@@ -416,7 +416,7 @@ PicoClaw hỗ trợ ba loại tích hợp WeCom:
 **Tùy chọn 2: WeCom App (App Tùy chỉnh)** - Nhiều tính năng hơn, nhắn tin chủ động, chỉ chat riêng
 **Tùy chọn 3: WeCom AI Bot (AI Bot)** - AI Bot chính thức, phản hồi streaming, hỗ trợ chat nhóm & riêng

-Xem [Hướng Dẫn Cấu Hình WeCom AI Bot](../channels/wecom/wecom_aibot/README.vi.md) để biết hướng dẫn thiết lập chi tiết.
+Xem [Hướng Dẫn Cấu Hình WeCom](../channels/wecom/README.vi.md) để biết hướng dẫn thiết lập chi tiết.

 **Thiết Lập Nhanh - WeCom Bot:**

@@ -1,6 +1,6 @@
 # 💬 聊天应用配置

-> 返回 [README](../../README.zh.md)
+> 返回 [README](../project/README.zh.md)

 ## 💬 聊天应用集成 (Chat Apps)

@@ -1,6 +1,6 @@
 # ⚙️ Guide de Configuration

-> Retour au [README](../../README.fr.md)
+> Retour au [README](../project/README.fr.md)

 ## ⚙️ Configuration

@@ -393,7 +393,7 @@ Les tâches planifiées persistent après redémarrage dans `~/.picoclaw/workspa

 | Sujet | Description |
 | ----- | ----------- |
-| [Système de Hooks](../hooks/README.md) | Hooks événementiels : observateurs, intercepteurs, hooks d'approbation |
-| [Steering](../steering.md) | Injecter des messages dans une boucle agent en cours d'exécution |
-| [SubTurn](../subturn.md) | Coordination de subagents, contrôle de concurrence, cycle de vie |
-| [Gestion du Contexte](../agent-refactor/context.md) | Détection des limites de contexte, compression |
+| [Système de Hooks](../architecture/hooks/README.md) | Hooks événementiels : observateurs, intercepteurs, hooks d'approbation |
+| [Steering](../architecture/steering.md) | Injecter des messages dans une boucle agent en cours d'exécution |
+| [SubTurn](../architecture/subturn.md) | Coordination de subagents, contrôle de concurrence, cycle de vie |
+| [Gestion du Contexte](../architecture/agent-refactor/context.md) | Détection des limites de contexte, compression |
@@ -1,6 +1,6 @@
 # ⚙️ 設定ガイド

-> [README](../../README.ja.md) に戻る
+> [README](../project/README.ja.md) に戻る

 ## ⚙️ 設定詳細

@@ -394,7 +394,7 @@ PicoClaw は `cron` ツールを通じて cron スタイルのスケジュール

 | トピック | 説明 |
 | -------- | ---- |
-| [Hook システム](../hooks/README.md) | イベント駆動 Hook：オブザーバー、インターセプター、承認 Hook |
-| [Steering](../steering.md) | 実行中の Agent ループにメッセージを注入 |
-| [SubTurn](../subturn.md) | サブ Agent の調整、並行制御、ライフサイクル |
-| [コンテキスト管理](../agent-refactor/context.md) | コンテキスト境界検出、圧縮戦略 |
+| [Hook システム](../architecture/hooks/README.md) | イベント駆動 Hook：オブザーバー、インターセプター、承認 Hook |
+| [Steering](../architecture/steering.md) | 実行中の Agent ループにメッセージを注入 |
+| [SubTurn](../architecture/subturn.md) | サブ Agent の調整、並行制御、ライフサイクル |
+| [コンテキスト管理](../architecture/agent-refactor/context.md) | コンテキスト境界検出、圧縮戦略 |
@@ -6,7 +6,7 @@

 Config file: `~/.picoclaw/config.json`

-> **Security Configuration:** For storing API keys, tokens, and other sensitive data, see the [Security Configuration Guide](security_configuration.md).
+> **Security Configuration:** For storing API keys, tokens, and other sensitive data, see the [Security Configuration Guide](../security/security_configuration.md).

 ### Environment Variables

@@ -555,7 +555,7 @@ chmod 600 ~/.picoclaw/.security.yml
 - If a field exists in both files, `.security.yml` value takes precedence
 - You can mix direct values in config.json with security values

-For complete documentation, see [`security_configuration.md`](security_configuration.md).
+For complete documentation, see [`../security/security_configuration.md`](../security/security_configuration.md).

 #### All Supported Vendors

@@ -840,7 +840,7 @@ This keeps the runtime lightweight while making new OpenAI-compatible backends m

 > **Note**: The `providers` format is deprecated. Use the new `model_list` format with `.security.yml` for better security.
 >
-> **`max_parallel_turns`**: Controls concurrent processing of messages from different sessions. `1` (default) = sequential; `>1` = parallel. Messages from the same session are always serialized. See [Steering docs](../steering.md) for details.
+> **`max_parallel_turns`**: Controls concurrent processing of messages from different sessions. `1` (default) = sequential; `>1` = parallel. Messages from the same session are always serialized. See [Steering docs](../architecture/steering.md) for details.

 </details>

@@ -906,9 +906,9 @@ Scheduled tasks persist across restarts and are stored in `~/.picoclaw/workspace

 | Topic | Description |
 | ----- | ----------- |
-| [Security Configuration](security_configuration.md) | Store API keys and secrets in separate `.security.yml` file |
-| [Sensitive Data Filtering](sensitive_data_filtering.md) | Filter API keys and tokens from tool results before sending to LLM |
-| [Hook System](hooks/README.md) | Event-driven hooks: observers, interceptors, approval hooks |
-| [Steering](steering.md) | Inject messages into a running agent loop between tool calls |
-| [SubTurn](subturn.md) | Subagent coordination, concurrency control, lifecycle |
-| [Context Management](agent-refactor/context.md) | Context boundary detection, proactive budget check, compression |
+| [Security Configuration](../security/security_configuration.md) | Store API keys and secrets in separate `.security.yml` file |
+| [Sensitive Data Filtering](../security/sensitive_data_filtering.md) | Filter API keys and tokens from tool results before sending to LLM |
+| [Hook System](../architecture/hooks/README.md) | Event-driven hooks: observers, interceptors, approval hooks |
+| [Steering](../architecture/steering.md) | Inject messages into a running agent loop between tool calls |
+| [SubTurn](../architecture/subturn.md) | Subagent coordination, concurrency control, lifecycle |
+| [Context Management](../architecture/agent-refactor/context.md) | Context boundary detection, proactive budget check, compression |
@@ -1,6 +1,6 @@
 # ⚙️ Panduan Konfigurasi

-> Kembali ke [README](../../README.my.md)
+> Kembali ke [README](../project/README.ms.md)

 ## ⚙️ Konfigurasi

@@ -1,6 +1,6 @@
 # ⚙️ Guia de Configuração

-> Voltar ao [README](../../README.pt-br.md)
+> Voltar ao [README](../project/README.pt-br.md)

 ## ⚙️ Configuração

@@ -394,7 +394,7 @@ As tarefas agendadas persistem após reinicializações em `~/.picoclaw/workspac

 | Tópico | Descrição |
 | ------ | --------- |
-| [Sistema de Hooks](../hooks/README.md) | Hooks orientados a eventos: observadores, interceptores, hooks de aprovação |
-| [Steering](../steering.md) | Injetar mensagens em um loop de agente em execução |
-| [SubTurn](../subturn.md) | Coordenação de subagentes, controle de concorrência, ciclo de vida |
-| [Gerenciamento de Contexto](../agent-refactor/context.md) | Detecção de limites de contexto, compressão |
+| [Sistema de Hooks](../architecture/hooks/README.md) | Hooks orientados a eventos: observadores, interceptores, hooks de aprovação |
+| [Steering](../architecture/steering.md) | Injetar mensagens em um loop de agente em execução |
+| [SubTurn](../architecture/subturn.md) | Coordenação de subagentes, controle de concorrência, ciclo de vida |
+| [Gerenciamento de Contexto](../architecture/agent-refactor/context.md) | Detecção de limites de contexto, compressão |
@@ -1,6 +1,6 @@
 # ⚙️ Hướng Dẫn Cấu Hình

-> Quay lại [README](../../README.vi.md)
+> Quay lại [README](../project/README.vi.md)

 ## ⚙️ Cấu Hình

@@ -394,7 +394,7 @@ Tác vụ đã lên lịch được lưu trữ bền vững sau khi khởi độ

 | Chủ đề | Mô tả |
 | ------ | ----- |
-| [Hệ Thống Hook](../hooks/README.md) | Hook hướng sự kiện: observer, interceptor, approval hook |
-| [Steering](../steering.md) | Chèn tin nhắn vào vòng lặp agent đang chạy |
-| [SubTurn](../subturn.md) | Điều phối subagent, kiểm soát đồng thời, vòng đời |
-| [Quản Lý Ngữ Cảnh](../agent-refactor/context.md) | Phát hiện ranh giới ngữ cảnh, nén |
+| [Hệ Thống Hook](../architecture/hooks/README.md) | Hook hướng sự kiện: observer, interceptor, approval hook |
+| [Steering](../architecture/steering.md) | Chèn tin nhắn vào vòng lặp agent đang chạy |
+| [SubTurn](../architecture/subturn.md) | Điều phối subagent, kiểm soát đồng thời, vòng đời |
+| [Quản Lý Ngữ Cảnh](../architecture/agent-refactor/context.md) | Phát hiện ranh giới ngữ cảnh, nén |
@@ -1,6 +1,6 @@
 # ⚙️ 配置指南

-> 返回 [README](../../README.zh.md)
+> 返回 [README](../project/README.zh.md)

 ## ⚙️ 配置详解

@@ -670,8 +670,8 @@ PicoClaw 通过 `cron` 工具支持 cron 风格的定时任务。Agent 可以设

 | 主题 | 说明 |
 | ---- | ---- |
-| [敏感数据过滤](../sensitive_data_filtering.md) | 在发送给 LLM 前，从工具结果中过滤 API 密钥和令牌 |
-| [Hook 系统](../hooks/README.zh.md) | 事件驱动 Hook：观察者、拦截器、审批 Hook |
-| [Steering](../steering.md) | 在工具调用间向运行中的 Agent 注入消息 |
-| [SubTurn](../subturn.md) | 子 Agent 协调、并发控制、生命周期管理 |
-| [上下文管理](../agent-refactor/context.md) | 上下文边界检测、主动预算检查、压缩策略 |
+| [敏感数据过滤](../security/sensitive_data_filtering.zh.md) | 在发送给 LLM 前，从工具结果中过滤 API 密钥和令牌 |
+| [Hook 系统](../architecture/hooks/README.zh.md) | 事件驱动 Hook：观察者、拦截器、审批 Hook |
+| [Steering](../architecture/steering.md) | 在工具调用间向运行中的 Agent 注入消息 |
+| [SubTurn](../architecture/subturn.md) | 子 Agent 协调、并发控制、生命周期管理 |
+| [上下文管理](../architecture/agent-refactor/context.md) | 上下文边界检测、主动预算检查、压缩策略 |
@@ -1,6 +1,6 @@
 # 🐳 Docker et Démarrage Rapide

-> Retour au [README](../../README.fr.md)
+> Retour au [README](../project/README.fr.md)

 ## 🐳 Docker Compose

@@ -1,6 +1,6 @@
 # 🐳 Docker とクイックスタート

-> [README](../../README.ja.md) に戻る
+> [README](../project/README.ja.md) に戻る

 ## 🐳 Docker Compose

@@ -143,7 +143,7 @@ picoclaw onboard
 }
 ```

-> **新機能**: `model_list` 設定形式により、コード変更なしで provider を追加できます。詳細は[モデル設定](providers.md#モデル設定-model_list)を参照してください。
+> **新機能**: `model_list` 設定形式により、コード変更なしで provider を追加できます。詳細は[モデル設定](providers.ja.md#モデル設定-model_list)を参照してください。
 > `request_timeout` はオプションで、単位は秒です。省略または `<= 0` に設定した場合、PicoClaw はデフォルトのタイムアウト（120 秒）を使用します。

 **3. API Key の取得**
@@ -1,6 +1,6 @@
 # 🐳 Panduan Docker & Quick Start

-> Kembali ke [README](../../README.my.md)
+> Kembali ke [README](../project/README.ms.md)

 ## 🐳 Docker Compose

@@ -1,6 +1,6 @@
 # 🐳 Docker e Início Rápido

-> Voltar ao [README](../../README.pt-br.md)
+> Voltar ao [README](../project/README.pt-br.md)

 ## 🐳 Docker Compose

@@ -1,6 +1,6 @@
 # 🐳 Docker và Bắt Đầu Nhanh

-> Quay lại [README](../../README.vi.md)
+> Quay lại [README](../project/README.vi.md)

 ## 🐳 Docker Compose

--- a/Show More
+++ b/Show More