diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index cbb6a6347..a78c41c36 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -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`.
---
diff --git a/Makefile b/Makefile
index afaa7c29a..c5d691c29 100644
--- a/Makefile
+++ b/Makefile
@@ -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
diff --git a/README.md b/README.md
index 1ab514a29..5aac4bbc9 100644
--- a/README.md
+++ b/README.md
@@ -18,7 +18,7 @@
-[中文](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**
@@ -112,7 +112,7 @@ _*Recent builds may use 10-20MB due to rapid PR merges. Resource optimization is
-> **[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!
@@ -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).
+
### 📱 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).
@@ -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).
## 
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
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 000000000..529eb49ec
--- /dev/null
+++ b/docs/README.md
@@ -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//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 `..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//..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 `..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//` 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.
diff --git a/docs/architecture/README.md b/docs/architecture/README.md
new file mode 100644
index 000000000..1803bc84f
--- /dev/null
+++ b/docs/architecture/README.md
@@ -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/).
diff --git a/docs/agent-refactor/README.md b/docs/architecture/agent-refactor/README.md
similarity index 100%
rename from docs/agent-refactor/README.md
rename to docs/architecture/agent-refactor/README.md
diff --git a/docs/agent-refactor/context.md b/docs/architecture/agent-refactor/context.md
similarity index 100%
rename from docs/agent-refactor/context.md
rename to docs/architecture/agent-refactor/context.md
diff --git a/docs/agent-refactor/loop-split.md b/docs/architecture/agent-refactor/loop-split.md
similarity index 100%
rename from docs/agent-refactor/loop-split.md
rename to docs/architecture/agent-refactor/loop-split.md
diff --git a/docs/hooks/README.md b/docs/architecture/hooks/README.md
similarity index 100%
rename from docs/hooks/README.md
rename to docs/architecture/hooks/README.md
diff --git a/docs/hooks/README.zh.md b/docs/architecture/hooks/README.zh.md
similarity index 100%
rename from docs/hooks/README.zh.md
rename to docs/architecture/hooks/README.zh.md
diff --git a/docs/hooks/hook-json-protocol.md b/docs/architecture/hooks/hook-json-protocol.md
similarity index 100%
rename from docs/hooks/hook-json-protocol.md
rename to docs/architecture/hooks/hook-json-protocol.md
diff --git a/docs/hooks/hook-json-protocol.zh.md b/docs/architecture/hooks/hook-json-protocol.zh.md
similarity index 100%
rename from docs/hooks/hook-json-protocol.zh.md
rename to docs/architecture/hooks/hook-json-protocol.zh.md
diff --git a/docs/hooks/plugin-tool-injection.md b/docs/architecture/hooks/plugin-tool-injection.md
similarity index 100%
rename from docs/hooks/plugin-tool-injection.md
rename to docs/architecture/hooks/plugin-tool-injection.md
diff --git a/docs/hooks/plugin-tool-injection.zh.md b/docs/architecture/hooks/plugin-tool-injection.zh.md
similarity index 100%
rename from docs/hooks/plugin-tool-injection.zh.md
rename to docs/architecture/hooks/plugin-tool-injection.zh.md
diff --git a/docs/steering.md b/docs/architecture/steering.md
similarity index 100%
rename from docs/steering.md
rename to docs/architecture/steering.md
diff --git a/docs/subturn.md b/docs/architecture/subturn.md
similarity index 100%
rename from docs/subturn.md
rename to docs/architecture/subturn.md
diff --git a/docs/channels/dingtalk/README.fr.md b/docs/channels/dingtalk/README.fr.md
index eec59f6f2..ea0d45194 100644
--- a/docs/channels/dingtalk/README.fr.md
+++ b/docs/channels/dingtalk/README.fr.md
@@ -1,4 +1,4 @@
-> Retour au [README](../../../README.fr.md)
+> Retour au [README](../../project/README.fr.md)
# DingTalk
diff --git a/docs/channels/dingtalk/README.ja.md b/docs/channels/dingtalk/README.ja.md
index c465b6e2f..4796038f9 100644
--- a/docs/channels/dingtalk/README.ja.md
+++ b/docs/channels/dingtalk/README.ja.md
@@ -1,4 +1,4 @@
-> [README](../../../README.ja.md) に戻る
+> [README](../../project/README.ja.md) に戻る
# DingTalk
diff --git a/docs/channels/dingtalk/README.pt-br.md b/docs/channels/dingtalk/README.pt-br.md
index a96480342..c4a3da804 100644
--- a/docs/channels/dingtalk/README.pt-br.md
+++ b/docs/channels/dingtalk/README.pt-br.md
@@ -1,4 +1,4 @@
-> Voltar ao [README](../../../README.pt-br.md)
+> Voltar ao [README](../../project/README.pt-br.md)
# DingTalk
diff --git a/docs/channels/dingtalk/README.vi.md b/docs/channels/dingtalk/README.vi.md
index b760e28f7..83550a14e 100644
--- a/docs/channels/dingtalk/README.vi.md
+++ b/docs/channels/dingtalk/README.vi.md
@@ -1,4 +1,4 @@
-> Quay lại [README](../../../README.vi.md)
+> Quay lại [README](../../project/README.vi.md)
# DingTalk
diff --git a/docs/channels/dingtalk/README.zh.md b/docs/channels/dingtalk/README.zh.md
index 13c7080b3..7c672c383 100644
--- a/docs/channels/dingtalk/README.zh.md
+++ b/docs/channels/dingtalk/README.zh.md
@@ -1,4 +1,4 @@
-> 返回 [README](../../../README.zh.md)
+> 返回 [README](../../project/README.zh.md)
# 钉钉
diff --git a/docs/channels/discord/README.fr.md b/docs/channels/discord/README.fr.md
index e8ac64668..951eb59be 100644
--- a/docs/channels/discord/README.fr.md
+++ b/docs/channels/discord/README.fr.md
@@ -1,4 +1,4 @@
-> Retour au [README](../../../README.fr.md)
+> Retour au [README](../../project/README.fr.md)
# Discord
diff --git a/docs/channels/discord/README.ja.md b/docs/channels/discord/README.ja.md
index e4d71f41b..212abc1a3 100644
--- a/docs/channels/discord/README.ja.md
+++ b/docs/channels/discord/README.ja.md
@@ -1,4 +1,4 @@
-> [README](../../../README.ja.md) に戻る
+> [README](../../project/README.ja.md) に戻る
# Discord
diff --git a/docs/channels/discord/README.pt-br.md b/docs/channels/discord/README.pt-br.md
index b782a944b..32d828b76 100644
--- a/docs/channels/discord/README.pt-br.md
+++ b/docs/channels/discord/README.pt-br.md
@@ -1,4 +1,4 @@
-> Voltar ao [README](../../../README.pt-br.md)
+> Voltar ao [README](../../project/README.pt-br.md)
# Discord
diff --git a/docs/channels/discord/README.vi.md b/docs/channels/discord/README.vi.md
index ea25dc003..e9ad6f5cc 100644
--- a/docs/channels/discord/README.vi.md
+++ b/docs/channels/discord/README.vi.md
@@ -1,4 +1,4 @@
-> Quay lại [README](../../../README.vi.md)
+> Quay lại [README](../../project/README.vi.md)
# Discord
diff --git a/docs/channels/discord/README.zh.md b/docs/channels/discord/README.zh.md
index 30fe3d28b..d6785ac3b 100644
--- a/docs/channels/discord/README.zh.md
+++ b/docs/channels/discord/README.zh.md
@@ -1,4 +1,4 @@
-> 返回 [README](../../../README.zh.md)
+> 返回 [README](../../project/README.zh.md)
# Discord
diff --git a/docs/channels/feishu/README.fr.md b/docs/channels/feishu/README.fr.md
index 8f9fdafcc..0d82c9655 100644
--- a/docs/channels/feishu/README.fr.md
+++ b/docs/channels/feishu/README.fr.md
@@ -1,4 +1,4 @@
-> Retour au [README](../../../README.fr.md)
+> Retour au [README](../../project/README.fr.md)
# Feishu
diff --git a/docs/channels/feishu/README.ja.md b/docs/channels/feishu/README.ja.md
index 955ecc233..c19e9fbec 100644
--- a/docs/channels/feishu/README.ja.md
+++ b/docs/channels/feishu/README.ja.md
@@ -1,4 +1,4 @@
-> [README](../../../README.ja.md) に戻る
+> [README](../../project/README.ja.md) に戻る
# 飛書（Feishu）
diff --git a/docs/channels/feishu/README.pt-br.md b/docs/channels/feishu/README.pt-br.md
index 11089cf2c..73ab981e0 100644
--- a/docs/channels/feishu/README.pt-br.md
+++ b/docs/channels/feishu/README.pt-br.md
@@ -1,4 +1,4 @@
-> Voltar ao [README](../../../README.pt-br.md)
+> Voltar ao [README](../../project/README.pt-br.md)
# Feishu
diff --git a/docs/channels/feishu/README.vi.md b/docs/channels/feishu/README.vi.md
index abe51db97..1db4c1146 100644
--- a/docs/channels/feishu/README.vi.md
+++ b/docs/channels/feishu/README.vi.md
@@ -1,4 +1,4 @@
-> Quay lại [README](../../../README.vi.md)
+> Quay lại [README](../../project/README.vi.md)
# Feishu
diff --git a/docs/channels/feishu/README.zh.md b/docs/channels/feishu/README.zh.md
index 882ee3d3f..afe117286 100644
--- a/docs/channels/feishu/README.zh.md
+++ b/docs/channels/feishu/README.zh.md
@@ -1,4 +1,4 @@
-> 返回 [README](../../../README.zh.md)
+> 返回 [README](../../project/README.zh.md)
# 飞书
diff --git a/docs/channels/line/README.fr.md b/docs/channels/line/README.fr.md
index 522ff1d2f..c37e1c3a0 100644
--- a/docs/channels/line/README.fr.md
+++ b/docs/channels/line/README.fr.md
@@ -1,4 +1,4 @@
-> Retour au [README](../../../README.fr.md)
+> Retour au [README](../../project/README.fr.md)
# Line
diff --git a/docs/channels/line/README.ja.md b/docs/channels/line/README.ja.md
index a751d61e9..ed374c5e3 100644
--- a/docs/channels/line/README.ja.md
+++ b/docs/channels/line/README.ja.md
@@ -1,4 +1,4 @@
-> [README](../../../README.ja.md) に戻る
+> [README](../../project/README.ja.md) に戻る
# Line
diff --git a/docs/channels/line/README.pt-br.md b/docs/channels/line/README.pt-br.md
index 73a1ab837..5feea3153 100644
--- a/docs/channels/line/README.pt-br.md
+++ b/docs/channels/line/README.pt-br.md
@@ -1,4 +1,4 @@
-> Voltar ao [README](../../../README.pt-br.md)
+> Voltar ao [README](../../project/README.pt-br.md)
# Line
diff --git a/docs/channels/line/README.vi.md b/docs/channels/line/README.vi.md
index d799a934d..e834610e8 100644
--- a/docs/channels/line/README.vi.md
+++ b/docs/channels/line/README.vi.md
@@ -1,4 +1,4 @@
-> Quay lại [README](../../../README.vi.md)
+> Quay lại [README](../../project/README.vi.md)
# Line
diff --git a/docs/channels/line/README.zh.md b/docs/channels/line/README.zh.md
index cdc4380c3..5b353de1b 100644
--- a/docs/channels/line/README.zh.md
+++ b/docs/channels/line/README.zh.md
@@ -1,4 +1,4 @@
-> 返回 [README](../../../README.zh.md)
+> 返回 [README](../../project/README.zh.md)
# Line
diff --git a/docs/channels/maixcam/README.fr.md b/docs/channels/maixcam/README.fr.md
index c4871f10a..23f8c11cc 100644
--- a/docs/channels/maixcam/README.fr.md
+++ b/docs/channels/maixcam/README.fr.md
@@ -1,4 +1,4 @@
-> Retour au [README](../../../README.fr.md)
+> Retour au [README](../../project/README.fr.md)
# MaixCam
diff --git a/docs/channels/maixcam/README.ja.md b/docs/channels/maixcam/README.ja.md
index 6d06370d7..adec19445 100644
--- a/docs/channels/maixcam/README.ja.md
+++ b/docs/channels/maixcam/README.ja.md
@@ -1,4 +1,4 @@
-> [README](../../../README.ja.md) に戻る
+> [README](../../project/README.ja.md) に戻る
# MaixCam
diff --git a/docs/channels/maixcam/README.pt-br.md b/docs/channels/maixcam/README.pt-br.md
index 6243bb67b..dd606ff53 100644
--- a/docs/channels/maixcam/README.pt-br.md
+++ b/docs/channels/maixcam/README.pt-br.md
@@ -1,4 +1,4 @@
-> Voltar ao [README](../../../README.pt-br.md)
+> Voltar ao [README](../../project/README.pt-br.md)
# MaixCam
diff --git a/docs/channels/maixcam/README.vi.md b/docs/channels/maixcam/README.vi.md
index 7f0dc5812..09aba3540 100644
--- a/docs/channels/maixcam/README.vi.md
+++ b/docs/channels/maixcam/README.vi.md
@@ -1,4 +1,4 @@
-> Quay lại [README](../../../README.vi.md)
+> Quay lại [README](../../project/README.vi.md)
# MaixCam
diff --git a/docs/channels/maixcam/README.zh.md b/docs/channels/maixcam/README.zh.md
index f9e434976..2b4fdb87a 100644
--- a/docs/channels/maixcam/README.zh.md
+++ b/docs/channels/maixcam/README.zh.md
@@ -1,4 +1,4 @@
-> 返回 [README](../../../README.zh.md)
+> 返回 [README](../../project/README.zh.md)
# MaixCam
diff --git a/docs/channels/matrix/README.fr.md b/docs/channels/matrix/README.fr.md
index e4e1341c1..5ff329a28 100644
--- a/docs/channels/matrix/README.fr.md
+++ b/docs/channels/matrix/README.fr.md
@@ -1,4 +1,4 @@
-> Retour au [README](../../../README.fr.md)
+> Retour au [README](../../project/README.fr.md)
# Guide de configuration du canal Matrix
diff --git a/docs/channels/matrix/README.ja.md b/docs/channels/matrix/README.ja.md
index fb80cd484..adb14a1f9 100644
--- a/docs/channels/matrix/README.ja.md
+++ b/docs/channels/matrix/README.ja.md
@@ -1,4 +1,4 @@
-> [README](../../../README.ja.md) に戻る
+> [README](../../project/README.ja.md) に戻る
# Matrix チャンネル設定ガイド
diff --git a/docs/channels/matrix/README.pt-br.md b/docs/channels/matrix/README.pt-br.md
index 22deaf861..4f606f3ed 100644
--- a/docs/channels/matrix/README.pt-br.md
+++ b/docs/channels/matrix/README.pt-br.md
@@ -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
diff --git a/docs/channels/matrix/README.vi.md b/docs/channels/matrix/README.vi.md
index d01b5ae3d..27f2ce746 100644
--- a/docs/channels/matrix/README.vi.md
+++ b/docs/channels/matrix/README.vi.md
@@ -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
diff --git a/docs/channels/matrix/README.zh.md b/docs/channels/matrix/README.zh.md
index 08a746d7f..97634e2e6 100644
--- a/docs/channels/matrix/README.zh.md
+++ b/docs/channels/matrix/README.zh.md
@@ -1,4 +1,4 @@
-> 返回 [README](../../../README.zh.md)
+> 返回 [README](../../project/README.zh.md)
# Matrix 通道配置指南
diff --git a/docs/channels/onebot/README.fr.md b/docs/channels/onebot/README.fr.md
index 209dd529d..8a2aec8d2 100644
--- a/docs/channels/onebot/README.fr.md
+++ b/docs/channels/onebot/README.fr.md
@@ -1,4 +1,4 @@
-> Retour au [README](../../../README.fr.md)
+> Retour au [README](../../project/README.fr.md)
# OneBot
diff --git a/docs/channels/onebot/README.ja.md b/docs/channels/onebot/README.ja.md
index d08908d69..d2616e582 100644
--- a/docs/channels/onebot/README.ja.md
+++ b/docs/channels/onebot/README.ja.md
@@ -1,4 +1,4 @@
-> [README](../../../README.ja.md) に戻る
+> [README](../../project/README.ja.md) に戻る
# OneBot
diff --git a/docs/channels/onebot/README.pt-br.md b/docs/channels/onebot/README.pt-br.md
index 7043cc867..2e037361f 100644
--- a/docs/channels/onebot/README.pt-br.md
+++ b/docs/channels/onebot/README.pt-br.md
@@ -1,4 +1,4 @@
-> Voltar ao [README](../../../README.pt-br.md)
+> Voltar ao [README](../../project/README.pt-br.md)
# OneBot
diff --git a/docs/channels/onebot/README.vi.md b/docs/channels/onebot/README.vi.md
index 5ee1f37fd..3dfcf8161 100644
--- a/docs/channels/onebot/README.vi.md
+++ b/docs/channels/onebot/README.vi.md
@@ -1,4 +1,4 @@
-> Quay lại [README](../../../README.vi.md)
+> Quay lại [README](../../project/README.vi.md)
# OneBot
diff --git a/docs/channels/onebot/README.zh.md b/docs/channels/onebot/README.zh.md
index 6f9f07c0d..4e5210b82 100644
--- a/docs/channels/onebot/README.zh.md
+++ b/docs/channels/onebot/README.zh.md
@@ -1,4 +1,4 @@
-> 返回 [README](../../../README.zh.md)
+> 返回 [README](../../project/README.zh.md)
# OneBot
diff --git a/docs/channels/qq/README.fr.md b/docs/channels/qq/README.fr.md
index e46bd7ebd..2202fa09d 100644
--- a/docs/channels/qq/README.fr.md
+++ b/docs/channels/qq/README.fr.md
@@ -1,4 +1,4 @@
-> Retour au [README](../../../README.fr.md)
+> Retour au [README](../../project/README.fr.md)
# QQ
diff --git a/docs/channels/qq/README.ja.md b/docs/channels/qq/README.ja.md
index 791428cc2..d9e86a061 100644
--- a/docs/channels/qq/README.ja.md
+++ b/docs/channels/qq/README.ja.md
@@ -1,4 +1,4 @@
-> [README](../../../README.ja.md) に戻る
+> [README](../../project/README.ja.md) に戻る
# QQ
diff --git a/docs/channels/qq/README.pt-br.md b/docs/channels/qq/README.pt-br.md
index d5eb0080b..b0a7e5568 100644
--- a/docs/channels/qq/README.pt-br.md
+++ b/docs/channels/qq/README.pt-br.md
@@ -1,4 +1,4 @@
-> Voltar ao [README](../../../README.pt-br.md)
+> Voltar ao [README](../../project/README.pt-br.md)
# QQ
diff --git a/docs/channels/qq/README.vi.md b/docs/channels/qq/README.vi.md
index d3973df41..cf940d05d 100644
--- a/docs/channels/qq/README.vi.md
+++ b/docs/channels/qq/README.vi.md
@@ -1,4 +1,4 @@
-> Quay lại [README](../../../README.vi.md)
+> Quay lại [README](../../project/README.vi.md)
# QQ
diff --git a/docs/channels/qq/README.zh.md b/docs/channels/qq/README.zh.md
index fa3b129e0..dc40f6225 100644
--- a/docs/channels/qq/README.zh.md
+++ b/docs/channels/qq/README.zh.md
@@ -1,4 +1,4 @@
-> 返回 [README](../../../README.zh.md)
+> 返回 [README](../../project/README.zh.md)
# QQ
diff --git a/docs/channels/slack/README.fr.md b/docs/channels/slack/README.fr.md
index 7d0d09f5d..be533052a 100644
--- a/docs/channels/slack/README.fr.md
+++ b/docs/channels/slack/README.fr.md
@@ -1,4 +1,4 @@
-> Retour au [README](../../../README.fr.md)
+> Retour au [README](../../project/README.fr.md)
# Slack
diff --git a/docs/channels/slack/README.ja.md b/docs/channels/slack/README.ja.md
index b2184310e..38cfc0134 100644
--- a/docs/channels/slack/README.ja.md
+++ b/docs/channels/slack/README.ja.md
@@ -1,4 +1,4 @@
-> [README](../../../README.ja.md) に戻る
+> [README](../../project/README.ja.md) に戻る
# Slack
diff --git a/docs/channels/slack/README.pt-br.md b/docs/channels/slack/README.pt-br.md
index 6d1b7c520..d2676d44a 100644
--- a/docs/channels/slack/README.pt-br.md
+++ b/docs/channels/slack/README.pt-br.md
@@ -1,4 +1,4 @@
-> Voltar ao [README](../../../README.pt-br.md)
+> Voltar ao [README](../../project/README.pt-br.md)
# Slack
diff --git a/docs/channels/slack/README.vi.md b/docs/channels/slack/README.vi.md
index dff55b9ad..3bbbe3132 100644
--- a/docs/channels/slack/README.vi.md
+++ b/docs/channels/slack/README.vi.md
@@ -1,4 +1,4 @@
-> Quay lại [README](../../../README.vi.md)
+> Quay lại [README](../../project/README.vi.md)
# Slack
diff --git a/docs/channels/slack/README.zh.md b/docs/channels/slack/README.zh.md
index e8dba16b8..8ecfe88bf 100644
--- a/docs/channels/slack/README.zh.md
+++ b/docs/channels/slack/README.zh.md
@@ -1,4 +1,4 @@
-> 返回 [README](../../../README.zh.md)
+> 返回 [README](../../project/README.zh.md)
# Slack
diff --git a/docs/channels/telegram/README.fr.md b/docs/channels/telegram/README.fr.md
index 944b0091f..51db2082f 100644
--- a/docs/channels/telegram/README.fr.md
+++ b/docs/channels/telegram/README.fr.md
@@ -1,4 +1,4 @@
-> Retour au [README](../../../README.fr.md)
+> Retour au [README](../../project/README.fr.md)
# Telegram
diff --git a/docs/channels/telegram/README.ja.md b/docs/channels/telegram/README.ja.md
index 58e4cbdfa..03303f255 100644
--- a/docs/channels/telegram/README.ja.md
+++ b/docs/channels/telegram/README.ja.md
@@ -1,4 +1,4 @@
-> [README](../../../README.ja.md) に戻る
+> [README](../../project/README.ja.md) に戻る
# Telegram
diff --git a/docs/channels/telegram/README.md b/docs/channels/telegram/README.md
index e4b298176..3b114ebef 100644
--- a/docs/channels/telegram/README.md
+++ b/docs/channels/telegram/README.md
@@ -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
diff --git a/docs/channels/telegram/README.pt-br.md b/docs/channels/telegram/README.pt-br.md
index 2cd4c99c7..4af8d7a25 100644
--- a/docs/channels/telegram/README.pt-br.md
+++ b/docs/channels/telegram/README.pt-br.md
@@ -1,4 +1,4 @@
-> Voltar ao [README](../../../README.pt-br.md)
+> Voltar ao [README](../../project/README.pt-br.md)
# Telegram
diff --git a/docs/channels/telegram/README.vi.md b/docs/channels/telegram/README.vi.md
index efe6cf821..c6a276754 100644
--- a/docs/channels/telegram/README.vi.md
+++ b/docs/channels/telegram/README.vi.md
@@ -1,4 +1,4 @@
-> Quay lại [README](../../../README.vi.md)
+> Quay lại [README](../../project/README.vi.md)
# Telegram
diff --git a/docs/channels/telegram/README.zh.md b/docs/channels/telegram/README.zh.md
index fa5dc42d6..543e16e47 100644
--- a/docs/channels/telegram/README.zh.md
+++ b/docs/channels/telegram/README.zh.md
@@ -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#语音转录)），以及内置命令处理器。
## 配置
diff --git a/docs/channels/vk/README.md b/docs/channels/vk/README.md
index c3f4b80e4..5e0c72bce 100644
--- a/docs/channels/vk/README.md
+++ b/docs/channels/vk/README.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
diff --git a/docs/channels/wecom/README.fr.md b/docs/channels/wecom/README.fr.md
index b2cad168e..843943bdf 100644
--- a/docs/channels/wecom/README.fr.md
+++ b/docs/channels/wecom/README.fr.md
@@ -1,4 +1,4 @@
-> Retour au [README](../../../README.fr.md)
+> Retour au [README](../../project/README.fr.md)
# WeCom
diff --git a/docs/channels/wecom/README.ja.md b/docs/channels/wecom/README.ja.md
index 02224b6a9..459a922a6 100644
--- a/docs/channels/wecom/README.ja.md
+++ b/docs/channels/wecom/README.ja.md
@@ -1,4 +1,4 @@
-> [README](../../../README.ja.md) に戻る
+> [README](../../project/README.ja.md) に戻る
# WeCom
diff --git a/docs/channels/wecom/README.pt-br.md b/docs/channels/wecom/README.pt-br.md
index d20631910..07a5e23b9 100644
--- a/docs/channels/wecom/README.pt-br.md
+++ b/docs/channels/wecom/README.pt-br.md
@@ -1,4 +1,4 @@
-> Voltar ao [README](../../../README.pt-br.md)
+> Voltar ao [README](../../project/README.pt-br.md)
# WeCom
diff --git a/docs/channels/wecom/README.vi.md b/docs/channels/wecom/README.vi.md
index 08d571e24..4769fd6d6 100644
--- a/docs/channels/wecom/README.vi.md
+++ b/docs/channels/wecom/README.vi.md
@@ -1,4 +1,4 @@
-> Quay lại [README](../../../README.vi.md)
+> Quay lại [README](../../project/README.vi.md)
# WeCom
diff --git a/docs/channels/wecom/README.zh.md b/docs/channels/wecom/README.zh.md
index 736ef969a..8303a8f8a 100644
--- a/docs/channels/wecom/README.zh.md
+++ b/docs/channels/wecom/README.zh.md
@@ -1,4 +1,4 @@
-> 返回 [README](../../../README.zh.md)
+> 返回 [README](../../project/README.zh.md)
# 企业微信（WeCom）
diff --git a/docs/fr/ANTIGRAVITY_USAGE.md b/docs/guides/ANTIGRAVITY_USAGE.fr.md
similarity index 98%
rename from docs/fr/ANTIGRAVITY_USAGE.md
rename to docs/guides/ANTIGRAVITY_USAGE.fr.md
index d6d0a2bd4..5672952d3 100644
--- a/docs/fr/ANTIGRAVITY_USAGE.md
+++ b/docs/guides/ANTIGRAVITY_USAGE.fr.md
@@ -1,4 +1,4 @@
-> Retour au [README](../../README.fr.md)
+> Retour au [README](../project/README.fr.md)
# Utiliser le fournisseur Antigravity dans PicoClaw
diff --git a/docs/ja/ANTIGRAVITY_USAGE.md b/docs/guides/ANTIGRAVITY_USAGE.ja.md
similarity index 98%
rename from docs/ja/ANTIGRAVITY_USAGE.md
rename to docs/guides/ANTIGRAVITY_USAGE.ja.md
index c044c1970..bd221ed1c 100644
--- a/docs/ja/ANTIGRAVITY_USAGE.md
+++ b/docs/guides/ANTIGRAVITY_USAGE.ja.md
@@ -1,4 +1,4 @@
-> [README](../../README.ja.md) に戻る
+> [README](../project/README.ja.md) に戻る
# PicoClaw で Antigravity プロバイダーを使用する
diff --git a/docs/ANTIGRAVITY_USAGE.md b/docs/guides/ANTIGRAVITY_USAGE.md
similarity index 100%
rename from docs/ANTIGRAVITY_USAGE.md
rename to docs/guides/ANTIGRAVITY_USAGE.md
diff --git a/docs/pt-br/ANTIGRAVITY_USAGE.md b/docs/guides/ANTIGRAVITY_USAGE.pt-br.md
similarity index 98%
rename from docs/pt-br/ANTIGRAVITY_USAGE.md
rename to docs/guides/ANTIGRAVITY_USAGE.pt-br.md
index d4b681ad0..e5108916a 100644
--- a/docs/pt-br/ANTIGRAVITY_USAGE.md
+++ b/docs/guides/ANTIGRAVITY_USAGE.pt-br.md
@@ -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
diff --git a/docs/vi/ANTIGRAVITY_USAGE.md b/docs/guides/ANTIGRAVITY_USAGE.vi.md
similarity index 98%
rename from docs/vi/ANTIGRAVITY_USAGE.md
rename to docs/guides/ANTIGRAVITY_USAGE.vi.md
index 4a696f770..54b4a6add 100644
--- a/docs/vi/ANTIGRAVITY_USAGE.md
+++ b/docs/guides/ANTIGRAVITY_USAGE.vi.md
@@ -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
diff --git a/docs/zh/ANTIGRAVITY_USAGE.md b/docs/guides/ANTIGRAVITY_USAGE.zh.md
similarity index 98%
rename from docs/zh/ANTIGRAVITY_USAGE.md
rename to docs/guides/ANTIGRAVITY_USAGE.zh.md
index 2218618a9..b4dde6ea3 100644
--- a/docs/zh/ANTIGRAVITY_USAGE.md
+++ b/docs/guides/ANTIGRAVITY_USAGE.zh.md
@@ -1,4 +1,4 @@
-> 返回 [README](../../README.zh.md)
+> 返回 [README](../project/README.zh.md)
# 在 PicoClaw 中使用 Antigravity 提供商
diff --git a/docs/guides/README.md b/docs/guides/README.md
new file mode 100644
index 000000000..93ed679d5
--- /dev/null
+++ b/docs/guides/README.md
@@ -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.
diff --git a/docs/fr/chat-apps.md b/docs/guides/chat-apps.fr.md
similarity index 98%
rename from docs/fr/chat-apps.md
rename to docs/guides/chat-apps.fr.md
index 35330ed92..d9112c595 100644
--- a/docs/fr/chat-apps.md
+++ b/docs/guides/chat-apps.fr.md
@@ -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 :**
diff --git a/docs/ja/chat-apps.md b/docs/guides/chat-apps.ja.md
similarity index 98%
rename from docs/ja/chat-apps.md
rename to docs/guides/chat-apps.ja.md
index b143a5fc6..49c41a66e 100644
--- a/docs/ja/chat-apps.md
+++ b/docs/guides/chat-apps.ja.md
@@ -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：**
diff --git a/docs/chat-apps.md b/docs/guides/chat-apps.md
similarity index 90%
rename from docs/chat-apps.md
rename to docs/guides/chat-apps.md
index 698633642..140a659d1 100644
--- a/docs/chat-apps.md
+++ b/docs/guides/chat-apps.md
@@ -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 | |
@@ -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).
@@ -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).
diff --git a/docs/my/chat-apps.md b/docs/guides/chat-apps.ms.md
similarity index 98%
rename from docs/my/chat-apps.md
rename to docs/guides/chat-apps.ms.md
index 531c19cbb..6bfa7565e 100644
--- a/docs/my/chat-apps.md
+++ b/docs/guides/chat-apps.ms.md
@@ -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).
@@ -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:**
diff --git a/docs/pt-br/chat-apps.md b/docs/guides/chat-apps.pt-br.md
similarity index 98%
rename from docs/pt-br/chat-apps.md
rename to docs/guides/chat-apps.pt-br.md
index 5d7e5990b..6d4fbdc23 100644
--- a/docs/pt-br/chat-apps.md
+++ b/docs/guides/chat-apps.pt-br.md
@@ -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:**
diff --git a/docs/vi/chat-apps.md b/docs/guides/chat-apps.vi.md
similarity index 98%
rename from docs/vi/chat-apps.md
rename to docs/guides/chat-apps.vi.md
index 5dc4f8f01..8d0b4ee32 100644
--- a/docs/vi/chat-apps.md
+++ b/docs/guides/chat-apps.vi.md
@@ -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:**
diff --git a/docs/zh/chat-apps.md b/docs/guides/chat-apps.zh.md
similarity index 99%
rename from docs/zh/chat-apps.md
rename to docs/guides/chat-apps.zh.md
index bb71e7c1c..b5891dc69 100644
--- a/docs/zh/chat-apps.md
+++ b/docs/guides/chat-apps.zh.md
@@ -1,6 +1,6 @@
# 💬 聊天应用配置
-> 返回 [README](../../README.zh.md)
+> 返回 [README](../project/README.zh.md)
## 💬 聊天应用集成 (Chat Apps)
diff --git a/docs/fr/configuration.md b/docs/guides/configuration.fr.md
similarity index 97%
rename from docs/fr/configuration.md
rename to docs/guides/configuration.fr.md
index b26b8c4f7..f147fea95 100644
--- a/docs/fr/configuration.md
+++ b/docs/guides/configuration.fr.md
@@ -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 |
diff --git a/docs/ja/configuration.md b/docs/guides/configuration.ja.md
similarity index 97%
rename from docs/ja/configuration.md
rename to docs/guides/configuration.ja.md
index bf2392585..1940eacda 100644
--- a/docs/ja/configuration.md
+++ b/docs/guides/configuration.ja.md
@@ -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) | コンテキスト境界検出、圧縮戦略 |
diff --git a/docs/configuration.md b/docs/guides/configuration.md
similarity index 97%
rename from docs/configuration.md
rename to docs/guides/configuration.md
index 88999b8a3..b9a26b044 100644
--- a/docs/configuration.md
+++ b/docs/guides/configuration.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.
@@ -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 |
diff --git a/docs/my/configuration.md b/docs/guides/configuration.ms.md
similarity index 99%
rename from docs/my/configuration.md
rename to docs/guides/configuration.ms.md
index 75bdd71a6..bcd17afa8 100644
--- a/docs/my/configuration.md
+++ b/docs/guides/configuration.ms.md
@@ -1,6 +1,6 @@
# ⚙️ Panduan Konfigurasi
-> Kembali ke [README](../../README.my.md)
+> Kembali ke [README](../project/README.ms.md)
## ⚙️ Konfigurasi
diff --git a/docs/pt-br/configuration.md b/docs/guides/configuration.pt-br.md
similarity index 97%
rename from docs/pt-br/configuration.md
rename to docs/guides/configuration.pt-br.md
index 7bf5f4026..c47278484 100644
--- a/docs/pt-br/configuration.md
+++ b/docs/guides/configuration.pt-br.md
@@ -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 |
diff --git a/docs/vi/configuration.md b/docs/guides/configuration.vi.md
similarity index 97%
rename from docs/vi/configuration.md
rename to docs/guides/configuration.vi.md
index ea897bc28..9efeaa2b6 100644
--- a/docs/vi/configuration.md
+++ b/docs/guides/configuration.vi.md
@@ -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 |
diff --git a/docs/zh/configuration.md b/docs/guides/configuration.zh.md
similarity index 97%
rename from docs/zh/configuration.md
rename to docs/guides/configuration.zh.md
index 9a8d39262..3dac6e6ee 100644
--- a/docs/zh/configuration.md
+++ b/docs/guides/configuration.zh.md
@@ -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) | 上下文边界检测、主动预算检查、压缩策略 |
diff --git a/docs/fr/docker.md b/docs/guides/docker.fr.md
similarity index 99%
rename from docs/fr/docker.md
rename to docs/guides/docker.fr.md
index 9605440bc..f8c821570 100644
--- a/docs/fr/docker.md
+++ b/docs/guides/docker.fr.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
diff --git a/docs/ja/docker.md b/docs/guides/docker.ja.md
similarity index 97%
rename from docs/ja/docker.md
rename to docs/guides/docker.ja.md
index a585c5e80..f5885e775 100644
--- a/docs/ja/docker.md
+++ b/docs/guides/docker.ja.md
@@ -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 の取得**
diff --git a/docs/docker.md b/docs/guides/docker.md
similarity index 100%
rename from docs/docker.md
rename to docs/guides/docker.md
diff --git a/docs/my/docker.md b/docs/guides/docker.ms.md
similarity index 99%
rename from docs/my/docker.md
rename to docs/guides/docker.ms.md
index 2f9cac3fd..05725e195 100644
--- a/docs/my/docker.md
+++ b/docs/guides/docker.ms.md
@@ -1,6 +1,6 @@
# 🐳 Panduan Docker & Quick Start
-> Kembali ke [README](../../README.my.md)
+> Kembali ke [README](../project/README.ms.md)
## 🐳 Docker Compose
diff --git a/docs/pt-br/docker.md b/docs/guides/docker.pt-br.md
similarity index 99%
rename from docs/pt-br/docker.md
rename to docs/guides/docker.pt-br.md
index a17dc64ec..46d273bee 100644
--- a/docs/pt-br/docker.md
+++ b/docs/guides/docker.pt-br.md
@@ -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
diff --git a/docs/vi/docker.md b/docs/guides/docker.vi.md
similarity index 99%
rename from docs/vi/docker.md
rename to docs/guides/docker.vi.md
index e6bc74b1a..716c81544 100644
--- a/docs/vi/docker.md
+++ b/docs/guides/docker.vi.md
@@ -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
diff --git a/docs/zh/docker.md b/docs/guides/docker.zh.md
similarity index 97%
rename from docs/zh/docker.md
rename to docs/guides/docker.zh.md
index f840290a7..521747d16 100644
--- a/docs/zh/docker.md
+++ b/docs/guides/docker.zh.md
@@ -1,6 +1,6 @@
# 🐳 Docker 与快速开始
-> 返回 [README](../../README.zh.md)
+> 返回 [README](../project/README.zh.md)
## 🐳 Docker Compose
@@ -143,7 +143,7 @@ picoclaw onboard
}
```
-> **新功能**: `model_list` 配置格式支持零代码添加 provider。详见[模型配置](providers.md#模型配置-model_list)章节。
+> **新功能**: `model_list` 配置格式支持零代码添加 provider。详见[模型配置](providers.zh.md#模型配置-model_list)章节。
> `request_timeout` 为可选项，单位为秒。若省略或设置为 `<= 0`，PicoClaw 使用默认超时（120 秒）。
**3. 获取 API Key**
diff --git a/docs/fr/hardware-compatibility.md b/docs/guides/hardware-compatibility.fr.md
similarity index 98%
rename from docs/fr/hardware-compatibility.md
rename to docs/guides/hardware-compatibility.fr.md
index c1f397e80..bb2d92d57 100644
--- a/docs/fr/hardware-compatibility.md
+++ b/docs/guides/hardware-compatibility.fr.md
@@ -1,4 +1,4 @@
-> Retour au [README](../../README.fr.md)
+> Retour au [README](../project/README.fr.md)
# 🖥️ PicoClaw Liste de compatibilité matérielle
@@ -99,7 +99,7 @@ Produits grand public, routeurs et appareils industriels testés avec PicoClaw.
Tout téléphone Android ARM64 (2015+) avec 1 Go+ de RAM. Installez [Termux](https://github.com/termux/termux-app), utilisez `proot` pour exécuter PicoClaw.
-> Voir [README : Exécuter sur d'anciens téléphones Android](../../README.fr.md#-run-on-old-android-phones) pour les instructions de configuration.
+> Voir [README : Exécuter sur d'anciens téléphones Android](../project/README.fr.md#-run-on-old-android-phones) pour les instructions de configuration.
### Bureau / Serveur / Cloud
diff --git a/docs/ja/hardware-compatibility.md b/docs/guides/hardware-compatibility.ja.md
similarity index 98%
rename from docs/ja/hardware-compatibility.md
rename to docs/guides/hardware-compatibility.ja.md
index 96ccd1cd1..c86684f84 100644
--- a/docs/ja/hardware-compatibility.md
+++ b/docs/guides/hardware-compatibility.ja.md
@@ -1,4 +1,4 @@
-> [README](../../README.ja.md) に戻る
+> [README](../project/README.ja.md) に戻る
# 🖥️ PicoClaw ハードウェア互換性リスト
@@ -99,7 +99,7 @@ PicoClaw でテスト済みのコンシューマー製品、ルーター、産
1GB 以上の RAM を搭載した ARM64 Android スマートフォン（2015年以降）。[Termux](https://github.com/termux/termux-app) をインストールし、`proot` を使用して PicoClaw を実行します。
-> セットアップ手順は [README：古い Android スマートフォンで実行](../../README.ja.md#-run-on-old-android-phones) を参照してください。
+> セットアップ手順は [README：古い Android スマートフォンで実行](../project/README.ja.md#-run-on-old-android-phones) を参照してください。
### デスクトップ / サーバー / クラウド
diff --git a/docs/hardware-compatibility.md b/docs/guides/hardware-compatibility.md
similarity index 98%
rename from docs/hardware-compatibility.md
rename to docs/guides/hardware-compatibility.md
index c11849822..a07bb5116 100644
--- a/docs/hardware-compatibility.md
+++ b/docs/guides/hardware-compatibility.md
@@ -97,7 +97,7 @@ Consumer products, routers, and industrial devices that have been tested with Pi
Any ARM64 Android phone (2015+) with 1GB+ RAM. Install [Termux](https://github.com/termux/termux-app), use `proot` to run PicoClaw.
-> See [README: Run on old Android Phones](../README.md#-run-on-old-android-phones) for setup instructions.
+> See [README: Run on old Android Phones](../../README.md#-run-on-old-android-phones) for setup instructions.
### Desktop / Server / Cloud
diff --git a/docs/pt-br/hardware-compatibility.md b/docs/guides/hardware-compatibility.pt-br.md
similarity index 97%
rename from docs/pt-br/hardware-compatibility.md
rename to docs/guides/hardware-compatibility.pt-br.md
index 771621014..1fc8ee25e 100644
--- a/docs/pt-br/hardware-compatibility.md
+++ b/docs/guides/hardware-compatibility.pt-br.md
@@ -1,4 +1,4 @@
-> Voltar ao [README](../../README.pt-br.md)
+> Voltar ao [README](../project/README.pt-br.md)
# 🖥️ PicoClaw Lista de compatibilidade de hardware
@@ -99,7 +99,7 @@ Produtos de consumo, roteadores e dispositivos industriais testados com o PicoCl
Qualquer celular Android ARM64 (2015+) com 1GB+ de RAM. Instale o [Termux](https://github.com/termux/termux-app), use `proot` para rodar o PicoClaw.
-> Veja [README: Rodar em celulares Android antigos](../../README.pt-br.md#-run-on-old-android-phones) para instruções de configuração.
+> Veja [README: Rodar em celulares Android antigos](../project/README.pt-br.md#-run-on-old-android-phones) para instruções de configuração.
### Desktop / Servidor / Nuvem
diff --git a/docs/vi/hardware-compatibility.md b/docs/guides/hardware-compatibility.vi.md
similarity index 97%
rename from docs/vi/hardware-compatibility.md
rename to docs/guides/hardware-compatibility.vi.md
index 8315c049e..5566a4248 100644
--- a/docs/vi/hardware-compatibility.md
+++ b/docs/guides/hardware-compatibility.vi.md
@@ -1,4 +1,4 @@
-> Quay lại [README](../../README.vi.md)
+> Quay lại [README](../project/README.vi.md)
# 🖥️ PicoClaw Danh sách tương thích phần cứng
@@ -99,7 +99,7 @@ Sản phẩm tiêu dùng, router và thiết bị công nghiệp đã được k
Bất kỳ điện thoại Android ARM64 nào (2015+) với 1GB+ RAM. Cài đặt [Termux](https://github.com/termux/termux-app), sử dụng `proot` để chạy PicoClaw.
-> Xem [README: Chạy trên điện thoại Android cũ](../../README.vi.md#-run-on-old-android-phones) để biết hướng dẫn cài đặt.
+> Xem [README: Chạy trên điện thoại Android cũ](../project/README.vi.md#-run-on-old-android-phones) để biết hướng dẫn cài đặt.
### Desktop / Máy chủ / Đám mây
diff --git a/docs/zh/hardware-compatibility.md b/docs/guides/hardware-compatibility.zh.md
similarity index 97%
rename from docs/zh/hardware-compatibility.md
rename to docs/guides/hardware-compatibility.zh.md
index 66bd08072..d563f3ebe 100644
--- a/docs/zh/hardware-compatibility.md
+++ b/docs/guides/hardware-compatibility.zh.md
@@ -1,4 +1,4 @@
-> 返回 [README](../../README.zh.md)
+> 返回 [README](../project/README.zh.md)
# 🖥️ PicoClaw 硬件兼容性列表
@@ -99,7 +99,7 @@ PicoClaw 几乎可以在任何 Linux 设备上运行。本页面记录了已验
任何 ARM64 Android 手机（2015 年以后），1GB 以上内存。安装 [Termux](https://github.com/termux/termux-app)，使用 `proot` 运行 PicoClaw。
-> 参见 [README：在旧 Android 手机上运行](../../README.zh.md#-run-on-old-android-phones) 获取设置说明。
+> 参见 [README：在旧 Android 手机上运行](../project/README.zh.md#-run-on-old-android-phones) 获取设置说明。
### 桌面 / 服务器 / 云
diff --git a/docs/fr/providers.md b/docs/guides/providers.fr.md
similarity index 99%
rename from docs/fr/providers.md
rename to docs/guides/providers.fr.md
index f053d5d57..5e2700a01 100644
--- a/docs/fr/providers.md
+++ b/docs/guides/providers.fr.md
@@ -1,6 +1,6 @@
# 🔌 Fournisseurs et Configuration des Modèles
-> Retour au [README](../../README.fr.md)
+> Retour au [README](../project/README.fr.md)
### Fournisseurs
@@ -454,5 +454,5 @@ picoclaw agent -m "Hello"
---
-
+
-
+
-
+
-
+
-
+
-
+
PicoClaw : Assistant IA Ultra-Efficace en Go
@@ -14,11 +14,11 @@
-SipeedIO-black?style=flat&logo=x&logoColor=white)
-
+
-[中文](README.zh.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | **Français** | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | [English](README.md)
+[中文](README.zh.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt-br.md) | [Tiếng Việt](README.vi.md) | **Français** | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.ms.md) | [English](../../README.md)
|
-
+
|
-
+
|
@@ -72,7 +72,7 @@
2026-02-26 🎉 PicoClaw atteint **20K Stars** en seulement 17 jours ! L'orchestration automatique des channels et les interfaces de capacités sont disponibles.
-2026-02-16 🎉 PicoClaw dépasse 12K Stars en une semaine ! Rôles de mainteneurs communautaires et [Roadmap](ROADMAP.md) officiellement lancés.
+2026-02-16 🎉 PicoClaw dépasse 12K Stars en une semaine ! Rôles de mainteneurs communautaires et [Roadmap](../../ROADMAP.md) officiellement lancés.
2026-02-13 🎉 PicoClaw dépasse 5000 Stars en 4 jours ! Roadmap du projet et groupes de développeurs en cours.
@@ -110,14 +110,14 @@ _*Les builds récents peuvent utiliser 10-20 Mo en raison des fusions rapides de
| **Temps de démarrage**(cœur 0,8 GHz) | >500s | >30s | **<1s** |
| **Coût** | Mac Mini $599 | La plupart des cartes Linux ~$50 | **N'importe quelle carte Linux****à partir de $10** |
-
+
-> **[Liste de compatibilité matérielle](docs/fr/hardware-compatibility.md)** — Voir toutes les cartes testées, du RISC-V à $5 au Raspberry Pi en passant par les téléphones Android. Votre carte n'est pas listée ? Soumettez une PR !
+> **[Liste de compatibilité matérielle](../guides/hardware-compatibility.fr.md)** — Voir toutes les cartes testées, du RISC-V à $5 au Raspberry Pi en passant par les téléphones Android. Votre carte n'est pas listée ? Soumettez une PR !
-
+
## 🦾 Démonstration
@@ -131,9 +131,9 @@ _*Les builds récents peuvent utiliser 10-20 Mo en raison des fusions rapides de
Recherche Web & Apprentissage |
-
|
-
|
-
|
+
|
+
|
+
|
| Développer · Déployer · Mettre à l'échelle |
@@ -223,7 +223,7 @@ picoclaw-launcher
> ```
-
+
**Pour commencer :**
@@ -277,7 +277,7 @@ macOS peut bloquer `picoclaw-launcher` au premier lancement car il est télécha
**Étape 1 :** Double-cliquez sur `picoclaw-launcher`. Un avertissement de sécurité s'affiche :
-
+
> *"picoclaw-launcher" n'a pas pu être ouvert — Apple n'a pas pu vérifier que "picoclaw-launcher" ne contient pas de logiciel malveillant susceptible de nuire à votre Mac ou de compromettre votre confidentialité.*
@@ -285,7 +285,7 @@ macOS peut bloquer `picoclaw-launcher` au premier lancement car il est télécha
**Étape 2 :** Ouvrez **Réglages Système** → **Confidentialité et sécurité** → faites défiler jusqu'à la section **Sécurité** → cliquez sur **Ouvrir quand même** → confirmez en cliquant sur **Ouvrir quand même** dans la boîte de dialogue.
-
+
Après cette étape unique, `picoclaw-launcher` s'ouvrira normalement lors des lancements suivants.
@@ -301,7 +301,7 @@ picoclaw-launcher-tui
```
-
+
**Pour commencer :**
@@ -310,6 +310,7 @@ Utilisez les menus TUI pour : **1)** Configurer un Provider -> **2)** Configurer
Pour la documentation détaillée du TUI, voir [docs.picoclaw.io](https://docs.picoclaw.io).
+
### 📱 Android
Donnez une seconde vie à votre téléphone vieux de dix ans ! Transformez-le en assistant IA intelligent avec PicoClaw.
@@ -320,10 +321,10 @@ Aperçu :
@@ -347,7 +348,7 @@ termux-chroot ./picoclaw onboard # chroot fournit une arborescence Linux stand
Suivez ensuite la section Terminal Launcher ci-dessous pour terminer la configuration.
-
+
Pour les environnements minimaux où seul le binaire principal `picoclaw` est disponible (sans Launcher UI), vous pouvez tout configurer via la ligne de commande et un fichier de configuration JSON.
@@ -454,7 +455,7 @@ PicoClaw supporte plus de 30 providers LLM via la configuration `model_list`. Ut
}
```
-Pour les détails complets de configuration des providers, voir [Providers & Models](docs/fr/providers.md).
+Pour les détails complets de configuration des providers, voir [Providers & Models](../guides/providers.fr.md).
@@ -464,28 +465,28 @@ Parlez à votre PicoClaw via plus de 17 plateformes de messagerie :
| Channel | Configuration | Protocole | Docs |
|---------|---------------|-----------|------|
-| **Telegram** | Facile (token bot) | Long polling | [Guide](docs/channels/telegram/README.fr.md) |
-| **Discord** | Facile (token bot + intents) | WebSocket | [Guide](docs/channels/discord/README.fr.md) |
-| **WhatsApp** | Facile (scan QR ou URL bridge) | Natif / Bridge | [Guide](docs/fr/chat-apps.md#whatsapp) |
-| **Weixin** | Facile (scan QR natif) | iLink API | [Guide](docs/fr/chat-apps.md#weixin) |
-| **QQ** | Facile (AppID + AppSecret) | WebSocket | [Guide](docs/channels/qq/README.fr.md) |
-| **Slack** | Facile (token bot + app) | Socket Mode | [Guide](docs/channels/slack/README.fr.md) |
-| **Matrix** | Moyen (homeserver + token) | Sync API | [Guide](docs/channels/matrix/README.fr.md) |
-| **DingTalk** | Moyen (identifiants client) | Stream | [Guide](docs/channels/dingtalk/README.fr.md) |
-| **Feishu / Lark** | Moyen (App ID + Secret) | WebSocket/SDK | [Guide](docs/channels/feishu/README.fr.md) |
-| **LINE** | Moyen (identifiants + webhook) | Webhook | [Guide](docs/channels/line/README.fr.md) |
-| **WeCom** | Facile (QR login ou manuel) | WebSocket | [Guide](docs/channels/wecom/README.md) |
-| **IRC** | Moyen (serveur + pseudo) | Protocole IRC | [Guide](docs/fr/chat-apps.md#irc) |
-| **OneBot** | Moyen (URL WebSocket) | OneBot v11 | [Guide](docs/channels/onebot/README.fr.md) |
-| **MaixCam** | Facile (activer) | Socket TCP | [Guide](docs/channels/maixcam/README.fr.md) |
+| **Telegram** | Facile (token bot) | Long polling | [Guide](../channels/telegram/README.fr.md) |
+| **Discord** | Facile (token bot + intents) | WebSocket | [Guide](../channels/discord/README.fr.md) |
+| **WhatsApp** | Facile (scan QR ou URL bridge) | Natif / Bridge | [Guide](../guides/chat-apps.fr.md#whatsapp) |
+| **Weixin** | Facile (scan QR natif) | iLink API | [Guide](../guides/chat-apps.fr.md#weixin) |
+| **QQ** | Facile (AppID + AppSecret) | WebSocket | [Guide](../channels/qq/README.fr.md) |
+| **Slack** | Facile (token bot + app) | Socket Mode | [Guide](../channels/slack/README.fr.md) |
+| **Matrix** | Moyen (homeserver + token) | Sync API | [Guide](../channels/matrix/README.fr.md) |
+| **DingTalk** | Moyen (identifiants client) | Stream | [Guide](../channels/dingtalk/README.fr.md) |
+| **Feishu / Lark** | Moyen (App ID + Secret) | WebSocket/SDK | [Guide](../channels/feishu/README.fr.md) |
+| **LINE** | Moyen (identifiants + webhook) | Webhook | [Guide](../channels/line/README.fr.md) |
+| **WeCom** | Facile (QR login ou manuel) | WebSocket | [Guide](../channels/wecom/README.fr.md) |
+| **IRC** | Moyen (serveur + pseudo) | Protocole IRC | [Guide](../guides/chat-apps.fr.md#irc) |
+| **OneBot** | Moyen (URL WebSocket) | OneBot v11 | [Guide](../channels/onebot/README.fr.md) |
+| **MaixCam** | Facile (activer) | Socket TCP | [Guide](../channels/maixcam/README.fr.md) |
| **Pico** | Facile (activer) | Protocole natif | Intégré |
| **Pico Client** | Facile (URL WebSocket) | WebSocket | Intégré |
> Tous les channels basés sur webhook partagent un seul serveur HTTP Gateway (`gateway.host`:`gateway.port`, par défaut `127.0.0.1:18790`). Feishu utilise le mode WebSocket/SDK et n'utilise pas le serveur HTTP partagé.
-> La verbosité des logs est contrôlée par `gateway.log_level` (par défaut : `warn`). Valeurs supportées : `debug`, `info`, `warn`, `error`, `fatal`. Peut aussi être défini via `PICOCLAW_LOG_LEVEL`. Voir [Configuration](docs/fr/configuration.md#niveau-de-log-du-gateway) pour plus de détails.
+> La verbosité des logs est contrôlée par `gateway.log_level` (par défaut : `warn`). Valeurs supportées : `debug`, `info`, `warn`, `error`, `fatal`. Peut aussi être défini via `PICOCLAW_LOG_LEVEL`. Voir [Configuration](../guides/configuration.fr.md#niveau-de-log-du-gateway) pour plus de détails.
-Pour les instructions détaillées de configuration des channels, voir [Configuration des applications de chat](docs/fr/chat-apps.md).
+Pour les instructions détaillées de configuration des channels, voir [Configuration des applications de chat](../guides/chat-apps.fr.md).
## 🔧 Outils
@@ -505,7 +506,7 @@ PicoClaw peut effectuer des recherches sur le web pour fournir des informations
### ⚙️ Autres outils
-PicoClaw inclut des outils intégrés pour les opérations sur fichiers, l'exécution de code, la planification et plus encore. Voir [Configuration des outils](docs/fr/tools_configuration.md) pour les détails.
+PicoClaw inclut des outils intégrés pour les opérations sur fichiers, l'exécution de code, la planification et plus encore. Voir [Configuration des outils](../reference/tools_configuration.fr.md) pour les détails.
## 🎯 Skills
@@ -535,7 +536,7 @@ Ajoutez à votre `config.json` :
}
```
-Pour plus de détails, voir [Configuration des outils - Skills](docs/fr/tools_configuration.md#skills-tool).
+Pour plus de détails, voir [Configuration des outils - Skills](../reference/tools_configuration.fr.md#skills-tool).
## 🔗 MCP (Model Context Protocol)
@@ -558,9 +559,9 @@ PicoClaw supporte nativement [MCP](https://modelcontextprotocol.io/) — connect
}
```
-Pour la configuration MCP complète (transports stdio, SSE, HTTP, Tool Discovery), voir [Configuration des outils - MCP](docs/fr/tools_configuration.md#mcp-tool).
+Pour la configuration MCP complète (transports stdio, SSE, HTTP, Tool Discovery), voir [Configuration des outils - MCP](../reference/tools_configuration.fr.md#mcp-tool).
-## Rejoignez le réseau social des Agents
+## 
Rejoignez le réseau social des Agents
Connectez PicoClaw au réseau social des Agents simplement en envoyant un seul message via le CLI ou n'importe quelle application de chat intégrée.
@@ -601,23 +602,23 @@ Pour des guides détaillés au-delà de ce README :
| Sujet | Description |
|-------|-------------|
-| [Docker & Démarrage rapide](docs/fr/docker.md) | Configuration Docker Compose, modes Launcher/Agent |
-| [Applications de chat](docs/fr/chat-apps.md) | Guides de configuration pour les 17+ channels |
-| [Configuration](docs/fr/configuration.md) | Variables d'environnement, structure du workspace, sandbox de sécurité |
-| [Providers & Modèles](docs/fr/providers.md) | 30+ providers LLM, routage de modèles, configuration model_list |
-| [Spawn & Tâches asynchrones](docs/fr/spawn-tasks.md) | Tâches rapides, tâches longues avec spawn, orchestration de sous-agents asynchrones |
-| [Hooks](docs/hooks/README.md) | Système de hooks événementiels : observateurs, intercepteurs, hooks d'approbation |
-| [Steering](docs/steering.md) | Injecter des messages dans une boucle agent en cours d'exécution |
-| [SubTurn](docs/subturn.md) | Coordination de subagents, contrôle de concurrence, cycle de vie |
-| [Dépannage](docs/fr/troubleshooting.md) | Problèmes courants et solutions |
-| [Configuration des outils](docs/fr/tools_configuration.md) | Activation/désactivation par outil, politiques d'exécution, MCP, Skills |
-| [Compatibilité matérielle](docs/fr/hardware-compatibility.md) | Cartes testées, exigences minimales |
+| [Docker & Démarrage rapide](../guides/docker.fr.md) | Configuration Docker Compose, modes Launcher/Agent |
+| [Applications de chat](../guides/chat-apps.fr.md) | Guides de configuration pour les 17+ channels |
+| [Configuration](../guides/configuration.fr.md) | Variables d'environnement, structure du workspace, sandbox de sécurité |
+| [Providers & Modèles](../guides/providers.fr.md) | 30+ providers LLM, routage de modèles, configuration model_list |
+| [Spawn & Tâches asynchrones](../guides/spawn-tasks.fr.md) | Tâches rapides, tâches longues avec spawn, orchestration de sous-agents asynchrones |
+| [Hooks](../architecture/hooks/README.md) | Système de 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 |
+| [Dépannage](../operations/troubleshooting.fr.md) | Problèmes courants et solutions |
+| [Configuration des outils](../reference/tools_configuration.fr.md) | Activation/désactivation par outil, politiques d'exécution, MCP, Skills |
+| [Compatibilité matérielle](../guides/hardware-compatibility.fr.md) | Cartes testées, exigences minimales |
## 🤝 Contribuer & Roadmap
Les PRs sont les bienvenues ! Le code source est intentionnellement petit et lisible.
-Consultez notre [Roadmap communautaire](https://github.com/sipeed/picoclaw/issues/988) et [CONTRIBUTING.md](CONTRIBUTING.md) pour les directives.
+Consultez notre [Roadmap communautaire](https://github.com/sipeed/picoclaw/issues/988) et [CONTRIBUTING.md](../../CONTRIBUTING.md) pour les directives.
Groupe de développeurs en construction, rejoignez-le après votre première PR fusionnée !
@@ -626,4 +627,4 @@ Groupes d'utilisateurs :
Discord :
WeChat :
-
+
diff --git a/README.id.md b/docs/project/README.id.md
similarity index 83%
rename from README.id.md
rename to docs/project/README.id.md
index 525d4dc72..244e6e49a 100644
--- a/README.id.md
+++ b/docs/project/README.id.md
@@ -1,5 +1,5 @@
-
+
PicoClaw: Asisten AI Super Ringan berbasis Go
@@ -14,11 +14,11 @@
-
+
-[中文](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** | [Malay](README.my.md) | [English](README.md)
+[中文](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** | [Malay](README.ms.md) | [English](../../README.md)
|
-
+
|
-
+
|
@@ -71,7 +71,7 @@
2026-02-26 🎉 PicoClaw mencapai **20K Stars** hanya dalam 17 hari! Orkestrasi channel otomatis dan antarmuka kapabilitas kini aktif.
-2026-02-16 🎉 PicoClaw menembus 12K Stars dalam satu minggu! Peran maintainer komunitas dan [Roadmap](ROADMAP.md) resmi diluncurkan.
+2026-02-16 🎉 PicoClaw menembus 12K Stars dalam satu minggu! Peran maintainer komunitas dan [Roadmap](../../ROADMAP.md) resmi diluncurkan.
2026-02-13 🎉 PicoClaw menembus 5000 Stars dalam 4 hari! Roadmap proyek dan grup pengembang sedang dalam proses.
@@ -108,14 +108,14 @@ _*Build terbaru mungkin menggunakan 10-20MB karena penggabungan PR yang cepat. O
| **Waktu Boot**(core 0,8GHz) | >500d | >30d | **<1d** |
| **Biaya** | Mac Mini $599 | Kebanyakan board Linux ~$50 | **Board Linux mana pun****mulai $10** |
-
+
-> **[Daftar Kompatibilitas Hardware](docs/hardware-compatibility.md)** — Lihat semua board yang telah diuji, dari RISC-V $5 hingga Raspberry Pi hingga ponsel Android. Board Anda belum terdaftar? Kirim PR!
+> **[Daftar Kompatibilitas Hardware](../guides/hardware-compatibility.md)** — Lihat semua board yang telah diuji, dari RISC-V $5 hingga Raspberry Pi hingga ponsel Android. Board Anda belum terdaftar? Kirim PR!
-
+
## 🦾 Demonstrasi
@@ -129,9 +129,9 @@ _*Build terbaru mungkin menggunakan 10-20MB karena penggabungan PR yang cepat. O
Pencarian Web & Pembelajaran |
-
|
-
|
-
|
+
|
+
|
+
|
| Develop · Deploy · Scale |
@@ -220,7 +220,7 @@ picoclaw-launcher
> ```
-
+
**Memulai:**
@@ -274,7 +274,7 @@ macOS mungkin memblokir `picoclaw-launcher` saat pertama kali diluncurkan karena
**Langkah 1:** Klik dua kali `picoclaw-launcher`. Anda akan melihat peringatan keamanan:
-
+
> *"picoclaw-launcher" Tidak Dapat Dibuka — Apple tidak dapat memverifikasi bahwa "picoclaw-launcher" bebas dari malware yang dapat membahayakan Mac Anda atau mengancam privasi Anda.*
@@ -282,7 +282,7 @@ macOS mungkin memblokir `picoclaw-launcher` saat pertama kali diluncurkan karena
**Langkah 2:** Buka **Pengaturan Sistem** → **Privasi & Keamanan** → gulir ke bawah ke bagian **Keamanan** → klik **Tetap Buka** → konfirmasi dengan mengklik **Tetap Buka** pada dialog.
-
+
Setelah langkah satu kali ini, `picoclaw-launcher` akan terbuka secara normal pada peluncuran berikutnya.
@@ -298,7 +298,7 @@ picoclaw-launcher-tui
```
-
+
**Memulai:**
@@ -317,10 +317,10 @@ Pratinjau:
@@ -344,7 +344,7 @@ termux-chroot ./picoclaw onboard # chroot menyediakan tata letak filesystem Li
Kemudian ikuti bagian Terminal Launcher di bawah untuk menyelesaikan konfigurasi.
-
+
Untuk lingkungan minimal di mana hanya binary inti `picoclaw` yang tersedia (tanpa Launcher UI), Anda dapat mengonfigurasi semuanya melalui command line dan file konfigurasi JSON.
@@ -450,7 +450,7 @@ PicoClaw mendukung 30+ provider LLM melalui konfigurasi `model_list`. Gunakan fo
}
```
-Untuk detail konfigurasi provider lengkap, lihat [Providers & Models](docs/providers.md).
+Untuk detail konfigurasi provider lengkap, lihat [Providers & Models](../guides/providers.md).
@@ -460,28 +460,28 @@ Bicara dengan PicoClaw Anda melalui 17+ platform pesan:
| Channel | Pengaturan | Protocol | Dokumentasi |
|---------|------------|----------|-------------|
-| **Telegram** | Mudah (bot token) | Long polling | [Panduan](docs/channels/telegram/README.md) |
-| **Discord** | Mudah (bot token + intents) | WebSocket | [Panduan](docs/channels/discord/README.md) |
-| **WhatsApp** | Mudah (scan QR atau bridge URL) | Native / Bridge | [Panduan](docs/chat-apps.md#whatsapp) |
-| **Weixin** | Mudah (scan QR native) | iLink API | [Panduan](docs/chat-apps.md#weixin) |
-| **QQ** | Mudah (AppID + AppSecret) | WebSocket | [Panduan](docs/channels/qq/README.md) |
-| **Slack** | Mudah (bot + app token) | Socket Mode | [Panduan](docs/channels/slack/README.md) |
-| **Matrix** | Sedang (homeserver + token) | Sync API | [Panduan](docs/channels/matrix/README.md) |
-| **DingTalk** | Sedang (client credentials) | Stream | [Panduan](docs/channels/dingtalk/README.md) |
-| **Feishu / Lark** | Sedang (App ID + Secret) | WebSocket/SDK | [Panduan](docs/channels/feishu/README.md) |
-| **LINE** | Sedang (credentials + webhook) | Webhook | [Panduan](docs/channels/line/README.md) |
-| **WeCom** | Mudah (login QR atau manual) | WebSocket | [Panduan](docs/channels/wecom/README.md) |
-| **IRC** | Sedang (server + nick) | IRC protocol | [Panduan](docs/chat-apps.md#irc) |
-| **OneBot** | Sedang (WebSocket URL) | OneBot v11 | [Panduan](docs/channels/onebot/README.md) |
-| **MaixCam** | Mudah (aktifkan) | TCP socket | [Panduan](docs/channels/maixcam/README.md) |
+| **Telegram** | Mudah (bot token) | Long polling | [Panduan](../channels/telegram/README.md) |
+| **Discord** | Mudah (bot token + intents) | WebSocket | [Panduan](../channels/discord/README.md) |
+| **WhatsApp** | Mudah (scan QR atau bridge URL) | Native / Bridge | [Panduan](../guides/chat-apps.md#whatsapp) |
+| **Weixin** | Mudah (scan QR native) | iLink API | [Panduan](../guides/chat-apps.md#weixin) |
+| **QQ** | Mudah (AppID + AppSecret) | WebSocket | [Panduan](../channels/qq/README.md) |
+| **Slack** | Mudah (bot + app token) | Socket Mode | [Panduan](../channels/slack/README.md) |
+| **Matrix** | Sedang (homeserver + token) | Sync API | [Panduan](../channels/matrix/README.md) |
+| **DingTalk** | Sedang (client credentials) | Stream | [Panduan](../channels/dingtalk/README.md) |
+| **Feishu / Lark** | Sedang (App ID + Secret) | WebSocket/SDK | [Panduan](../channels/feishu/README.md) |
+| **LINE** | Sedang (credentials + webhook) | Webhook | [Panduan](../channels/line/README.md) |
+| **WeCom** | Mudah (login QR atau manual) | WebSocket | [Panduan](../channels/wecom/README.md) |
+| **IRC** | Sedang (server + nick) | IRC protocol | [Panduan](../guides/chat-apps.md#irc) |
+| **OneBot** | Sedang (WebSocket URL) | OneBot v11 | [Panduan](../channels/onebot/README.md) |
+| **MaixCam** | Mudah (aktifkan) | TCP socket | [Panduan](../channels/maixcam/README.md) |
| **Pico** | Mudah (aktifkan) | Native protocol | Bawaan |
| **Pico Client** | Mudah (WebSocket URL) | WebSocket | Bawaan |
> Semua channel berbasis webhook berbagi satu server HTTP Gateway (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). Feishu menggunakan mode WebSocket/SDK dan tidak menggunakan server HTTP bersama.
-> Verbositas log dikontrol oleh `gateway.log_level` (default: `warn`). Nilai yang didukung: `debug`, `info`, `warn`, `error`, `fatal`. Juga dapat diatur melalui `PICOCLAW_LOG_LEVEL`. Lihat [Konfigurasi](docs/configuration.md#gateway-log-level) untuk detail.
+> Verbositas log dikontrol oleh `gateway.log_level` (default: `warn`). Nilai yang didukung: `debug`, `info`, `warn`, `error`, `fatal`. Juga dapat diatur melalui `PICOCLAW_LOG_LEVEL`. Lihat [Konfigurasi](../guides/configuration.md#gateway-log-level) untuk detail.
-Untuk instruksi pengaturan channel lengkap, lihat [Konfigurasi Aplikasi Chat](docs/chat-apps.md).
+Untuk instruksi pengaturan channel lengkap, lihat [Konfigurasi Aplikasi Chat](../guides/chat-apps.md).
## 🔧 Tools
@@ -501,7 +501,7 @@ PicoClaw dapat mencari web untuk memberikan informasi terkini. Konfigurasi di `t
### ⚙️ Tools Lainnya
-PicoClaw menyertakan tools bawaan untuk operasi file, eksekusi kode, penjadwalan, dan lainnya. Lihat [Konfigurasi Tools](docs/tools_configuration.md) untuk detail.
+PicoClaw menyertakan tools bawaan untuk operasi file, eksekusi kode, penjadwalan, dan lainnya. Lihat [Konfigurasi Tools](../reference/tools_configuration.md) untuk detail.
## 🎯 Skills
@@ -531,7 +531,7 @@ Tambahkan ke `config.json` Anda:
}
```
-Untuk detail lebih lanjut, lihat [Konfigurasi Tools - Skills](docs/tools_configuration.md#skills-tool).
+Untuk detail lebih lanjut, lihat [Konfigurasi Tools - Skills](../reference/tools_configuration.md#skills-tool).
## 🔗 MCP (Model Context Protocol)
@@ -554,9 +554,9 @@ PicoClaw mendukung [MCP](https://modelcontextprotocol.io/) secara native — hub
}
```
-Untuk konfigurasi MCP lengkap (transport stdio, SSE, HTTP, Tool Discovery), lihat [Konfigurasi Tools - MCP](docs/tools_configuration.md#mcp-tool).
+Untuk konfigurasi MCP lengkap (transport stdio, SSE, HTTP, Tool Discovery), lihat [Konfigurasi Tools - MCP](../reference/tools_configuration.md#mcp-tool).
-## Bergabung dengan Jaringan Sosial Agent
+## Bergabung dengan Jaringan Sosial Agent
Hubungkan PicoClaw ke Jaringan Sosial Agent hanya dengan mengirim satu pesan melalui CLI atau Aplikasi Chat terintegrasi mana pun.
@@ -597,23 +597,23 @@ Untuk panduan lengkap di luar README ini:
| Topik | Deskripsi |
|-------|-----------|
-| [Docker & Panduan Cepat](docs/docker.md) | Pengaturan Docker Compose, mode Launcher/Agent |
-| [Aplikasi Chat](docs/chat-apps.md) | Semua 17+ panduan pengaturan channel |
-| [Konfigurasi](docs/configuration.md) | Variabel environment, tata letak workspace, sandbox keamanan |
-| [Providers & Models](docs/providers.md) | 30+ provider LLM, routing model, konfigurasi model_list |
-| [Spawn & Tugas Async](docs/spawn-tasks.md) | Tugas cepat, tugas panjang dengan spawn, orkestrasi sub-agent async |
-| [Hooks](docs/hooks/README.md) | Sistem hook berbasis event: observer, interceptor, approval hook |
-| [Steering](docs/steering.md) | Menyuntikkan pesan ke dalam loop agent yang sedang berjalan |
-| [SubTurn](docs/subturn.md) | Koordinasi subagent, kontrol konkurensi, siklus hidup |
-| [Pemecahan Masalah](docs/troubleshooting.md) | Masalah umum dan solusinya |
-| [Konfigurasi Tools](docs/tools_configuration.md) | Aktifkan/nonaktifkan per-tool, kebijakan exec, MCP, Skills |
-| [Kompatibilitas Hardware](docs/hardware-compatibility.md) | Board yang telah diuji, persyaratan minimum |
+| [Docker & Panduan Cepat](../guides/docker.md) | Pengaturan Docker Compose, mode Launcher/Agent |
+| [Aplikasi Chat](../guides/chat-apps.md) | Semua 17+ panduan pengaturan channel |
+| [Konfigurasi](../guides/configuration.md) | Variabel environment, tata letak workspace, sandbox keamanan |
+| [Providers & Models](../guides/providers.md) | 30+ provider LLM, routing model, konfigurasi model_list |
+| [Spawn & Tugas Async](../guides/spawn-tasks.md) | Tugas cepat, tugas panjang dengan spawn, orkestrasi sub-agent async |
+| [Hooks](../architecture/hooks/README.md) | Sistem hook berbasis event: observer, interceptor, approval hook |
+| [Steering](../architecture/steering.md) | Menyuntikkan pesan ke dalam loop agent yang sedang berjalan |
+| [SubTurn](../architecture/subturn.md) | Koordinasi subagent, kontrol konkurensi, siklus hidup |
+| [Pemecahan Masalah](../operations/troubleshooting.md) | Masalah umum dan solusinya |
+| [Konfigurasi Tools](../reference/tools_configuration.md) | Aktifkan/nonaktifkan per-tool, kebijakan exec, MCP, Skills |
+| [Kompatibilitas Hardware](../guides/hardware-compatibility.md) | Board yang telah diuji, persyaratan minimum |
## 🤝 Kontribusi & Roadmap
PR sangat diterima! Codebase sengaja dibuat kecil dan mudah dibaca.
-Lihat [Roadmap Komunitas](https://github.com/sipeed/picoclaw/issues/988) dan [CONTRIBUTING.md](CONTRIBUTING.md) untuk panduan.
+Lihat [Roadmap Komunitas](https://github.com/sipeed/picoclaw/issues/988) dan [CONTRIBUTING.md](../../CONTRIBUTING.md) untuk panduan.
Grup pengembang sedang dibangun, bergabunglah setelah PR pertama Anda di-merge!
@@ -622,4 +622,4 @@ Grup Pengguna:
Discord:
WeChat:
-
+
diff --git a/README.it.md b/docs/project/README.it.md
similarity index 82%
rename from README.it.md
rename to docs/project/README.it.md
index c560976cf..eb2f7c95b 100644
--- a/README.it.md
+++ b/docs/project/README.it.md
@@ -1,5 +1,5 @@
-
+
PicoClaw: Assistente IA Ultra-Efficiente in Go
@@ -14,11 +14,11 @@
-
+
-[中文](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** | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | [English](README.md)
+[中文](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** | [Bahasa Indonesia](README.id.md) | [Malay](README.ms.md) | [English](../../README.md)
|
-
+
|
-
+
|
@@ -71,7 +71,7 @@
2026-02-26 🎉 PicoClaw raggiunge **20K stelle** in soli 17 giorni! Orchestrazione automatica dei canali e interfacce di capacità sono attive.
-2026-02-16 🎉 PicoClaw supera 12K stelle in una settimana! Ruoli di maintainer della community e [Roadmap](ROADMAP.md) pubblicati ufficialmente.
+2026-02-16 🎉 PicoClaw supera 12K stelle in una settimana! Ruoli di maintainer della community e [Roadmap](../../ROADMAP.md) pubblicati ufficialmente.
2026-02-13 🎉 PicoClaw supera 5000 stelle in 4 giorni! Roadmap del progetto e gruppi sviluppatori in fase di avvio.
@@ -108,14 +108,14 @@ _*Le build recenti potrebbero usare 10-20MB a causa delle fusioni rapide di PR.
| **Avvio**(core 0,8 GHz) | >500s | >30s | **<1s** |
| **Costo** | Mac Mini $599 | La maggior parte degli SBC Linux ~$50 | **Qualsiasi scheda Linux****a partire da $10** |
-
+
-> **[Lista di Compatibilità Hardware](docs/hardware-compatibility.md)** — Vedi tutte le schede testate, dai $5 RISC-V al Raspberry Pi ai telefoni Android. La tua scheda non è elencata? Invia una PR!
+> **[Lista di Compatibilità Hardware](../guides/hardware-compatibility.md)** — Vedi tutte le schede testate, dai $5 RISC-V al Raspberry Pi ai telefoni Android. La tua scheda non è elencata? Invia una PR!
-
+
## 🦾 Dimostrazione
@@ -129,9 +129,9 @@ _*Le build recenti potrebbero usare 10-20MB a causa delle fusioni rapide di PR.
Ricerca Web & Apprendimento |
-
|
-
|
-
|
+
|
+
|
+
|
| Sviluppa · Distribuisci · Scala |
@@ -220,7 +220,7 @@ picoclaw-launcher
> ```
-
+
**Per iniziare:**
@@ -274,7 +274,7 @@ macOS potrebbe bloccare `picoclaw-launcher` al primo avvio perché è stato scar
**Passo 1:** Fai doppio clic su `picoclaw-launcher`. Verrà visualizzato un avviso di sicurezza:
-
+
> *"picoclaw-launcher" Non Aperto — Apple non è riuscita a verificare che "picoclaw-launcher" sia privo di malware che potrebbe danneggiare il Mac o compromettere la privacy.*
@@ -282,7 +282,7 @@ macOS potrebbe bloccare `picoclaw-launcher` al primo avvio perché è stato scar
**Passo 2:** Apri **Impostazioni di Sistema** → **Privacy e sicurezza** → scorri fino alla sezione **Sicurezza** → clicca su **Apri comunque** → conferma cliccando su **Apri comunque** nella finestra di dialogo.
-
+
Dopo questo passaggio una tantum, `picoclaw-launcher` si aprirà normalmente ai lanci successivi.
@@ -298,7 +298,7 @@ picoclaw-launcher-tui
```
-
+
**Per iniziare:**
@@ -317,10 +317,10 @@ Anteprima:
@@ -344,7 +344,7 @@ termux-chroot ./picoclaw onboard # chroot fornisce un layout standard del file
Poi segui la sezione Terminal Launcher qui sotto per completare la configurazione.
-
+
Per ambienti minimali dove è disponibile solo il binario core `picoclaw` (senza Launcher UI), puoi configurare tutto tramite riga di comando e un file di configurazione JSON.
@@ -450,7 +450,7 @@ PicoClaw supporta 30+ provider LLM tramite la configurazione `model_list`. Usa i
}
```
-Per i dettagli completi sulla configurazione dei provider, vedi [Provider & Modelli](docs/providers.md).
+Per i dettagli completi sulla configurazione dei provider, vedi [Provider & Modelli](../guides/providers.md).
@@ -460,28 +460,28 @@ Parla con il tuo PicoClaw attraverso 17+ piattaforme di messaggistica:
| Channel | Configurazione | Protocollo | Docs |
|---------|----------------|------------|------|
-| **Telegram** | Facile (bot token) | Long polling | [Guida](docs/channels/telegram/README.md) |
-| **Discord** | Facile (bot token + intents) | WebSocket | [Guida](docs/channels/discord/README.md) |
-| **WhatsApp** | Facile (QR scan o bridge URL) | Nativo / Bridge | [Guida](docs/chat-apps.md#whatsapp) |
-| **Weixin** | Facile (scan QR nativo) | iLink API | [Guida](docs/chat-apps.md#weixin) |
-| **QQ** | Facile (AppID + AppSecret) | WebSocket | [Guida](docs/channels/qq/README.md) |
-| **Slack** | Facile (bot + app token) | Socket Mode | [Guida](docs/channels/slack/README.md) |
-| **Matrix** | Medio (homeserver + token) | Sync API | [Guida](docs/channels/matrix/README.md) |
-| **DingTalk** | Medio (credenziali client) | Stream | [Guida](docs/channels/dingtalk/README.md) |
-| **Feishu / Lark** | Medio (App ID + Secret) | WebSocket/SDK | [Guida](docs/channels/feishu/README.md) |
-| **LINE** | Medio (credenziali + webhook) | Webhook | [Guida](docs/channels/line/README.md) |
-| **WeCom** | Facile (login QR o manuale) | WebSocket | [Guida](docs/channels/wecom/README.md) |
-| **IRC** | Medio (server + nick) | Protocollo IRC | [Guida](docs/chat-apps.md#irc) |
-| **OneBot** | Medio (WebSocket URL) | OneBot v11 | [Guida](docs/channels/onebot/README.md) |
-| **MaixCam** | Facile (abilita) | TCP socket | [Guida](docs/channels/maixcam/README.md) |
+| **Telegram** | Facile (bot token) | Long polling | [Guida](../channels/telegram/README.md) |
+| **Discord** | Facile (bot token + intents) | WebSocket | [Guida](../channels/discord/README.md) |
+| **WhatsApp** | Facile (QR scan o bridge URL) | Nativo / Bridge | [Guida](../guides/chat-apps.md#whatsapp) |
+| **Weixin** | Facile (scan QR nativo) | iLink API | [Guida](../guides/chat-apps.md#weixin) |
+| **QQ** | Facile (AppID + AppSecret) | WebSocket | [Guida](../channels/qq/README.md) |
+| **Slack** | Facile (bot + app token) | Socket Mode | [Guida](../channels/slack/README.md) |
+| **Matrix** | Medio (homeserver + token) | Sync API | [Guida](../channels/matrix/README.md) |
+| **DingTalk** | Medio (credenziali client) | Stream | [Guida](../channels/dingtalk/README.md) |
+| **Feishu / Lark** | Medio (App ID + Secret) | WebSocket/SDK | [Guida](../channels/feishu/README.md) |
+| **LINE** | Medio (credenziali + webhook) | Webhook | [Guida](../channels/line/README.md) |
+| **WeCom** | Facile (login QR o manuale) | WebSocket | [Guida](../channels/wecom/README.md) |
+| **IRC** | Medio (server + nick) | Protocollo IRC | [Guida](../guides/chat-apps.md#irc) |
+| **OneBot** | Medio (WebSocket URL) | OneBot v11 | [Guida](../channels/onebot/README.md) |
+| **MaixCam** | Facile (abilita) | TCP socket | [Guida](../channels/maixcam/README.md) |
| **Pico** | Facile (abilita) | Protocollo nativo | Integrato |
| **Pico Client** | Facile (WebSocket URL) | WebSocket | Integrato |
> Tutti i channel basati su webhook condividono un singolo server HTTP Gateway (`gateway.host`:`gateway.port`, default `127.0.0.1:18790`). Feishu usa la modalità WebSocket/SDK e non usa il server HTTP condiviso.
-> La verbosità dei log è controllata da `gateway.log_level` (default: `warn`). Valori supportati: `debug`, `info`, `warn`, `error`, `fatal`. Può essere impostato anche tramite `PICOCLAW_LOG_LEVEL`. Vedi [Configurazione](docs/configuration.md#gateway-log-level) per i dettagli.
+> La verbosità dei log è controllata da `gateway.log_level` (default: `warn`). Valori supportati: `debug`, `info`, `warn`, `error`, `fatal`. Può essere impostato anche tramite `PICOCLAW_LOG_LEVEL`. Vedi [Configurazione](../guides/configuration.md#gateway-log-level) per i dettagli.
-Per istruzioni dettagliate sulla configurazione dei channel, vedi [Configurazione App di Chat](docs/chat-apps.md).
+Per istruzioni dettagliate sulla configurazione dei channel, vedi [Configurazione App di Chat](../guides/chat-apps.md).
## 🔧 Strumenti
@@ -501,7 +501,7 @@ PicoClaw può cercare sul web per fornire informazioni aggiornate. Configura in
### ⚙️ Altri Strumenti
-PicoClaw include strumenti integrati per operazioni su file, esecuzione di codice, pianificazione e altro. Vedi [Configurazione degli Strumenti](docs/tools_configuration.md) per i dettagli.
+PicoClaw include strumenti integrati per operazioni su file, esecuzione di codice, pianificazione e altro. Vedi [Configurazione degli Strumenti](../reference/tools_configuration.md) per i dettagli.
## 🎯 Skill
@@ -531,7 +531,7 @@ Aggiungi al tuo `config.json`:
}
```
-Per maggiori dettagli, vedi [Configurazione degli Strumenti - Skill](docs/tools_configuration.md#skills-tool).
+Per maggiori dettagli, vedi [Configurazione degli Strumenti - Skill](../reference/tools_configuration.md#skills-tool).
## 🔗 MCP (Model Context Protocol)
@@ -554,9 +554,9 @@ PicoClaw supporta nativamente [MCP](https://modelcontextprotocol.io/) — connet
}
```
-Per la configurazione MCP completa (trasporti stdio, SSE, HTTP, Tool Discovery), vedi [Configurazione degli Strumenti - MCP](docs/tools_configuration.md#mcp-tool).
+Per la configurazione MCP completa (trasporti stdio, SSE, HTTP, Tool Discovery), vedi [Configurazione degli Strumenti - MCP](../reference/tools_configuration.md#mcp-tool).
-## Unisciti al Social Network degli Agent
+## Unisciti al Social Network degli Agent
Connetti PicoClaw al Social Network degli Agent semplicemente inviando un singolo messaggio tramite CLI o qualsiasi app di chat integrata.
@@ -597,23 +597,23 @@ Per guide dettagliate oltre questo README:
| Argomento | Descrizione |
|-----------|-------------|
-| [Docker & Avvio Rapido](docs/docker.md) | Configurazione Docker Compose, modalità Launcher/Agent |
-| [App di Chat](docs/chat-apps.md) | Tutte le guide di configurazione per 17+ channel |
-| [Configurazione](docs/configuration.md) | Variabili d'ambiente, struttura del workspace, sandbox di sicurezza |
-| [Provider & Modelli](docs/providers.md) | 30+ provider LLM, routing dei modelli, configurazione model_list |
-| [Spawn & Task Asincroni](docs/spawn-tasks.md) | Task veloci, task lunghi con spawn, orchestrazione asincrona di sub-agent |
-| [Hooks](docs/hooks/README.md) | Sistema di hook event-driven: observer, interceptor, approval hook |
-| [Steering](docs/steering.md) | Iniettare messaggi in un loop agent in esecuzione |
-| [SubTurn](docs/subturn.md) | Coordinamento subagent, controllo concorrenza, ciclo di vita |
-| [Risoluzione Problemi](docs/troubleshooting.md) | Problemi comuni e soluzioni |
-| [Configurazione degli Strumenti](docs/tools_configuration.md) | Abilitazione/disabilitazione per strumento, politiche exec, MCP, Skill |
-| [Compatibilità Hardware](docs/hardware-compatibility.md) | Schede testate, requisiti minimi |
+| [Docker & Avvio Rapido](../guides/docker.md) | Configurazione Docker Compose, modalità Launcher/Agent |
+| [App di Chat](../guides/chat-apps.md) | Tutte le guide di configurazione per 17+ channel |
+| [Configurazione](../guides/configuration.md) | Variabili d'ambiente, struttura del workspace, sandbox di sicurezza |
+| [Provider & Modelli](../guides/providers.md) | 30+ provider LLM, routing dei modelli, configurazione model_list |
+| [Spawn & Task Asincroni](../guides/spawn-tasks.md) | Task veloci, task lunghi con spawn, orchestrazione asincrona di sub-agent |
+| [Hooks](../architecture/hooks/README.md) | Sistema di hook event-driven: observer, interceptor, approval hook |
+| [Steering](../architecture/steering.md) | Iniettare messaggi in un loop agent in esecuzione |
+| [SubTurn](../architecture/subturn.md) | Coordinamento subagent, controllo concorrenza, ciclo di vita |
+| [Risoluzione Problemi](../operations/troubleshooting.md) | Problemi comuni e soluzioni |
+| [Configurazione degli Strumenti](../reference/tools_configuration.md) | Abilitazione/disabilitazione per strumento, politiche exec, MCP, Skill |
+| [Compatibilità Hardware](../guides/hardware-compatibility.md) | Schede testate, requisiti minimi |
## 🤝 Contribuisci & Roadmap
Le PR sono benvenute! Il codice è volutamente piccolo e leggibile.
-Consulta la nostra [Roadmap della Community](https://github.com/sipeed/picoclaw/issues/988) e [CONTRIBUTING.md](CONTRIBUTING.md) per le linee guida.
+Consulta la nostra [Roadmap della Community](https://github.com/sipeed/picoclaw/issues/988) e [CONTRIBUTING.md](../../CONTRIBUTING.md) per le linee guida.
Gruppo sviluppatori in costruzione, unisciti dopo la tua prima PR accettata!
@@ -622,4 +622,4 @@ Gruppi utenti:
Discord:
WeChat:
-
+
diff --git a/README.ja.md b/docs/project/README.ja.md
similarity index 84%
rename from README.ja.md
rename to docs/project/README.ja.md
index d09eb436d..66d06ba5e 100644
--- a/README.ja.md
+++ b/docs/project/README.ja.md
@@ -1,5 +1,5 @@
-
+
PicoClaw: Go で書かれた超効率 AI アシスタント
@@ -14,11 +14,11 @@
-
+
-[中文](README.zh.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](README.md)
+[中文](README.zh.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.ms.md) | [English](../../README.md)
|
-
+
|
-
+
|
@@ -71,7 +71,7 @@
2026-02-26 🎉 PicoClaw がわずか 17 日で **20K スター** 達成！Channel 自動オーケストレーションとケイパビリティインターフェースが実装されました。
-2026-02-16 🎉 PicoClaw が 1 週間で 12K スター達成！コミュニティメンテナーの役割と[ロードマップ](ROADMAP.md)が正式に公開されました。
+2026-02-16 🎉 PicoClaw が 1 週間で 12K スター達成！コミュニティメンテナーの役割と[ロードマップ](../../ROADMAP.md)が正式に公開されました。
2026-02-13 🎉 PicoClaw が 4 日間で 5000 スター達成！プロジェクトロードマップと開発者グループの準備が進行中。
@@ -108,14 +108,14 @@ _*最近のバージョンでは急速な PR マージにより 10〜20MB にな
| **起動時間**(0.8GHz コア) | >500秒 | >30秒 | **<1秒** |
| **コスト** | Mac Mini $599 | 大半の Linux ボード ~$50 | **あらゆる Linux ボード****最安 $10** |
-
+
-> **[ハードウェア互換性リスト](docs/ja/hardware-compatibility.md)** — テスト済みの全ボード一覧（$5 RISC-V から Raspberry Pi、Android スマートフォンまで）。お使いのボードが未掲載？PR を送ってください！
+> **[ハードウェア互換性リスト](../guides/hardware-compatibility.ja.md)** — テスト済みの全ボード一覧（$5 RISC-V から Raspberry Pi、Android スマートフォンまで）。お使いのボードが未掲載？PR を送ってください！
-
+
## 🦾 デモンストレーション
@@ -129,9 +129,9 @@ _*最近のバージョンでは急速な PR マージにより 10〜20MB にな
Web 検索＆学習 |
-
|
-
|
-
|
+
|
+
|
+
|
| 開発 · デプロイ · スケール |
@@ -220,7 +220,7 @@ picoclaw-launcher
> ```
-
+
**始め方:**
@@ -274,7 +274,7 @@ docker compose -f docker/docker-compose.yml --profile launcher up -d
**ステップ 1：** `picoclaw-launcher` をダブルクリックすると、セキュリティ警告が表示されます：
-
+
> *"picoclaw-launcher" は開けません — "picoclaw-launcher" がMacに害を与えたりプライバシーを侵害するマルウェアを含まないことをAppleは確認できません。*
@@ -282,7 +282,7 @@ docker compose -f docker/docker-compose.yml --profile launcher up -d
**ステップ 2：** **システム設定** → **プライバシーとセキュリティ** を開き、**セキュリティ** セクションまでスクロールして **このまま開く** をクリック → ダイアログで再度 **開く** をクリックします。
-
+
この操作を一度行うと、以降の起動では警告が表示されなくなります。
@@ -298,7 +298,7 @@ picoclaw-launcher-tui
```
-
+
**始め方:**
@@ -307,6 +307,7 @@ TUI メニューを使って：**1)** Provider を設定 → **2)** Channel を
TUI の詳細なドキュメントは [docs.picoclaw.io](https://docs.picoclaw.io) を参照してください。
+
### 📱 Android
10 年前のスマホに第二の人生を！PicoClaw でスマート AI アシスタントに変身させましょう。
@@ -317,10 +318,10 @@ TUI の詳細なドキュメントは [docs.picoclaw.io](https://docs.picoclaw.i
@@ -344,7 +345,7 @@ termux-chroot ./picoclaw onboard # chroot で標準的な Linux ファイル
その後、下記の Terminal Launcher セクションの手順に従って設定を完了してください。
-
+
`picoclaw` コアバイナリのみが利用可能な最小環境（Launcher UI なし）では、コマンドラインと JSON 設定ファイルですべてを設定できます。
@@ -450,7 +451,7 @@ PicoClaw は `model_list` 設定を通じて 30 以上の LLM Provider をサポ
}
```
-Provider の完全な設定詳細は [Provider とモデル](docs/ja/providers.md) を参照してください。
+Provider の完全な設定詳細は [Provider とモデル](../guides/providers.ja.md) を参照してください。
@@ -460,28 +461,28 @@ Provider の完全な設定詳細は [Provider とモデル](docs/ja/providers.m
| Channel | セットアップ | Protocol | ドキュメント |
|---------|------------|----------|------------|
-| **Telegram** | 簡単（bot トークン） | Long polling | [ガイド](docs/channels/telegram/README.ja.md) |
-| **Discord** | 簡単（bot トークン + intents） | WebSocket | [ガイド](docs/channels/discord/README.ja.md) |
-| **WhatsApp** | 簡単（QR スキャンまたは bridge URL） | Native / Bridge | [ガイド](docs/ja/chat-apps.md#whatsapp) |
-| **微信 (Weixin)** | 簡単（QR スキャン） | iLink API | [ガイド](docs/ja/chat-apps.md#weixin) |
-| **QQ** | 簡単（AppID + AppSecret） | WebSocket | [ガイド](docs/channels/qq/README.ja.md) |
-| **Slack** | 簡単（bot + app トークン） | Socket Mode | [ガイド](docs/channels/slack/README.ja.md) |
-| **Matrix** | 中級（homeserver + トークン） | Sync API | [ガイド](docs/channels/matrix/README.ja.md) |
-| **DingTalk** | 中級（クライアント認証情報） | Stream | [ガイド](docs/channels/dingtalk/README.ja.md) |
-| **Feishu / Lark** | 中級（App ID + Secret） | WebSocket/SDK | [ガイド](docs/channels/feishu/README.ja.md) |
-| **LINE** | 中級（認証情報 + webhook） | Webhook | [ガイド](docs/channels/line/README.ja.md) |
-| **WeCom** | 簡単（QR ログインまたは手動） | WebSocket | [ガイド](docs/channels/wecom/README.md) |
-| **IRC** | 中級（サーバー + nick） | IRC protocol | [ガイド](docs/ja/chat-apps.md#irc) |
-| **OneBot** | 中級（WebSocket URL） | OneBot v11 | [ガイド](docs/channels/onebot/README.ja.md) |
-| **MaixCam** | 簡単（有効化） | TCP socket | [ガイド](docs/channels/maixcam/README.ja.md) |
+| **Telegram** | 簡単（bot トークン） | Long polling | [ガイド](../channels/telegram/README.ja.md) |
+| **Discord** | 簡単（bot トークン + intents） | WebSocket | [ガイド](../channels/discord/README.ja.md) |
+| **WhatsApp** | 簡単（QR スキャンまたは bridge URL） | Native / Bridge | [ガイド](../guides/chat-apps.ja.md#whatsapp) |
+| **微信 (Weixin)** | 簡単（QR スキャン） | iLink API | [ガイド](../guides/chat-apps.ja.md#weixin) |
+| **QQ** | 簡単（AppID + AppSecret） | WebSocket | [ガイド](../channels/qq/README.ja.md) |
+| **Slack** | 簡単（bot + app トークン） | Socket Mode | [ガイド](../channels/slack/README.ja.md) |
+| **Matrix** | 中級（homeserver + トークン） | Sync API | [ガイド](../channels/matrix/README.ja.md) |
+| **DingTalk** | 中級（クライアント認証情報） | Stream | [ガイド](../channels/dingtalk/README.ja.md) |
+| **Feishu / Lark** | 中級（App ID + Secret） | WebSocket/SDK | [ガイド](../channels/feishu/README.ja.md) |
+| **LINE** | 中級（認証情報 + webhook） | Webhook | [ガイド](../channels/line/README.ja.md) |
+| **WeCom** | 簡単（QR ログインまたは手動） | WebSocket | [ガイド](../channels/wecom/README.ja.md) |
+| **IRC** | 中級（サーバー + nick） | IRC protocol | [ガイド](../guides/chat-apps.ja.md#irc) |
+| **OneBot** | 中級（WebSocket URL） | OneBot v11 | [ガイド](../channels/onebot/README.ja.md) |
+| **MaixCam** | 簡単（有効化） | TCP socket | [ガイド](../channels/maixcam/README.ja.md) |
| **Pico** | 簡単（有効化） | Native protocol | 内蔵 |
| **Pico Client** | 簡単（WebSocket URL） | WebSocket | 内蔵 |
> webhook ベースのすべての Channel は単一の Gateway HTTP サーバー（`gateway.host`:`gateway.port`、デフォルト `127.0.0.1:18790`）を共有します。Feishu は WebSocket/SDK モードを使用し、共有 HTTP サーバーを使用しません。
-> ログの詳細度は `gateway.log_level` で制御します（デフォルト：`warn`）。サポートされる値：`debug`、`info`、`warn`、`error`、`fatal`。`PICOCLAW_LOG_LEVEL` 環境変数でも設定可能です。詳細は[設定ガイド](docs/ja/configuration.md#gateway-ログレベル)を参照してください。
+> ログの詳細度は `gateway.log_level` で制御します（デフォルト：`warn`）。サポートされる値：`debug`、`info`、`warn`、`error`、`fatal`。`PICOCLAW_LOG_LEVEL` 環境変数でも設定可能です。詳細は[設定ガイド](../guides/configuration.ja.md#gateway-ログレベル)を参照してください。
-Channel の詳細なセットアップ手順は [チャットアプリ設定](docs/ja/chat-apps.md) を参照してください。
+Channel の詳細なセットアップ手順は [チャットアプリ設定](../guides/chat-apps.ja.md) を参照してください。
## 🔧 ツール
@@ -501,7 +502,7 @@ PicoClaw は最新情報を提供するために Web を検索できます。`to
### ⚙️ その他のツール
-PicoClaw にはファイル操作、コード実行、スケジューリングなどの組み込みツールが含まれています。詳細は [ツール設定](docs/ja/tools_configuration.md) を参照してください。
+PicoClaw にはファイル操作、コード実行、スケジューリングなどの組み込みツールが含まれています。詳細は [ツール設定](../reference/tools_configuration.ja.md) を参照してください。
## 🎯 Skill
@@ -531,7 +532,7 @@ picoclaw skills install
}
```
-詳細は [ツール設定 - Skill](docs/ja/tools_configuration.md#skills-tool) を参照してください。
+詳細は [ツール設定 - Skill](../reference/tools_configuration.ja.md#skills-tool) を参照してください。
## 🔗 MCP（Model Context Protocol）
@@ -554,9 +555,9 @@ PicoClaw は [MCP](https://modelcontextprotocol.io/) をネイティブサポー
}
```
-MCP の完全な設定（stdio、SSE、HTTP トランスポート、Tool Discovery）は [ツール設定 - MCP](docs/ja/tools_configuration.md#mcp-tool) を参照してください。
+MCP の完全な設定（stdio、SSE、HTTP トランスポート、Tool Discovery）は [ツール設定 - MCP](../reference/tools_configuration.ja.md#mcp-tool) を参照してください。
-## エージェントソーシャルネットワークに参加
+## エージェントソーシャルネットワークに参加
CLI または統合チャットアプリからメッセージを 1 つ送るだけで、PicoClaw をエージェントソーシャルネットワークに接続できます。
@@ -597,23 +598,23 @@ PicoClaw は `cron` ツールによるスケジュールリマインダーと定
| トピック | 説明 |
|---------|------|
-| [Docker & クイックスタート](docs/ja/docker.md) | Docker Compose セットアップ、Launcher/Agent モード |
-| [チャットアプリ](docs/ja/chat-apps.md) | 17 以上の Channel セットアップガイド |
-| [設定](docs/ja/configuration.md) | 環境変数、ワークスペース構成、セキュリティサンドボックス |
-| [Provider とモデル](docs/ja/providers.md) | 30 以上の LLM Provider、モデルルーティング、model_list 設定 |
-| [Spawn & 非同期タスク](docs/ja/spawn-tasks.md) | クイックタスク、spawn による長時間タスク、非同期サブエージェントオーケストレーション |
-| [Hook システム](docs/hooks/README.md) | イベント駆動 Hook：オブザーバー、インターセプター、承認 Hook |
-| [Steering](docs/steering.md) | 実行中の Agent ループにメッセージを注入 |
-| [SubTurn](docs/subturn.md) | サブ Agent の調整、並行制御、ライフサイクル |
-| [トラブルシューティング](docs/ja/troubleshooting.md) | よくある問題と解決策 |
-| [ツール設定](docs/ja/tools_configuration.md) | ツールごとの有効/無効、exec ポリシー、MCP、Skill |
-| [ハードウェア互換性](docs/ja/hardware-compatibility.md) | テスト済みボード、最小要件 |
+| [Docker & クイックスタート](../guides/docker.ja.md) | Docker Compose セットアップ、Launcher/Agent モード |
+| [チャットアプリ](../guides/chat-apps.ja.md) | 17 以上の Channel セットアップガイド |
+| [設定](../guides/configuration.ja.md) | 環境変数、ワークスペース構成、セキュリティサンドボックス |
+| [Provider とモデル](../guides/providers.ja.md) | 30 以上の LLM Provider、モデルルーティング、model_list 設定 |
+| [Spawn & 非同期タスク](../guides/spawn-tasks.ja.md) | クイックタスク、spawn による長時間タスク、非同期サブエージェントオーケストレーション |
+| [Hook システム](../architecture/hooks/README.md) | イベント駆動 Hook：オブザーバー、インターセプター、承認 Hook |
+| [Steering](../architecture/steering.md) | 実行中の Agent ループにメッセージを注入 |
+| [SubTurn](../architecture/subturn.md) | サブ Agent の調整、並行制御、ライフサイクル |
+| [トラブルシューティング](../operations/troubleshooting.ja.md) | よくある問題と解決策 |
+| [ツール設定](../reference/tools_configuration.ja.md) | ツールごとの有効/無効、exec ポリシー、MCP、Skill |
+| [ハードウェア互換性](../guides/hardware-compatibility.ja.md) | テスト済みボード、最小要件 |
## 🤝 コントリビュート＆ロードマップ
PR 歓迎！コードベースは意図的に小さく読みやすくしています。
-[コミュニティロードマップ](https://github.com/sipeed/picoclaw/issues/988)と[CONTRIBUTING.md](CONTRIBUTING.md)をご覧ください。
+[コミュニティロードマップ](https://github.com/sipeed/picoclaw/issues/988)と[CONTRIBUTING.md](../../CONTRIBUTING.md)をご覧ください。
開発者グループ構築中、最初の PR がマージされたら参加できます！
@@ -622,4 +623,4 @@ PR 歓迎！コードベースは意図的に小さく読みやすくしてい
Discord:
WeChat:
-
+
diff --git a/README.ko.md b/docs/project/README.ko.md
similarity index 83%
rename from README.ko.md
rename to docs/project/README.ko.md
index 9095a9240..cfc985688 100644
--- a/README.ko.md
+++ b/docs/project/README.ko.md
@@ -1,5 +1,5 @@
-
+
PicoClaw: Go로 작성된 초고효율 AI 어시스턴트
@@ -14,11 +14,11 @@
-
+
-[中文](README.zh.md) | [日本語](README.ja.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](README.md)
+[中文](README.zh.md) | [日本語](README.ja.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.ms.md) | [English](../../README.md)
|
-
+
|
-
+
|
@@ -71,7 +71,7 @@
2026-02-26 🎉 PicoClaw가 단 17일 만에 **20K 스타**를 달성했습니다! 채널 자동 오케스트레이션과 기능 인터페이스가 적용되었습니다.
-2026-02-16 🎉 PicoClaw가 1주일 만에 **12K 스타**를 돌파했습니다! 커뮤니티 메인터너 역할과 [로드맵](ROADMAP.md)이 공식적으로 공개되었습니다.
+2026-02-16 🎉 PicoClaw가 1주일 만에 **12K 스타**를 돌파했습니다! 커뮤니티 메인터너 역할과 [로드맵](../../ROADMAP.md)이 공식적으로 공개되었습니다.
2026-02-13 🎉 PicoClaw가 4일 만에 **5000 스타**를 돌파했습니다! 프로젝트 로드맵과 개발자 그룹이 준비 중입니다.
@@ -108,14 +108,14 @@ _*최근 빌드는 급격한 PR 병합으로 인해 10~20MB를 사용할 수 있
| **부팅 시간**(0.8GHz 코어) | >500초 | >30초 | **<1초** |
| **비용** | Mac Mini $599 | 대부분의 Linux 보드 ~$50 | **모든 Linux 보드****최저 $10부터** |
-
+
-> **[하드웨어 호환 목록](docs/hardware-compatibility.md)** — 테스트된 모든 보드를 확인하세요. $5 RISC-V 보드부터 Raspberry Pi, Android 스마트폰까지 포함됩니다. 사용 중인 보드가 없나요? PR을 보내주세요!
+> **[하드웨어 호환 목록](../guides/hardware-compatibility.md)** — 테스트된 모든 보드를 확인하세요. $5 RISC-V 보드부터 Raspberry Pi, Android 스마트폰까지 포함됩니다. 사용 중인 보드가 없나요? PR을 보내주세요!
-
+
## 🦾 데모
@@ -129,9 +129,9 @@ _*최근 빌드는 급격한 PR 병합으로 인해 10~20MB를 사용할 수 있
웹 검색 및 학습 |
-
|
-
|
-
|
+
|
+
|
+
|
| 개발 · 배포 · 확장 |
@@ -220,7 +220,7 @@ picoclaw-launcher
> ```
-
+
**시작 방법:**
@@ -274,7 +274,7 @@ macOS에서는 인터넷에서 다운로드한 앱이고 Mac App Store 공증을
**1단계:** `picoclaw-launcher`를 더블클릭합니다. 그러면 보안 경고가 표시됩니다.
-
+
> *"picoclaw-launcher"을(를) 열 수 없습니다. Apple에서 이 앱이 악성 소프트웨어가 없으며 Mac이나 개인 정보를 해치지 않는다고 확인할 수 없습니다.*
@@ -282,7 +282,7 @@ macOS에서는 인터넷에서 다운로드한 앱이고 Mac App Store 공증을
**2단계:** **시스템 설정** -> **개인정보 보호 및 보안** 으로 이동한 뒤 **보안** 섹션까지 스크롤하여 **그래도 열기(Open Anyway)** 를 클릭하고, 대화상자에서 다시 한 번 **그래도 열기**를 확인합니다.
-
+
이 과정을 한 번만 거치면 이후에는 `picoclaw-launcher`가 정상적으로 열립니다.
@@ -298,7 +298,7 @@ picoclaw-launcher-tui
```
-
+
**시작 방법:**
@@ -317,10 +317,10 @@ TUI 메뉴를 사용해 다음 순서로 진행하세요. **1)** 프로바이더
@@ -344,7 +344,7 @@ termux-chroot ./picoclaw onboard # chroot가 표준 Linux 파일시스템 레
그다음 아래의 터미널 런처 섹션을 따라 설정을 마무리하세요.
-
+
런처 UI 없이 `picoclaw` 코어 바이너리만 있는 최소 환경에서는 명령줄과 JSON 설정 파일만으로도 모든 설정을 마칠 수 있습니다.
@@ -377,7 +377,7 @@ picoclaw onboard
> 사용 가능한 모든 옵션이 포함된 전체 설정 템플릿은 저장소의 `config/config.example.json`을 참고하세요.
>
-> 참고: `config.example.json` 형식은 버전 0이며 민감 정보가 포함되어 있습니다. 실행 시 자동으로 버전 1+로 마이그레이션되며, 이후 `config.json`에는 비민감 정보만 저장되고 민감 정보는 `.security.yml`에 저장됩니다. 민감 정보를 직접 수정해야 한다면 `docs/security_configuration.md`를 참고하세요.
+> 참고: `config.example.json` 형식은 버전 0이며 민감 정보가 포함되어 있습니다. 실행 시 자동으로 버전 1+로 마이그레이션되며, 이후 `config.json`에는 비민감 정보만 저장되고 민감 정보는 `.security.yml`에 저장됩니다. 민감 정보를 직접 수정해야 한다면 `../security/security_configuration.md`를 참고하세요.
**3. 채팅**
@@ -455,7 +455,7 @@ PicoClaw는 `model_list` 설정을 통해 30개 이상의 LLM 프로바이더를
}
```
-프로바이더 전체 설정은 [프로바이더와 모델](docs/providers.md)을 참고하세요.
+프로바이더 전체 설정은 [프로바이더와 모델](../guides/providers.md)을 참고하세요.
@@ -465,29 +465,29 @@ PicoClaw는 `model_list` 설정을 통해 30개 이상의 LLM 프로바이더를
| 채널 | 설정 | 프로토콜 | 문서 |
|---------|------|----------|------|
-| **Telegram** | 쉬움(봇 토큰) | Long polling | [가이드](docs/channels/telegram/README.md) |
-| **Discord** | 쉬움(봇 토큰 + intents) | WebSocket | [가이드](docs/channels/discord/README.md) |
-| **WhatsApp** | 쉬움(QR 스캔 또는 브리지 URL) | Native / Bridge | [가이드](docs/chat-apps.md#whatsapp) |
-| **Weixin** | 쉬움(네이티브 QR 스캔) | iLink API | [가이드](docs/chat-apps.md#weixin) |
-| **QQ** | 쉬움(AppID + AppSecret) | WebSocket | [가이드](docs/channels/qq/README.md) |
-| **Slack** | 쉬움(봇 + 앱 토큰) | Socket Mode | [가이드](docs/channels/slack/README.md) |
-| **Matrix** | 중간(homeserver + 토큰) | Sync API | [가이드](docs/channels/matrix/README.md) |
-| **DingTalk** | 중간(클라이언트 자격 증명) | Stream | [가이드](docs/channels/dingtalk/README.md) |
-| **Feishu / Lark** | 중간(App ID + Secret) | WebSocket/SDK | [가이드](docs/channels/feishu/README.md) |
-| **LINE** | 중간(인증 정보 + webhook) | Webhook | [가이드](docs/channels/line/README.md) |
-| **WeCom** | 쉬움(QR 로그인 또는 수동 설정) | WebSocket | [가이드](docs/channels/wecom/README.md) |
-| **VK** | 쉬움(그룹 토큰) | Long Poll | [가이드](docs/channels/vk/README.md) |
-| **IRC** | 중간(서버 + 닉네임) | IRC protocol | [가이드](docs/chat-apps.md#irc) |
-| **OneBot** | 중간(WebSocket URL) | OneBot v11 | [가이드](docs/channels/onebot/README.md) |
-| **MaixCam** | 쉬움(활성화) | TCP socket | [가이드](docs/channels/maixcam/README.md) |
+| **Telegram** | 쉬움(봇 토큰) | Long polling | [가이드](../channels/telegram/README.md) |
+| **Discord** | 쉬움(봇 토큰 + intents) | WebSocket | [가이드](../channels/discord/README.md) |
+| **WhatsApp** | 쉬움(QR 스캔 또는 브리지 URL) | Native / Bridge | [가이드](../guides/chat-apps.md#whatsapp) |
+| **Weixin** | 쉬움(네이티브 QR 스캔) | iLink API | [가이드](../guides/chat-apps.md#weixin) |
+| **QQ** | 쉬움(AppID + AppSecret) | WebSocket | [가이드](../channels/qq/README.md) |
+| **Slack** | 쉬움(봇 + 앱 토큰) | Socket Mode | [가이드](../channels/slack/README.md) |
+| **Matrix** | 중간(homeserver + 토큰) | Sync API | [가이드](../channels/matrix/README.md) |
+| **DingTalk** | 중간(클라이언트 자격 증명) | Stream | [가이드](../channels/dingtalk/README.md) |
+| **Feishu / Lark** | 중간(App ID + Secret) | WebSocket/SDK | [가이드](../channels/feishu/README.md) |
+| **LINE** | 중간(인증 정보 + webhook) | Webhook | [가이드](../channels/line/README.md) |
+| **WeCom** | 쉬움(QR 로그인 또는 수동 설정) | WebSocket | [가이드](../channels/wecom/README.md) |
+| **VK** | 쉬움(그룹 토큰) | Long Poll | [가이드](../channels/vk/README.md) |
+| **IRC** | 중간(서버 + 닉네임) | IRC protocol | [가이드](../guides/chat-apps.md#irc) |
+| **OneBot** | 중간(WebSocket URL) | OneBot v11 | [가이드](../channels/onebot/README.md) |
+| **MaixCam** | 쉬움(활성화) | TCP socket | [가이드](../channels/maixcam/README.md) |
| **Pico** | 쉬움(활성화) | 네이티브 프로토콜 | 내장 |
| **Pico Client** | 쉬움(WebSocket URL) | WebSocket | 내장 |
> webhook 기반 채널은 모두 하나의 게이트웨이 HTTP 서버(`gateway.host`:`gateway.port`, 기본값 `127.0.0.1:18790`)를 공유합니다. Feishu는 WebSocket/SDK 모드를 사용하며 이 공용 HTTP 서버를 사용하지 않습니다.
-> 로그 상세도는 `gateway.log_level`(기본값: `warn`)로 제어됩니다. 지원 값은 `debug`, `info`, `warn`, `error`, `fatal`입니다. `PICOCLAW_LOG_LEVEL` 환경 변수로도 설정할 수 있습니다. 자세한 내용은 [설정 문서](docs/configuration.md#gateway-log-level)를 참고하세요.
+> 로그 상세도는 `gateway.log_level`(기본값: `warn`)로 제어됩니다. 지원 값은 `debug`, `info`, `warn`, `error`, `fatal`입니다. `PICOCLAW_LOG_LEVEL` 환경 변수로도 설정할 수 있습니다. 자세한 내용은 [설정 문서](../guides/configuration.md#gateway-log-level)를 참고하세요.
-자세한 채널 설정 방법은 [채팅 앱 설정 가이드](docs/chat-apps.md)를 참고하세요.
+자세한 채널 설정 방법은 [채팅 앱 설정 가이드](../guides/chat-apps.md)를 참고하세요.
## 🔧 도구
@@ -507,7 +507,7 @@ PicoClaw는 최신 정보를 제공하기 위해 웹 검색을 수행할 수 있
### ⚙️ 기타 도구
-PicoClaw에는 파일 작업, 코드 실행, 스케줄링 등을 위한 내장 도구가 포함되어 있습니다. 자세한 내용은 [도구 설정](docs/tools_configuration.md)을 참고하세요.
+PicoClaw에는 파일 작업, 코드 실행, 스케줄링 등을 위한 내장 도구가 포함되어 있습니다. 자세한 내용은 [도구 설정](../reference/tools_configuration.md)을 참고하세요.
## 🎯 스킬
@@ -537,7 +537,7 @@ picoclaw skills install
}
```
-자세한 내용은 [도구 설정 - 스킬](docs/tools_configuration.md#skills-tool)를 참고하세요.
+자세한 내용은 [도구 설정 - 스킬](../reference/tools_configuration.md#skills-tool)를 참고하세요.
## 🔗 MCP (Model Context Protocol)
@@ -560,9 +560,9 @@ PicoClaw는 [MCP](https://modelcontextprotocol.io/)를 기본 지원합니다.
}
```
-MCP 전체 설정(stdio, SSE, HTTP 전송 방식, 도구 탐색)은 [도구 설정 - MCP](docs/tools_configuration.md#mcp-tool)를 참고하세요.
+MCP 전체 설정(stdio, SSE, HTTP 전송 방식, 도구 탐색)은 [도구 설정 - MCP](../reference/tools_configuration.md#mcp-tool)를 참고하세요.
-## 에이전트 소셜 네트워크 참여하기
+## 에이전트 소셜 네트워크 참여하기
CLI 또는 통합된 채팅 앱에서 메시지를 한 번만 보내면 PicoClaw를 에이전트 소셜 네트워크에 연결할 수 있습니다.
@@ -597,7 +597,7 @@ PicoClaw는 `cron` 도구를 통해 예약 리마인더와 반복 작업을 지
* **반복 작업**: "2시간마다 알려줘" -> 2시간마다 실행
* **Cron 표현식**: "매일 오전 9시에 알려줘" -> cron 표현식 사용
-현재 지원하는 스케줄 유형, 실행 모드, 명령 작업 게이트, 저장 방식은 [docs/cron.md](docs/cron.md)를 참고하세요.
+현재 지원하는 스케줄 유형, 실행 모드, 명령 작업 게이트, 저장 방식은 [docs/reference/cron.md](../reference/cron.md)를 참고하세요.
## 📚 문서
@@ -605,24 +605,24 @@ PicoClaw는 `cron` 도구를 통해 예약 리마인더와 반복 작업을 지
| 주제 | 설명 |
|------|------|
-| [도커 & 빠른 시작](docs/docker.md) | Docker Compose 설정, 런처/에이전트 모드 |
-| [채팅 앱](docs/chat-apps.md) | 17개 이상의 채널 설정 가이드 |
-| [설정](docs/configuration.md) | 환경 변수, 워크스페이스 레이아웃, 보안 샌드박스 |
-| [예약 작업과 Cron](docs/cron.md) | Cron 스케줄 유형, 전달 모드, 명령 게이트, 작업 저장 |
-| [프로바이더와 모델](docs/providers.md) | 30개 이상의 LLM 프로바이더, 모델 라우팅, model_list 설정 |
-| [Spawn & 비동기 작업](docs/spawn-tasks.md) | 빠른 작업, spawn을 이용한 장기 작업, 비동기 서브에이전트 오케스트레이션 |
-| [Hooks](docs/hooks/README.md) | 이벤트 기반 Hook 시스템: 관찰자, 인터셉터, 승인 훅 |
-| [Steering](docs/steering.md) | 실행 중인 에이전트 루프에서 도구 호출 사이에 메시지 주입 |
-| [SubTurn](docs/subturn.md) | 서브에이전트 조정, 동시성 제어, 생명주기 |
-| [문제 해결](docs/troubleshooting.md) | 자주 발생하는 문제와 해결 방법 |
-| [도구 설정](docs/tools_configuration.md) | 도구별 활성화/비활성화, exec 정책, MCP, 스킬 |
-| [하드웨어 호환성](docs/hardware-compatibility.md) | 테스트된 보드, 최소 요구사항 |
+| [도커 & 빠른 시작](../guides/docker.md) | Docker Compose 설정, 런처/에이전트 모드 |
+| [채팅 앱](../guides/chat-apps.md) | 17개 이상의 채널 설정 가이드 |
+| [설정](../guides/configuration.md) | 환경 변수, 워크스페이스 레이아웃, 보안 샌드박스 |
+| [예약 작업과 Cron](../reference/cron.md) | Cron 스케줄 유형, 전달 모드, 명령 게이트, 작업 저장 |
+| [프로바이더와 모델](../guides/providers.md) | 30개 이상의 LLM 프로바이더, 모델 라우팅, model_list 설정 |
+| [Spawn & 비동기 작업](../guides/spawn-tasks.md) | 빠른 작업, spawn을 이용한 장기 작업, 비동기 서브에이전트 오케스트레이션 |
+| [Hooks](../architecture/hooks/README.md) | 이벤트 기반 Hook 시스템: 관찰자, 인터셉터, 승인 훅 |
+| [Steering](../architecture/steering.md) | 실행 중인 에이전트 루프에서 도구 호출 사이에 메시지 주입 |
+| [SubTurn](../architecture/subturn.md) | 서브에이전트 조정, 동시성 제어, 생명주기 |
+| [문제 해결](../operations/troubleshooting.md) | 자주 발생하는 문제와 해결 방법 |
+| [도구 설정](../reference/tools_configuration.md) | 도구별 활성화/비활성화, exec 정책, MCP, 스킬 |
+| [하드웨어 호환성](../guides/hardware-compatibility.md) | 테스트된 보드, 최소 요구사항 |
## 🤝 기여 & 로드맵
PR은 언제든 환영합니다! 코드베이스는 의도적으로 작고 읽기 쉽게 유지하고 있습니다.
-가이드라인은 [커뮤니티 로드맵](https://github.com/sipeed/picoclaw/issues/988)과 [CONTRIBUTING.md](CONTRIBUTING.md)를 참고하세요.
+가이드라인은 [커뮤니티 로드맵](https://github.com/sipeed/picoclaw/issues/988)과 [CONTRIBUTING.md](../../CONTRIBUTING.md)를 참고하세요.
개발자 그룹도 준비 중입니다. 첫 PR이 머지되면 함께할 수 있습니다!
@@ -631,4 +631,4 @@ PR은 언제든 환영합니다! 코드베이스는 의도적으로 작고 읽
Discord:
WeChat:
-
+
diff --git a/README.my.md b/docs/project/README.ms.md
similarity index 85%
rename from README.my.md
rename to docs/project/README.ms.md
index bbe003deb..f8c9e95e7 100644
--- a/README.my.md
+++ b/docs/project/README.ms.md
@@ -1,5 +1,5 @@
-
+
PicoClaw: Pembantu AI Ultra-Cekap dalam Go
@@ -14,11 +14,11 @@
-
+
-[中文](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** | [English](README.md)
+[中文](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** | [English](../../README.md)
|
-
+
|
-
+
|
@@ -71,7 +71,7 @@
2026-02-26 🎉 PicoClaw mencapai **20K Stars** hanya dalam 17 hari! Orkestrasi saluran automatik dan antara muka keupayaan kini aktif.
-2026-02-16 🎉 PicoClaw melepasi 12K Stars dalam seminggu! Peranan penyelenggara komuniti dan [Peta Jalan](ROADMAP.md) dilancarkan secara rasmi.
+2026-02-16 🎉 PicoClaw melepasi 12K Stars dalam seminggu! Peranan penyelenggara komuniti dan [Peta Jalan](../../ROADMAP.md) dilancarkan secara rasmi.
2026-02-13 🎉 PicoClaw melepasi 5000 Stars dalam 4 hari! Peta jalan projek dan kumpulan pembangun sedang dalam proses.
@@ -108,14 +108,14 @@ _*Binaan terkini mungkin menggunakan 10-20MB disebabkan penggabungan PR yang pes
| **Masa Boot** (teras 0.8GHz) | >500s | >30s | **<1s** |
| **Kos** | Mac Mini $599 | Kebanyakan papan Linux ~$50 | **Mana-mana papan Linux dari $10** |
-
+
-> **[Senarai Keserasian Perkakasan](docs/hardware-compatibility.md)** — Lihat semua papan yang diuji, dari RISC-V $5 hingga Raspberry Pi hingga telefon Android.
+> **[Senarai Keserasian Perkakasan](../guides/hardware-compatibility.md)** — Lihat semua papan yang diuji, dari RISC-V $5 hingga Raspberry Pi hingga telefon Android.
-
+
## 🦾 Demonstrasi
@@ -129,9 +129,9 @@ _*Binaan terkini mungkin menggunakan 10-20MB disebabkan penggabungan PR yang pes
Carian Web & Pembelajaran |
-
|
-
|
-
|
+
|
+
|
+
|
| Bangun · Deploy · Skala |
@@ -220,7 +220,7 @@ picoclaw-launcher
> ```
-
+
**Memulakan:** Buka WebUI, kemudian: **1)** Konfigurasikan Penyedia (tambah kunci API LLM) -> **2)** Konfigurasikan Saluran (cth. Telegram) -> **3)** Mulakan Gateway -> **4)** Sembang!
@@ -271,7 +271,7 @@ macOS mungkin menyekat `picoclaw-launcher` pada pelancaran pertama kerana ia dim
**Langkah 1:** Klik dua kali `picoclaw-launcher`. Anda akan melihat amaran keselamatan:
-
+
> *"picoclaw-launcher" Tidak Dibuka — Apple tidak dapat mengesahkan "picoclaw-launcher" bebas daripada perisian hasad yang mungkin membahayakan Mac anda atau menjejaskan privasi anda.*
@@ -279,7 +279,7 @@ macOS mungkin menyekat `picoclaw-launcher` pada pelancaran pertama kerana ia dim
**Langkah 2:** Buka **Tetapan Sistem** → **Privasi & Keselamatan** → tatal ke bawah ke bahagian **Keselamatan** → klik **Buka Juga** → sahkan dengan mengklik **Buka Juga** dalam dialog.
-
+
Selepas langkah sekali ini, `picoclaw-launcher` akan dibuka secara normal pada pelancaran seterusnya.
@@ -295,7 +295,7 @@ picoclaw-launcher-tui
```
-
+
**Memulakan:**
@@ -314,10 +314,10 @@ Pratonton:
@@ -341,7 +341,7 @@ termux-chroot ./picoclaw onboard # chroot menyediakan susun atur sistem fail L
Kemudian ikuti bahagian Pelancar Terminal di bawah untuk melengkapkan konfigurasi.
-
+
Untuk persekitaran minimal di mana hanya binari teras `picoclaw` tersedia (tiada UI Pelancar), anda boleh mengkonfigurasi semua melalui baris arahan dan fail konfigurasi JSON.
@@ -449,7 +449,7 @@ PicoClaw menyokong 30+ penyedia LLM melalui konfigurasi `model_list`. Gunakan fo
}
```
-Untuk butiran konfigurasi penyedia penuh, lihat [Penyedia & Model](docs/providers.md).
+Untuk butiran konfigurasi penyedia penuh, lihat [Penyedia & Model](../guides/providers.md).
@@ -460,28 +460,28 @@ Bercakap dengan PicoClaw anda melalui 17+ platform pemesejan:
| Saluran | Persediaan | Protokol | Dok |
|---------|-----------|----------|-----|
-| **Telegram** | Mudah (token bot) | Long polling | [Panduan](docs/channels/telegram/README.md) |
-| **Discord** | Mudah (token bot + intents) | WebSocket | [Panduan](docs/channels/discord/README.md) |
-| **WhatsApp** | Mudah (imbas QR atau URL jambatan) | Natif / Jambatan | [Panduan](docs/chat-apps.md#whatsapp) |
-| **Weixin** | Mudah (imbas QR natif) | iLink API | [Panduan](docs/chat-apps.md#weixin) |
-| **QQ** | Mudah (AppID + AppSecret) | WebSocket | [Panduan](docs/channels/qq/README.md) |
-| **Slack** | Mudah (token bot + app) | Socket Mode | [Panduan](docs/channels/slack/README.md) |
-| **Matrix** | Sederhana (homeserver + token) | Sync API | [Panduan](docs/channels/matrix/README.md) |
-| **DingTalk** | Sederhana (kelayakan klien) | Stream | [Panduan](docs/channels/dingtalk/README.md) |
-| **Feishu / Lark** | Sederhana (App ID + Secret) | WebSocket/SDK | [Panduan](docs/channels/feishu/README.md) |
-| **LINE** | Sederhana (kelayakan + webhook) | Webhook | [Panduan](docs/channels/line/README.md) |
-| **WeCom** | Mudah (log masuk QR atau manual) | WebSocket | [Panduan](docs/channels/wecom/README.md) |
-| **IRC** | Sederhana (pelayan + nick) | Protokol IRC | [Panduan](docs/chat-apps.md#irc) |
-| **OneBot** | Sederhana (URL WebSocket) | OneBot v11 | [Panduan](docs/channels/onebot/README.md) |
-| **MaixCam** | Mudah (aktifkan) | TCP socket | [Panduan](docs/channels/maixcam/README.md) |
+| **Telegram** | Mudah (token bot) | Long polling | [Panduan](../channels/telegram/README.md) |
+| **Discord** | Mudah (token bot + intents) | WebSocket | [Panduan](../channels/discord/README.md) |
+| **WhatsApp** | Mudah (imbas QR atau URL jambatan) | Natif / Jambatan | [Panduan](../guides/chat-apps.ms.md#whatsapp) |
+| **Weixin** | Mudah (imbas QR natif) | iLink API | [Panduan](../guides/chat-apps.ms.md#weixin) |
+| **QQ** | Mudah (AppID + AppSecret) | WebSocket | [Panduan](../channels/qq/README.md) |
+| **Slack** | Mudah (token bot + app) | Socket Mode | [Panduan](../channels/slack/README.md) |
+| **Matrix** | Sederhana (homeserver + token) | Sync API | [Panduan](../channels/matrix/README.md) |
+| **DingTalk** | Sederhana (kelayakan klien) | Stream | [Panduan](../channels/dingtalk/README.md) |
+| **Feishu / Lark** | Sederhana (App ID + Secret) | WebSocket/SDK | [Panduan](../channels/feishu/README.md) |
+| **LINE** | Sederhana (kelayakan + webhook) | Webhook | [Panduan](../channels/line/README.md) |
+| **WeCom** | Mudah (log masuk QR atau manual) | WebSocket | [Panduan](../channels/wecom/README.md) |
+| **IRC** | Sederhana (pelayan + nick) | Protokol IRC | [Panduan](../guides/chat-apps.ms.md#irc) |
+| **OneBot** | Sederhana (URL WebSocket) | OneBot v11 | [Panduan](../channels/onebot/README.md) |
+| **MaixCam** | Mudah (aktifkan) | TCP socket | [Panduan](../channels/maixcam/README.md) |
| **Pico** | Mudah (aktifkan) | Protokol natif | Terbina dalam |
| **Pico Client** | Mudah (URL WebSocket) | WebSocket | Terbina dalam |
> Semua saluran berasaskan webhook berkongsi satu pelayan HTTP Gateway (`gateway.host`:`gateway.port`, lalai `127.0.0.1:18790`). Feishu menggunakan mod WebSocket/SDK dan tidak menggunakan pelayan HTTP yang dikongsi.
-> Tahap perincian log dikawal oleh `gateway.log_level` (lalai: `warn`). Nilai yang disokong: `debug`, `info`, `warn`, `error`, `fatal`. Boleh juga ditetapkan melalui `PICOCLAW_LOG_LEVEL`. Lihat [Konfigurasi](docs/configuration.md#gateway-log-level) untuk butiran.
+> Tahap perincian log dikawal oleh `gateway.log_level` (lalai: `warn`). Nilai yang disokong: `debug`, `info`, `warn`, `error`, `fatal`. Boleh juga ditetapkan melalui `PICOCLAW_LOG_LEVEL`. Lihat [Konfigurasi](../guides/configuration.ms.md#gateway-log-level) untuk butiran.
-Untuk arahan persediaan saluran terperinci, lihat [Konfigurasi Aplikasi Sembang](docs/my/chat-apps.md).
+Untuk arahan persediaan saluran terperinci, lihat [Konfigurasi Aplikasi Sembang](../guides/chat-apps.ms.md).
## 🔧 Alat
@@ -501,7 +501,7 @@ PicoClaw boleh mencari web untuk menyediakan maklumat terkini. Konfigurasikan da
### ⚙️ Alat Lain
-PicoClaw menyertakan alat terbina dalam untuk operasi fail, pelaksanaan kod, penjadualan, dan banyak lagi. Lihat [Konfigurasi Alat](docs/tools_configuration.md) untuk butiran.
+PicoClaw menyertakan alat terbina dalam untuk operasi fail, pelaksanaan kod, penjadualan, dan banyak lagi. Lihat [Konfigurasi Alat](../reference/tools_configuration.md) untuk butiran.
## 🎯 Kemahiran
@@ -531,7 +531,7 @@ Tambah ke `config.json` anda:
}
```
-Untuk butiran lanjut, lihat [Konfigurasi Alat - Kemahiran](docs/tools_configuration.md#skills-tool).
+Untuk butiran lanjut, lihat [Konfigurasi Alat - Kemahiran](../reference/tools_configuration.md#skills-tool).
## 🔗 MCP (Protokol Konteks Model)
@@ -554,9 +554,9 @@ PicoClaw menyokong [MCP](https://modelcontextprotocol.io/) secara natif — samb
}
```
-Untuk konfigurasi MCP penuh (pengangkutan stdio, SSE, HTTP, Penemuan Alat), lihat [Konfigurasi Alat - MCP](docs/tools_configuration.md#mcp-tool).
+Untuk konfigurasi MCP penuh (pengangkutan stdio, SSE, HTTP, Penemuan Alat), lihat [Konfigurasi Alat - MCP](../reference/tools_configuration.md#mcp-tool).
-## Sertai Rangkaian Sosial Agent
+## Sertai Rangkaian Sosial Agent
Sambungkan PicoClaw ke Rangkaian Sosial Agent dengan menghantar satu mesej melalui CLI atau mana-mana Aplikasi Sembang yang disepadukan.
@@ -597,20 +597,20 @@ Untuk panduan terperinci melebihi README ini:
| Topik | Penerangan |
|-------|------------|
-| [Docker & Permulaan Pantas](docs/my/docker.md) | Persediaan Docker Compose, mod Launcher/Agent |
-| [Aplikasi Sembang](docs/my/chat-apps.md) | Panduan persediaan 17+ saluran |
-| [Konfigurasi](docs/my/configuration.md) | Pemboleh ubah persekitaran, susun atur ruang kerja |
-| [Penyedia & Model](docs/providers.md) | 30+ penyedia LLM, penghalaan model |
-| [Spawn & Tugasan Async](docs/my/spawn-tasks.md) | Tugasan pantas, tugasan panjang dengan spawn |
-| [Penyelesaian Masalah](docs/my/troubleshooting.md) | Isu biasa dan penyelesaian |
-| [Konfigurasi Alat](docs/tools_configuration.md) | Aktif/nyahaktif alat, dasar exec, MCP, Kemahiran |
-| [Keserasian Perkakasan](docs/hardware-compatibility.md) | Papan yang diuji, keperluan minimum |
+| [Docker & Permulaan Pantas](../guides/docker.ms.md) | Persediaan Docker Compose, mod Launcher/Agent |
+| [Aplikasi Sembang](../guides/chat-apps.ms.md) | Panduan persediaan 17+ saluran |
+| [Konfigurasi](../guides/configuration.ms.md) | Pemboleh ubah persekitaran, susun atur ruang kerja |
+| [Penyedia & Model](../guides/providers.md) | 30+ penyedia LLM, penghalaan model |
+| [Spawn & Tugasan Async](../guides/spawn-tasks.ms.md) | Tugasan pantas, tugasan panjang dengan spawn |
+| [Penyelesaian Masalah](../operations/troubleshooting.ms.md) | Isu biasa dan penyelesaian |
+| [Konfigurasi Alat](../reference/tools_configuration.md) | Aktif/nyahaktif alat, dasar exec, MCP, Kemahiran |
+| [Keserasian Perkakasan](../guides/hardware-compatibility.md) | Papan yang diuji, keperluan minimum |
## 🤝 Sumbangan & Peta Jalan
PR dialu-alukan! Kod sumber sengaja dibuat kecil dan mudah dibaca.
-Lihat [Peta Jalan Komuniti](https://github.com/sipeed/picoclaw/issues/988) dan [CONTRIBUTING.md](CONTRIBUTING.md) untuk panduan.
+Lihat [Peta Jalan Komuniti](https://github.com/sipeed/picoclaw/issues/988) dan [CONTRIBUTING.md](../../CONTRIBUTING.md) untuk panduan.
Kumpulan pembangun sedang dibina, sertai selepas PR pertama anda digabungkan!
@@ -619,4 +619,4 @@ Kumpulan Pengguna:
Discord:
WeChat:
-
+
diff --git a/README.pt-br.md b/docs/project/README.pt-br.md
similarity index 82%
rename from README.pt-br.md
rename to docs/project/README.pt-br.md
index 25f82a180..56d4ddd63 100644
--- a/README.pt-br.md
+++ b/docs/project/README.pt-br.md
@@ -1,5 +1,5 @@
-
+
PicoClaw: Assistente de IA Ultra-Eficiente em Go
@@ -14,11 +14,11 @@
-
+
-[中文](README.zh.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | **Português** | [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](README.md)
+[中文](README.zh.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | **Português** | [Tiếng Việt](README.vi.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.ms.md) | [English](../../README.md)
|
-
+
|
-
+
|
@@ -71,7 +71,7 @@
2026-02-26 🎉 O PicoClaw atinge **20K Stars** em apenas 17 dias! Orquestração automática de channels e interfaces de capacidade estão disponíveis.
-2026-02-16 🎉 O PicoClaw ultrapassa 12K Stars em uma semana! Funções de mantenedor da comunidade e [Roadmap](ROADMAP.md) lançados oficialmente.
+2026-02-16 🎉 O PicoClaw ultrapassa 12K Stars em uma semana! Funções de mantenedor da comunidade e [Roadmap](../../ROADMAP.md) lançados oficialmente.
2026-02-13 🎉 O PicoClaw ultrapassa 5000 Stars em 4 dias! Roadmap do projeto e grupos de desenvolvedores em andamento.
@@ -108,14 +108,14 @@ _*Builds recentes podem usar 10-20MB devido a merges rápidos de PRs. Otimizaç
| **Tempo de boot**(core 0,8GHz) | >500s | >30s | **<1s** |
| **Custo** | Mac Mini $599 | Maioria das placas Linux ~$50 | **Qualquer placa Linux****a partir de $10** |
-
+
-> **[Lista de Compatibilidade de Hardware](docs/pt-br/hardware-compatibility.md)** — Veja todas as placas testadas, de RISC-V de $5 ao Raspberry Pi e celulares Android. Sua placa não está listada? Envie um PR!
+> **[Lista de Compatibilidade de Hardware](../guides/hardware-compatibility.pt-br.md)** — Veja todas as placas testadas, de RISC-V de $5 ao Raspberry Pi e celulares Android. Sua placa não está listada? Envie um PR!
-
+
## 🦾 Demonstração
@@ -129,9 +129,9 @@ _*Builds recentes podem usar 10-20MB devido a merges rápidos de PRs. Otimizaç
Busca na Web e Aprendizado |
-
|
-
|
-
|
+
|
+
|
+
|
| Desenvolver · Implantar · Escalar |
@@ -220,7 +220,7 @@ picoclaw-launcher
> ```
-
+
**Primeiros passos:**
@@ -274,7 +274,7 @@ O macOS pode bloquear o `picoclaw-launcher` no primeiro lançamento porque ele f
**Passo 1:** Dê um duplo clique em `picoclaw-launcher`. Você verá um aviso de segurança:
-
+
> *"picoclaw-launcher" não foi aberto — A Apple não conseguiu verificar se "picoclaw-launcher" está livre de malware que possa prejudicar seu Mac ou comprometer sua privacidade.*
@@ -282,7 +282,7 @@ O macOS pode bloquear o `picoclaw-launcher` no primeiro lançamento porque ele f
**Passo 2:** Abra **Configurações do Sistema** → **Privacidade e Segurança** → role até a seção **Segurança** → clique em **Abrir Mesmo Assim** → confirme clicando em **Abrir Mesmo Assim** na caixa de diálogo.
-
+
Após esta etapa única, o `picoclaw-launcher` abrirá normalmente nos lançamentos seguintes.
@@ -298,7 +298,7 @@ picoclaw-launcher-tui
```
-
+
**Primeiros passos:**
@@ -307,6 +307,7 @@ Use os menus do TUI para: **1)** Configurar um Provider -> **2)** Configurar um
Para documentação detalhada do TUI, veja [docs.picoclaw.io](https://docs.picoclaw.io).
+
### 📱 Android
Dê uma segunda vida ao seu celular de uma década! Transforme-o em um Assistente de IA inteligente com o PicoClaw.
@@ -317,10 +318,10 @@ Pré-visualização:
@@ -344,7 +345,7 @@ termux-chroot ./picoclaw onboard # chroot fornece um layout padrão de sistema
Em seguida, siga a seção Terminal Launcher abaixo para concluir a configuração.
-
+
Para ambientes mínimos onde apenas o binário principal `picoclaw` está disponível (sem Launcher UI), você pode configurar tudo via linha de comando e um arquivo de configuração JSON.
@@ -450,7 +451,7 @@ O PicoClaw suporta mais de 30 providers de LLM através da configuração `model
}
```
-Para detalhes completos de configuração de providers, veja [Providers & Models](docs/pt-br/providers.md).
+Para detalhes completos de configuração de providers, veja [Providers & Models](../guides/providers.pt-br.md).
@@ -460,28 +461,28 @@ Converse com seu PicoClaw por meio de mais de 17 plataformas de mensagens:
| Channel | Configuração | Protocolo | Docs |
|---------|--------------|-----------|------|
-| **Telegram** | Fácil (bot token) | Long polling | [Guia](docs/channels/telegram/README.pt-br.md) |
-| **Discord** | Fácil (bot token + intents) | WebSocket | [Guia](docs/channels/discord/README.pt-br.md) |
-| **WhatsApp** | Fácil (QR scan ou bridge URL) | Nativo / Bridge | [Guia](docs/pt-br/chat-apps.md#whatsapp) |
-| **Weixin** | Fácil (scan QR nativo) | iLink API | [Guia](docs/pt-br/chat-apps.md#weixin) |
-| **QQ** | Fácil (AppID + AppSecret) | WebSocket | [Guia](docs/channels/qq/README.pt-br.md) |
-| **Slack** | Fácil (bot + app token) | Socket Mode | [Guia](docs/channels/slack/README.pt-br.md) |
-| **Matrix** | Médio (homeserver + token) | Sync API | [Guia](docs/channels/matrix/README.pt-br.md) |
-| **DingTalk** | Médio (credenciais do cliente) | Stream | [Guia](docs/channels/dingtalk/README.pt-br.md) |
-| **Feishu / Lark** | Médio (App ID + Secret) | WebSocket/SDK | [Guia](docs/channels/feishu/README.pt-br.md) |
-| **LINE** | Médio (credenciais + webhook) | Webhook | [Guia](docs/channels/line/README.pt-br.md) |
-| **WeCom** | Fácil (login QR ou manual) | WebSocket | [Guia](docs/channels/wecom/README.md) |
-| **IRC** | Médio (servidor + nick) | Protocolo IRC | [Guia](docs/pt-br/chat-apps.md#irc) |
-| **OneBot** | Médio (WebSocket URL) | OneBot v11 | [Guia](docs/channels/onebot/README.pt-br.md) |
-| **MaixCam** | Fácil (habilitar) | TCP socket | [Guia](docs/channels/maixcam/README.pt-br.md) |
+| **Telegram** | Fácil (bot token) | Long polling | [Guia](../channels/telegram/README.pt-br.md) |
+| **Discord** | Fácil (bot token + intents) | WebSocket | [Guia](../channels/discord/README.pt-br.md) |
+| **WhatsApp** | Fácil (QR scan ou bridge URL) | Nativo / Bridge | [Guia](../guides/chat-apps.pt-br.md#whatsapp) |
+| **Weixin** | Fácil (scan QR nativo) | iLink API | [Guia](../guides/chat-apps.pt-br.md#weixin) |
+| **QQ** | Fácil (AppID + AppSecret) | WebSocket | [Guia](../channels/qq/README.pt-br.md) |
+| **Slack** | Fácil (bot + app token) | Socket Mode | [Guia](../channels/slack/README.pt-br.md) |
+| **Matrix** | Médio (homeserver + token) | Sync API | [Guia](../channels/matrix/README.pt-br.md) |
+| **DingTalk** | Médio (credenciais do cliente) | Stream | [Guia](../channels/dingtalk/README.pt-br.md) |
+| **Feishu / Lark** | Médio (App ID + Secret) | WebSocket/SDK | [Guia](../channels/feishu/README.pt-br.md) |
+| **LINE** | Médio (credenciais + webhook) | Webhook | [Guia](../channels/line/README.pt-br.md) |
+| **WeCom** | Fácil (login QR ou manual) | WebSocket | [Guia](../channels/wecom/README.pt-br.md) |
+| **IRC** | Médio (servidor + nick) | Protocolo IRC | [Guia](../guides/chat-apps.pt-br.md#irc) |
+| **OneBot** | Médio (WebSocket URL) | OneBot v11 | [Guia](../channels/onebot/README.pt-br.md) |
+| **MaixCam** | Fácil (habilitar) | TCP socket | [Guia](../channels/maixcam/README.pt-br.md) |
| **Pico** | Fácil (habilitar) | Protocolo nativo | Integrado |
| **Pico Client** | Fácil (WebSocket URL) | WebSocket | Integrado |
> Todos os channels baseados em webhook compartilham um único servidor HTTP do Gateway (`gateway.host`:`gateway.port`, padrão `127.0.0.1:18790`). O Feishu usa modo WebSocket/SDK e não utiliza o servidor HTTP compartilhado.
-> A verbosidade dos logs é controlada por `gateway.log_level` (padrão: `warn`). Valores suportados: `debug`, `info`, `warn`, `error`, `fatal`. Também pode ser definido via `PICOCLAW_LOG_LEVEL`. Veja [Configuração](docs/pt-br/configuration.md#nível-de-log-do-gateway) para detalhes.
+> A verbosidade dos logs é controlada por `gateway.log_level` (padrão: `warn`). Valores suportados: `debug`, `info`, `warn`, `error`, `fatal`. Também pode ser definido via `PICOCLAW_LOG_LEVEL`. Veja [Configuração](../guides/configuration.pt-br.md#nível-de-log-do-gateway) para detalhes.
-Para instruções detalhadas de configuração de channels, veja [Configuração de Apps de Chat](docs/pt-br/chat-apps.md).
+Para instruções detalhadas de configuração de channels, veja [Configuração de Apps de Chat](../guides/chat-apps.pt-br.md).
## 🔧 Ferramentas
@@ -501,7 +502,7 @@ O PicoClaw pode pesquisar na web para fornecer informações atualizadas. Config
### ⚙️ Outras Ferramentas
-O PicoClaw inclui ferramentas integradas para operações de arquivo, execução de código, agendamento e mais. Veja [Configuração de Ferramentas](docs/pt-br/tools_configuration.md) para detalhes.
+O PicoClaw inclui ferramentas integradas para operações de arquivo, execução de código, agendamento e mais. Veja [Configuração de Ferramentas](../reference/tools_configuration.pt-br.md) para detalhes.
## 🎯 Skills
@@ -531,7 +532,7 @@ Adicione ao seu `config.json`:
}
```
-Para mais detalhes, veja [Configuração de Ferramentas - Skills](docs/pt-br/tools_configuration.md#skills-tool).
+Para mais detalhes, veja [Configuração de Ferramentas - Skills](../reference/tools_configuration.pt-br.md#skills-tool).
## 🔗 MCP (Model Context Protocol)
@@ -554,9 +555,9 @@ O PicoClaw suporta nativamente o [MCP](https://modelcontextprotocol.io/) — con
}
```
-Para configuração completa de MCP (transportes stdio, SSE, HTTP, Tool Discovery), veja [Configuração de Ferramentas - MCP](docs/pt-br/tools_configuration.md#mcp-tool).
+Para configuração completa de MCP (transportes stdio, SSE, HTTP, Tool Discovery), veja [Configuração de Ferramentas - MCP](../reference/tools_configuration.pt-br.md#mcp-tool).
-## Junte-se à Rede Social de Agents
+## Junte-se à Rede Social de Agents
Conecte o PicoClaw à Rede Social de Agents simplesmente enviando uma única mensagem via CLI ou qualquer App de Chat integrado.
@@ -597,23 +598,23 @@ Para guias detalhados além deste README:
| Tópico | Descrição |
|--------|-----------|
-| [Docker & Início Rápido](docs/pt-br/docker.md) | Configuração do Docker Compose, modos Launcher/Agent |
-| [Apps de Chat](docs/pt-br/chat-apps.md) | Guias de configuração para todos os 17+ channels |
-| [Configuração](docs/pt-br/configuration.md) | Variáveis de ambiente, layout do workspace, sandbox de segurança |
-| [Providers & Models](docs/pt-br/providers.md) | 30+ providers de LLM, roteamento de modelos, configuração de model_list |
-| [Spawn & Tarefas Assíncronas](docs/pt-br/spawn-tasks.md) | Tarefas rápidas, tarefas longas com spawn, orquestração assíncrona de sub-agents |
-| [Hooks](docs/hooks/README.md) | Sistema de hooks orientado a eventos: observadores, interceptores, hooks de aprovação |
-| [Steering](docs/steering.md) | Injetar mensagens em um loop de agente em execução |
-| [SubTurn](docs/subturn.md) | Coordenação de subagentes, controle de concorrência, ciclo de vida |
-| [Solução de Problemas](docs/pt-br/troubleshooting.md) | Problemas comuns e soluções |
-| [Configuração de Ferramentas](docs/pt-br/tools_configuration.md) | Habilitar/desabilitar por ferramenta, políticas de exec, MCP, Skills |
-| [Compatibilidade de Hardware](docs/pt-br/hardware-compatibility.md) | Placas testadas, requisitos mínimos |
+| [Docker & Início Rápido](../guides/docker.pt-br.md) | Configuração do Docker Compose, modos Launcher/Agent |
+| [Apps de Chat](../guides/chat-apps.pt-br.md) | Guias de configuração para todos os 17+ channels |
+| [Configuração](../guides/configuration.pt-br.md) | Variáveis de ambiente, layout do workspace, sandbox de segurança |
+| [Providers & Models](../guides/providers.pt-br.md) | 30+ providers de LLM, roteamento de modelos, configuração de model_list |
+| [Spawn & Tarefas Assíncronas](../guides/spawn-tasks.pt-br.md) | Tarefas rápidas, tarefas longas com spawn, orquestração assíncrona de sub-agents |
+| [Hooks](../architecture/hooks/README.md) | Sistema de hooks orientado 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 |
+| [Solução de Problemas](../operations/troubleshooting.pt-br.md) | Problemas comuns e soluções |
+| [Configuração de Ferramentas](../reference/tools_configuration.pt-br.md) | Habilitar/desabilitar por ferramenta, políticas de exec, MCP, Skills |
+| [Compatibilidade de Hardware](../guides/hardware-compatibility.pt-br.md) | Placas testadas, requisitos mínimos |
## 🤝 Contribuir & Roadmap
PRs são bem-vindos! O código-fonte é intencionalmente pequeno e legível.
-Veja nosso [Roadmap da Comunidade](https://github.com/sipeed/picoclaw/issues/988) e [CONTRIBUTING.md](CONTRIBUTING.md) para diretrizes.
+Veja nosso [Roadmap da Comunidade](https://github.com/sipeed/picoclaw/issues/988) e [CONTRIBUTING.md](../../CONTRIBUTING.md) para diretrizes.
Grupo de desenvolvedores em formação, entre após seu primeiro PR mesclado!
@@ -622,4 +623,4 @@ Grupos de Usuários:
Discord:
WeChat:
-
+
diff --git a/README.vi.md b/docs/project/README.vi.md
similarity index 84%
rename from README.vi.md
rename to docs/project/README.vi.md
index 98e0b9bc9..52a56796b 100644
--- a/README.vi.md
+++ b/docs/project/README.vi.md
@@ -1,5 +1,5 @@
-
+
PicoClaw: Trợ lý AI Siêu Nhẹ viết bằng Go
@@ -14,11 +14,11 @@
-
+
-[中文](README.zh.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt-br.md) | **Tiếng Việt** | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.my.md) | [English](README.md)
+[中文](README.zh.md) | [日本語](README.ja.md) | [한국어](README.ko.md) | [Português](README.pt-br.md) | **Tiếng Việt** | [Français](README.fr.md) | [Italiano](README.it.md) | [Bahasa Indonesia](README.id.md) | [Malay](README.ms.md) | [English](../../README.md)
|
-
+
|
-
+
|
@@ -71,7 +71,7 @@
2026-02-26 🎉 PicoClaw đạt **20K Stars** chỉ trong 17 ngày! Tự động điều phối Channel và giao diện khả năng đã hoạt động.
-2026-02-16 🎉 PicoClaw vượt 12K Stars trong một tuần! Vai trò người duy trì cộng đồng và [Lộ trình](ROADMAP.md) chính thức ra mắt.
+2026-02-16 🎉 PicoClaw vượt 12K Stars trong một tuần! Vai trò người duy trì cộng đồng và [Lộ trình](../../ROADMAP.md) chính thức ra mắt.
2026-02-13 🎉 PicoClaw vượt 5000 Stars trong 4 ngày! Lộ trình dự án và nhóm nhà phát triển đang được xây dựng.
@@ -108,14 +108,14 @@ _*Các bản build gần đây có thể dùng 10-20MB do merge PR nhanh. Tối
| **Thời gian khởi động**(lõi 0.8GHz) | >500s | >30s | **<1s** |
| **Chi phí** | Mac Mini $599 | Hầu hết board Linux ~$50 | **Bất kỳ board Linux****từ $10** |
-
+
-> **[Danh sách Tương thích Phần cứng](docs/vi/hardware-compatibility.md)** — Xem tất cả các board đã được kiểm tra, từ RISC-V $5 đến Raspberry Pi đến điện thoại Android. Board của bạn chưa có trong danh sách? Gửi PR!
+> **[Danh sách Tương thích Phần cứng](../guides/hardware-compatibility.vi.md)** — Xem tất cả các board đã được kiểm tra, từ RISC-V $5 đến Raspberry Pi đến điện thoại Android. Board của bạn chưa có trong danh sách? Gửi PR!
-
+
## 🦾 Minh họa
@@ -129,9 +129,9 @@ _*Các bản build gần đây có thể dùng 10-20MB do merge PR nhanh. Tối
Tìm kiếm Web & Học tập |
-
|
-
|
-
|
+
|
+
|
+
|
| Phát triển · Triển khai · Mở rộng |
@@ -220,7 +220,7 @@ picoclaw-launcher
> ```
-
+
**Bắt đầu:**
@@ -274,7 +274,7 @@ macOS có thể chặn `picoclaw-launcher` khi khởi chạy lần đầu vì n
**Bước 1:** Nhấp đúp vào `picoclaw-launcher`. Bạn sẽ thấy cảnh báo bảo mật:
-
+
> *"picoclaw-launcher" Không Mở Được — Apple không thể xác minh "picoclaw-launcher" không chứa phần mềm độc hại có thể gây hại cho Mac hoặc xâm phạm quyền riêng tư của bạn.*
@@ -282,7 +282,7 @@ macOS có thể chặn `picoclaw-launcher` khi khởi chạy lần đầu vì n
**Bước 2:** Mở **Cài đặt Hệ thống** → **Quyền riêng tư & Bảo mật** → cuộn xuống phần **Bảo mật** → nhấp **Vẫn Mở** → xác nhận bằng cách nhấp **Vẫn Mở** trong hộp thoại.
-
+
Sau bước này, `picoclaw-launcher` sẽ mở bình thường trong các lần khởi chạy tiếp theo.
@@ -298,7 +298,7 @@ picoclaw-launcher-tui
```
-
+
**Bắt đầu:**
@@ -307,6 +307,7 @@ Sử dụng menu TUI để: **1)** Cấu hình Provider -> **2)** Cấu hình Ch
Để biết tài liệu TUI chi tiết, xem [docs.picoclaw.io](https://docs.picoclaw.io).
+
### 📱 Android
Hãy cho chiếc điện thoại cũ của bạn một cuộc sống mới! Biến nó thành Trợ lý AI thông minh với PicoClaw.
@@ -317,10 +318,10 @@ Xem trước:
@@ -344,7 +345,7 @@ termux-chroot ./picoclaw onboard # chroot provides a standard Linux filesystem
Sau đó làm theo phần Terminal Launcher bên dưới để hoàn tất cấu hình.
-
+
Đối với các môi trường tối giản chỉ có binary lõi `picoclaw` (không có Launcher UI), bạn có thể cấu hình mọi thứ qua dòng lệnh và tệp cấu hình JSON.
@@ -450,7 +451,7 @@ PicoClaw hỗ trợ 30+ Provider LLM thông qua cấu hình `model_list`. Sử d
}
```
-Để biết chi tiết cấu hình provider đầy đủ, xem [Providers & Models](docs/vi/providers.md).
+Để biết chi tiết cấu hình provider đầy đủ, xem [Providers & Models](../guides/providers.vi.md).
@@ -460,28 +461,28 @@ Trò chuyện với PicoClaw của bạn qua 17+ nền tảng nhắn tin:
| Channel | Thiết lập | Protocol | Tài liệu |
|---------|-----------|----------|----------|
-| **Telegram** | Dễ (bot token) | Long polling | [Hướng dẫn](docs/channels/telegram/README.vi.md) |
-| **Discord** | Dễ (bot token + intents) | WebSocket | [Hướng dẫn](docs/channels/discord/README.vi.md) |
-| **WhatsApp** | Dễ (quét QR hoặc bridge URL) | Native / Bridge | [Hướng dẫn](docs/vi/chat-apps.md#whatsapp) |
-| **Weixin** | Dễ (quét QR gốc) | iLink API | [Hướng dẫn](docs/vi/chat-apps.md#weixin) |
-| **QQ** | Dễ (AppID + AppSecret) | WebSocket | [Hướng dẫn](docs/channels/qq/README.vi.md) |
-| **Slack** | Dễ (bot + app token) | Socket Mode | [Hướng dẫn](docs/channels/slack/README.vi.md) |
-| **Matrix** | Trung bình (homeserver + token) | Sync API | [Hướng dẫn](docs/channels/matrix/README.vi.md) |
-| **DingTalk** | Trung bình (client credentials) | Stream | [Hướng dẫn](docs/channels/dingtalk/README.vi.md) |
-| **Feishu / Lark** | Trung bình (App ID + Secret) | WebSocket/SDK | [Hướng dẫn](docs/channels/feishu/README.vi.md) |
-| **LINE** | Trung bình (credentials + webhook) | Webhook | [Hướng dẫn](docs/channels/line/README.vi.md) |
-| **WeCom** | Dễ (đăng nhập QR hoặc thủ công) | WebSocket | [Hướng dẫn](docs/channels/wecom/README.md) |
-| **IRC** | Trung bình (server + nick) | IRC protocol | [Hướng dẫn](docs/vi/chat-apps.md#irc) |
-| **OneBot** | Trung bình (WebSocket URL) | OneBot v11 | [Hướng dẫn](docs/channels/onebot/README.vi.md) |
-| **MaixCam** | Dễ (bật) | TCP socket | [Hướng dẫn](docs/channels/maixcam/README.vi.md) |
+| **Telegram** | Dễ (bot token) | Long polling | [Hướng dẫn](../channels/telegram/README.vi.md) |
+| **Discord** | Dễ (bot token + intents) | WebSocket | [Hướng dẫn](../channels/discord/README.vi.md) |
+| **WhatsApp** | Dễ (quét QR hoặc bridge URL) | Native / Bridge | [Hướng dẫn](../guides/chat-apps.vi.md#whatsapp) |
+| **Weixin** | Dễ (quét QR gốc) | iLink API | [Hướng dẫn](../guides/chat-apps.vi.md#weixin) |
+| **QQ** | Dễ (AppID + AppSecret) | WebSocket | [Hướng dẫn](../channels/qq/README.vi.md) |
+| **Slack** | Dễ (bot + app token) | Socket Mode | [Hướng dẫn](../channels/slack/README.vi.md) |
+| **Matrix** | Trung bình (homeserver + token) | Sync API | [Hướng dẫn](../channels/matrix/README.vi.md) |
+| **DingTalk** | Trung bình (client credentials) | Stream | [Hướng dẫn](../channels/dingtalk/README.vi.md) |
+| **Feishu / Lark** | Trung bình (App ID + Secret) | WebSocket/SDK | [Hướng dẫn](../channels/feishu/README.vi.md) |
+| **LINE** | Trung bình (credentials + webhook) | Webhook | [Hướng dẫn](../channels/line/README.vi.md) |
+| **WeCom** | Dễ (đăng nhập QR hoặc thủ công) | WebSocket | [Hướng dẫn](../channels/wecom/README.vi.md) |
+| **IRC** | Trung bình (server + nick) | IRC protocol | [Hướng dẫn](../guides/chat-apps.vi.md#irc) |
+| **OneBot** | Trung bình (WebSocket URL) | OneBot v11 | [Hướng dẫn](../channels/onebot/README.vi.md) |
+| **MaixCam** | Dễ (bật) | TCP socket | [Hướng dẫn](../channels/maixcam/README.vi.md) |
| **Pico** | Dễ (bật) | Native protocol | Tích hợp sẵn |
| **Pico Client** | Dễ (WebSocket URL) | WebSocket | Tích hợp sẵn |
> Tất cả các Channel dựa trên webhook dùng chung một Gateway HTTP server (`gateway.host`:`gateway.port`, mặc định `127.0.0.1:18790`). Feishu sử dụng chế độ WebSocket/SDK và không dùng HTTP server chung.
-> Mức độ chi tiết log được kiểm soát bởi `gateway.log_level` (mặc định: `warn`). Các giá trị được hỗ trợ: `debug`, `info`, `warn`, `error`, `fatal`. Cũng có thể đặt qua `PICOCLAW_LOG_LEVEL`. Xem [Cấu hình](docs/vi/configuration.md#mức-log-của-gateway) để biết thêm chi tiết.
+> Mức độ chi tiết log được kiểm soát bởi `gateway.log_level` (mặc định: `warn`). Các giá trị được hỗ trợ: `debug`, `info`, `warn`, `error`, `fatal`. Cũng có thể đặt qua `PICOCLAW_LOG_LEVEL`. Xem [Cấu hình](../guides/configuration.vi.md#mức-log-của-gateway) để biết thêm chi tiết.
-Để biết hướng dẫn thiết lập Channel chi tiết, xem [Cấu hình Ứng dụng Chat](docs/vi/chat-apps.md).
+Để biết hướng dẫn thiết lập Channel chi tiết, xem [Cấu hình Ứng dụng Chat](../guides/chat-apps.vi.md).
## 🔧 Tools
@@ -501,7 +502,7 @@ PicoClaw có thể tìm kiếm web để cung cấp thông tin cập nhật. C
### ⚙️ Các Tools Khác
-PicoClaw bao gồm các tool tích hợp sẵn cho thao tác tệp, thực thi mã, lên lịch và nhiều hơn nữa. Xem [Cấu hình Tools](docs/vi/tools_configuration.md) để biết chi tiết.
+PicoClaw bao gồm các tool tích hợp sẵn cho thao tác tệp, thực thi mã, lên lịch và nhiều hơn nữa. Xem [Cấu hình Tools](../reference/tools_configuration.vi.md) để biết chi tiết.
## 🎯 Skills
@@ -531,7 +532,7 @@ Thêm vào `config.json` của bạn:
}
```
-Để biết thêm chi tiết, xem [Cấu hình Tools - Skills](docs/vi/tools_configuration.md#skills-tool).
+Để biết thêm chi tiết, xem [Cấu hình Tools - Skills](../reference/tools_configuration.vi.md#skills-tool).
## 🔗 MCP (Model Context Protocol)
@@ -554,9 +555,9 @@ PicoClaw hỗ trợ [MCP](https://modelcontextprotocol.io/) gốc — kết nố
}
```
-Để biết cấu hình MCP đầy đủ (stdio, SSE, HTTP transports, Tool Discovery), xem [Cấu hình Tools - MCP](docs/vi/tools_configuration.md#mcp-tool).
+Để biết cấu hình MCP đầy đủ (stdio, SSE, HTTP transports, Tool Discovery), xem [Cấu hình Tools - MCP](../reference/tools_configuration.vi.md#mcp-tool).
-## Tham gia Mạng xã hội Agent
+## Tham gia Mạng xã hội Agent
Kết nối PicoClaw với Mạng xã hội Agent chỉ bằng cách gửi một tin nhắn duy nhất qua CLI hoặc bất kỳ Ứng dụng Chat nào đã tích hợp.
@@ -597,23 +598,23 @@ PicoClaw hỗ trợ nhắc nhở đã lên lịch và tác vụ định kỳ th
| Chủ đề | Mô tả |
|--------|-------|
-| [Docker & Khởi động Nhanh](docs/vi/docker.md) | Thiết lập Docker Compose, chế độ Launcher/Agent |
-| [Ứng dụng Chat](docs/vi/chat-apps.md) | Hướng dẫn thiết lập 17+ Channel |
-| [Cấu hình](docs/vi/configuration.md) | Biến môi trường, bố cục workspace, sandbox bảo mật |
-| [Providers & Models](docs/vi/providers.md) | 30+ Provider LLM, định tuyến mô hình, cấu hình model_list |
-| [Spawn & Tác vụ Bất đồng bộ](docs/vi/spawn-tasks.md) | Tác vụ nhanh, tác vụ dài với spawn, điều phối sub-agent bất đồng bộ |
-| [Hooks](docs/hooks/README.md) | Hệ thống hook hướng sự kiện: observer, interceptor, approval hook |
-| [Steering](docs/steering.md) | Chèn tin nhắn vào vòng lặp agent đang chạy |
-| [SubTurn](docs/subturn.md) | Điều phối subagent, kiểm soát đồng thời, vòng đời |
-| [Khắc phục sự cố](docs/vi/troubleshooting.md) | Các vấn đề thường gặp và giải pháp |
-| [Cấu hình Tools](docs/vi/tools_configuration.md) | Bật/tắt từng tool, chính sách exec, MCP, Skills |
-| [Tương thích Phần cứng](docs/vi/hardware-compatibility.md) | Các board đã kiểm tra, yêu cầu tối thiểu |
+| [Docker & Khởi động Nhanh](../guides/docker.vi.md) | Thiết lập Docker Compose, chế độ Launcher/Agent |
+| [Ứng dụng Chat](../guides/chat-apps.vi.md) | Hướng dẫn thiết lập 17+ Channel |
+| [Cấu hình](../guides/configuration.vi.md) | Biến môi trường, bố cục workspace, sandbox bảo mật |
+| [Providers & Models](../guides/providers.vi.md) | 30+ Provider LLM, định tuyến mô hình, cấu hình model_list |
+| [Spawn & Tác vụ Bất đồng bộ](../guides/spawn-tasks.vi.md) | Tác vụ nhanh, tác vụ dài với spawn, điều phối sub-agent bất đồng bộ |
+| [Hooks](../architecture/hooks/README.md) | Hệ thống 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 |
+| [Khắc phục sự cố](../operations/troubleshooting.vi.md) | Các vấn đề thường gặp và giải pháp |
+| [Cấu hình Tools](../reference/tools_configuration.vi.md) | Bật/tắt từng tool, chính sách exec, MCP, Skills |
+| [Tương thích Phần cứng](../guides/hardware-compatibility.vi.md) | Các board đã kiểm tra, yêu cầu tối thiểu |
## 🤝 Đóng góp & Lộ trình
PR luôn được chào đón! Codebase được thiết kế nhỏ gọn và dễ đọc.
-Xem [Lộ trình Cộng đồng](https://github.com/sipeed/picoclaw/issues/988) và [CONTRIBUTING.md](CONTRIBUTING.md) để biết hướng dẫn.
+Xem [Lộ trình Cộng đồng](https://github.com/sipeed/picoclaw/issues/988) và [CONTRIBUTING.md](../../CONTRIBUTING.md) để biết hướng dẫn.
Nhóm nhà phát triển đang được xây dựng, tham gia sau khi PR đầu tiên của bạn được merge!
@@ -622,4 +623,4 @@ Nhóm Người dùng:
Discord:
WeChat:
-
+
diff --git a/README.zh.md b/docs/project/README.zh.md
similarity index 82%
rename from README.zh.md
rename to docs/project/README.zh.md
index 1a0659e22..a4fc892bd 100644
--- a/README.zh.md
+++ b/docs/project/README.zh.md
@@ -1,5 +1,5 @@
-
+
PicoClaw: 基于Go语言的超高效 AI 助手
@@ -14,11 +14,11 @@
-
+
-**中文** | [日本語](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](README.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.ms.md) | [English](../../README.md)
|
-
+
|
-
+
|
@@ -71,7 +71,7 @@
2026-02-26 🎉 PicoClaw 仅 17 天突破 **20K Stars**！频道自动编排和能力接口上线。
-2026-02-16 🎉 PicoClaw 一周内突破 12K Stars！社区维护者角色和 [路线图](ROADMAP.md) 正式发布。
+2026-02-16 🎉 PicoClaw 一周内突破 12K Stars！社区维护者角色和 [路线图](../../ROADMAP.md) 正式发布。
2026-02-13 🎉 PicoClaw 4 天内突破 5000 Stars！项目路线图和开发者群组筹建中。
@@ -108,14 +108,14 @@ _*近期版本因快速合并 PR 可能占用 10–20MB，资源优化已列入
| **启动时间**(0.8GHz core) | >500s | >30s | **<1s** |
| **成本** | Mac Mini $599 | 大多数 Linux 开发板 ~$50 | **任意 Linux 开发板****低至 $10** |
-
+
-> 📋 **[硬件兼容列表](docs/zh/hardware-compatibility.md)** — 查看所有已测试的板卡，从 $5 RISC-V 到树莓派到安卓手机。你的板卡没在列表中？欢迎提交 PR！
+> 📋 **[硬件兼容列表](../guides/hardware-compatibility.zh.md)** — 查看所有已测试的板卡，从 $5 RISC-V 到树莓派到安卓手机。你的板卡没在列表中？欢迎提交 PR！
-
+
## 🦾 演示
@@ -129,9 +129,9 @@ _*近期版本因快速合并 PR 可能占用 10–20MB，资源优化已列入
🔎 网络搜索与学习 |
-
|
-
|
-
|
+
|
+
|
+
|
| 开发 • 部署 • 扩展 |
@@ -220,7 +220,7 @@ picoclaw-launcher
> ```
-
+
**开始使用：**
@@ -274,7 +274,7 @@ macOS 可能会在首次启动时拦截 `picoclaw-launcher`，因为它从互联
**第一步：** 双击 `picoclaw-launcher`，会出现安全警告：
-
+
> *"picoclaw-launcher" 无法打开 — Apple 无法验证 "picoclaw-launcher" 不含可能损害 Mac 或危及隐私的恶意软件。*
@@ -282,7 +282,7 @@ macOS 可能会在首次启动时拦截 `picoclaw-launcher`，因为它从互联
**第二步：** 打开**系统设置** → **隐私与安全性** → 向下滚动找到**安全性**部分 → 点击**仍要打开** → 在弹窗中再次点击**打开**。
-
+
完成这一次操作后，后续启动 `picoclaw-launcher` 将不再弹出警告。
@@ -298,7 +298,7 @@ picoclaw-launcher-tui
```
-
+
**开始使用：**
@@ -307,6 +307,7 @@ picoclaw-launcher-tui
详细 TUI 文档请参阅 [docs.picoclaw.io](https://docs.picoclaw.io)。
+
### 📱 Android
让你十年前的旧手机焕发新生！将它变成你的 AI 助手。
@@ -317,10 +318,10 @@ picoclaw-launcher-tui
@@ -344,7 +345,7 @@ termux-chroot ./picoclaw onboard # chroot 提供标准 Linux 文件系统布
然后跟随下面的"Terminal Launcher"章节继续配置。
-
+
对于只有 `picoclaw` 核心二进制文件的极简环境（无 Launcher UI），可通过命令行和 JSON 配置文件完成所有配置。
@@ -450,7 +451,7 @@ PicoClaw 通过 `model_list` 配置支持 30+ LLM Provider，使用 `协议/模
}
```
-完整 Provider 配置详情请参阅 [Providers & Models](docs/zh/providers.md)。
+完整 Provider 配置详情请参阅 [Providers & Models](../guides/providers.zh.md)。
@@ -460,29 +461,29 @@ PicoClaw 通过 `model_list` 配置支持 30+ LLM Provider，使用 `协议/模
| Channel | 配置难度 | 协议 | 文档 |
|---------|----------|------|------|
-| **Telegram** | 简单（bot token） | 长轮询 | [指南](docs/channels/telegram/README.zh.md) |
-| **Discord** | 简单（bot token + intents） | WebSocket | [指南](docs/channels/discord/README.zh.md) |
-| **WhatsApp** | 简单（扫码或 bridge URL） | 原生 / Bridge | [指南](docs/zh/chat-apps.md#whatsapp) |
-| **微信 (Weixin)** | 简单（扫码登录） | iLink API | [指南](docs/zh/chat-apps.md#weixin) |
-| **QQ** | 简单（AppID + AppSecret） | WebSocket | [指南](docs/channels/qq/README.zh.md) |
-| **Slack** | 简单（bot + app token） | Socket Mode | [指南](docs/channels/slack/README.zh.md) |
-| **Matrix** | 中等（homeserver + token） | Sync API | [指南](docs/channels/matrix/README.zh.md) |
-| **钉钉** | 中等（client credentials） | Stream | [指南](docs/channels/dingtalk/README.zh.md) |
-| **飞书 / Lark** | 中等（App ID + Secret） | WebSocket/SDK | [指南](docs/channels/feishu/README.zh.md) |
-| **LINE** | 中等（credentials + webhook） | Webhook | [指南](docs/channels/line/README.zh.md) |
-| **企业微信** | 简单（扫码登录或手动配置） | WebSocket | [指南](docs/channels/wecom/README.zh.md) |
-| **VK** | 简单（群组 token） | Long Poll | [指南](docs/channels/vk/README.md) |
-| **IRC** | 中等（server + nick） | IRC 协议 | [指南](docs/zh/chat-apps.md#irc) |
-| **OneBot** | 中等（WebSocket URL） | OneBot v11 | [指南](docs/channels/onebot/README.zh.md) |
-| **MaixCam** | 简单（启用即可） | TCP socket | [指南](docs/channels/maixcam/README.zh.md) |
+| **Telegram** | 简单（bot token） | 长轮询 | [指南](../channels/telegram/README.zh.md) |
+| **Discord** | 简单（bot token + intents） | WebSocket | [指南](../channels/discord/README.zh.md) |
+| **WhatsApp** | 简单（扫码或 bridge URL） | 原生 / Bridge | [指南](../guides/chat-apps.zh.md#whatsapp) |
+| **微信 (Weixin)** | 简单（扫码登录） | iLink API | [指南](../guides/chat-apps.zh.md#weixin) |
+| **QQ** | 简单（AppID + AppSecret） | WebSocket | [指南](../channels/qq/README.zh.md) |
+| **Slack** | 简单（bot + app token） | Socket Mode | [指南](../channels/slack/README.zh.md) |
+| **Matrix** | 中等（homeserver + token） | Sync API | [指南](../channels/matrix/README.zh.md) |
+| **钉钉** | 中等（client credentials） | Stream | [指南](../channels/dingtalk/README.zh.md) |
+| **飞书 / Lark** | 中等（App ID + Secret） | WebSocket/SDK | [指南](../channels/feishu/README.zh.md) |
+| **LINE** | 中等（credentials + webhook） | Webhook | [指南](../channels/line/README.zh.md) |
+| **企业微信** | 简单（扫码登录或手动配置） | WebSocket | [指南](../channels/wecom/README.zh.md) |
+| **VK** | 简单（群组 token） | Long Poll | [指南](../channels/vk/README.md) |
+| **IRC** | 中等（server + nick） | IRC 协议 | [指南](../guides/chat-apps.zh.md#irc) |
+| **OneBot** | 中等（WebSocket URL） | OneBot v11 | [指南](../channels/onebot/README.zh.md) |
+| **MaixCam** | 简单（启用即可） | TCP socket | [指南](../channels/maixcam/README.zh.md) |
| **Pico** | 简单（启用即可） | 原生协议 | 内置 |
| **Pico Client** | 简单（WebSocket URL） | WebSocket | 内置 |
> 所有基于 Webhook 的 Channel 共用同一个 Gateway HTTP 服务器（`gateway.host`:`gateway.port`，默认 `127.0.0.1:18790`）。飞书使用 WebSocket/SDK 模式，不使用共享 HTTP 服务器。
-> 日志详细程度通过 `gateway.log_level` 控制（默认：`warn`）。支持的值：`debug`、`info`、`warn`、`error`、`fatal`。也可通过 `PICOCLAW_LOG_LEVEL` 环境变量设置。详见[配置指南](docs/zh/configuration.md#gateway-日志等级)。
+> 日志详细程度通过 `gateway.log_level` 控制（默认：`warn`）。支持的值：`debug`、`info`、`warn`、`error`、`fatal`。也可通过 `PICOCLAW_LOG_LEVEL` 环境变量设置。详见[配置指南](../guides/configuration.zh.md#gateway-日志等级)。
-详细 Channel 配置说明请参阅 [聊天应用配置](docs/zh/chat-apps.md)。
+详细 Channel 配置说明请参阅 [聊天应用配置](../guides/chat-apps.zh.md)。
## 🔧 Tools
@@ -502,7 +503,7 @@ PicoClaw 可以搜索网络以提供最新信息。在 `tools.web` 中配置：
### ⚙️ 其他工具
-PicoClaw 内置文件操作、代码执行、定时任务等工具。详情请参阅 [工具配置](docs/zh/tools_configuration.md)。
+PicoClaw 内置文件操作、代码执行、定时任务等工具。详情请参阅 [工具配置](../reference/tools_configuration.zh.md)。
## 🎯 Skills
@@ -539,7 +540,7 @@ picoclaw skills install
`tools.skills.github.*` 已废弃，请改用 `tools.skills.registries.github.*`。
-更多详情请参阅 [工具配置 - Skills](docs/zh/tools_configuration.md#skills-tool)。
+更多详情请参阅 [工具配置 - Skills](../reference/tools_configuration.zh.md#skills-tool)。
## 🔗 MCP (Model Context Protocol)
@@ -562,9 +563,9 @@ PicoClaw 原生支持 [MCP](https://modelcontextprotocol.io/) — 连接任意 M
}
```
-完整 MCP 配置（stdio、SSE、HTTP 传输、Tool Discovery）请参阅 [工具配置 - MCP](docs/zh/tools_configuration.md#mcp-tool)。
+完整 MCP 配置（stdio、SSE、HTTP 传输、Tool Discovery）请参阅 [工具配置 - MCP](../reference/tools_configuration.zh.md#mcp-tool)。
-## 加入 Agent 社交网络
+## 加入 Agent 社交网络
通过 CLI 或任何已集成的聊天应用发送一条消息，即可将 PicoClaw 连接到 Agent 社交网络。
@@ -605,23 +606,23 @@ PicoClaw 通过 `cron` 工具支持定时提醒和重复任务：
| 主题 | 说明 |
|------|------|
-| 🐳 [Docker 与快速开始](docs/zh/docker.md) | Docker Compose 配置、Launcher/Agent 模式、快速开始 |
-| 💬 [聊天应用配置](docs/zh/chat-apps.md) | 全部 17+ Channel 配置指南 |
-| ⚙️ [配置指南](docs/zh/configuration.md) | 环境变量、工作区布局、安全沙箱 |
-| 🔌 [提供商与模型配置](docs/zh/providers.md) | 30+ LLM Provider、模型路由、model_list 配置 |
-| 🔄 [异步任务与 Spawn](docs/zh/spawn-tasks.md) | 快速任务、长任务与 Spawn、异步子 Agent 编排 |
-| 🪝 [Hook 系统](docs/hooks/README.zh.md) | 事件驱动 Hook：观察者、拦截器、审批 Hook |
-| 🎯 [Steering](docs/steering.md) | 在工具调用间向运行中的 Agent 注入消息 |
-| 🔀 [SubTurn](docs/subturn.md) | 子 Agent 协调、并发控制、生命周期管理 |
-| 🐛 [疑难解答](docs/zh/troubleshooting.md) | 常见问题与解决方案 |
-| 🔧 [工具配置](docs/zh/tools_configuration.md) | 工具启用/禁用、执行策略、MCP、Skills |
-| 📋 [硬件兼容列表](docs/zh/hardware-compatibility.md) | 已测试板卡、最低要求 |
+| 🐳 [Docker 与快速开始](../guides/docker.zh.md) | Docker Compose 配置、Launcher/Agent 模式、快速开始 |
+| 💬 [聊天应用配置](../guides/chat-apps.zh.md) | 全部 17+ Channel 配置指南 |
+| ⚙️ [配置指南](../guides/configuration.zh.md) | 环境变量、工作区布局、安全沙箱 |
+| 🔌 [提供商与模型配置](../guides/providers.zh.md) | 30+ LLM Provider、模型路由、model_list 配置 |
+| 🔄 [异步任务与 Spawn](../guides/spawn-tasks.zh.md) | 快速任务、长任务与 Spawn、异步子 Agent 编排 |
+| 🪝 [Hook 系统](../architecture/hooks/README.zh.md) | 事件驱动 Hook：观察者、拦截器、审批 Hook |
+| 🎯 [Steering](../architecture/steering.md) | 在工具调用间向运行中的 Agent 注入消息 |
+| 🔀 [SubTurn](../architecture/subturn.md) | 子 Agent 协调、并发控制、生命周期管理 |
+| 🐛 [疑难解答](../operations/troubleshooting.zh.md) | 常见问题与解决方案 |
+| 🔧 [工具配置](../reference/tools_configuration.zh.md) | 工具启用/禁用、执行策略、MCP、Skills |
+| 📋 [硬件兼容列表](../guides/hardware-compatibility.zh.md) | 已测试板卡、最低要求 |
## 🤝 贡献与路线图
欢迎提交 PR！代码库刻意保持小巧和可读。🤗
-查看完整的 [社区路线图](https://github.com/sipeed/picoclaw/issues/988) 和 [CONTRIBUTING.md](CONTRIBUTING.md)。
+查看完整的 [社区路线图](https://github.com/sipeed/picoclaw/issues/988) 和 [CONTRIBUTING.md](../../CONTRIBUTING.md)。
开发者群组正在组建中，入群门槛：至少合并过 1 个 PR。
@@ -630,4 +631,4 @@ PicoClaw 通过 `cron` 工具支持定时提醒和重复任务：
Discord:
WeChat:
-
+
diff --git a/docs/reference/README.md b/docs/reference/README.md
new file mode 100644
index 000000000..eec5c09b4
--- /dev/null
+++ b/docs/reference/README.md
@@ -0,0 +1,8 @@
+# Reference
+
+Reference docs for precise configuration, runtime behavior, and tool semantics.
+
+- [Tools Configuration](tools_configuration.md): per-tool configuration, execution policies, MCP, and Skills.
+- [Scheduled Tasks and Cron Jobs](cron.md): schedule types, delivery modes, command gates, and storage.
+- [Config Schema Versioning Guide](config-versioning.md): config schema migration and compatibility notes.
+- [Dynamic Rate Limiting](rate-limiting.md): request throttling behavior for LLM providers.
diff --git a/docs/config-versioning.md b/docs/reference/config-versioning.md
similarity index 100%
rename from docs/config-versioning.md
rename to docs/reference/config-versioning.md
diff --git a/docs/cron.md b/docs/reference/cron.md
similarity index 100%
rename from docs/cron.md
rename to docs/reference/cron.md
diff --git a/docs/rate-limiting.md b/docs/reference/rate-limiting.md
similarity index 100%
rename from docs/rate-limiting.md
rename to docs/reference/rate-limiting.md
diff --git a/docs/fr/tools_configuration.md b/docs/reference/tools_configuration.fr.md
similarity index 99%
rename from docs/fr/tools_configuration.md
rename to docs/reference/tools_configuration.fr.md
index e64217c46..109c9cd6f 100644
--- a/docs/fr/tools_configuration.md
+++ b/docs/reference/tools_configuration.fr.md
@@ -1,6 +1,6 @@
# 🔧 Configuration des Outils
-> Retour au [README](../../README.fr.md)
+> Retour au [README](../project/README.fr.md)
La configuration des outils de PicoClaw se trouve dans le champ `tools` de `config.json`.
@@ -207,6 +207,7 @@ L'outil cron est utilisé pour planifier des tâches périodiques.
|------------------------|------|------------|----------------------------------------------------|
| `exec_timeout_minutes` | int | 5 | Délai d'expiration en minutes, 0 signifie sans limite |
+
## Outil MCP
L'outil MCP permet l'intégration avec des serveurs Model Context Protocol externes.
@@ -362,6 +363,7 @@ Au lieu de charger tous les outils, le LLM reçoit un outil de recherche léger
}
```
+
## Outil Skills
L'outil skills configure la découverte et l'installation de compétences via des registres comme ClawHub.
diff --git a/docs/ja/tools_configuration.md b/docs/reference/tools_configuration.ja.md
similarity index 99%
rename from docs/ja/tools_configuration.md
rename to docs/reference/tools_configuration.ja.md
index a31e58984..a331c869e 100644
--- a/docs/ja/tools_configuration.md
+++ b/docs/reference/tools_configuration.ja.md
@@ -1,6 +1,6 @@
# 🔧 ツール設定
-> [README](../../README.ja.md) に戻る
+> [README](../project/README.ja.md) に戻る
PicoClaw のツール設定は `config.json` の `tools` フィールドにあります。
@@ -207,6 +207,7 @@ Cron ツールは定期タスクのスケジューリングに使用されます
|------------------------|-----|------------|-----------------------------------------|
| `exec_timeout_minutes` | int | 5 | 実行タイムアウト（分）、0 は無制限 |
+
## MCP ツール
MCP ツールは外部の Model Context Protocol サーバーとの統合を可能にします。
@@ -362,6 +363,7 @@ MCP ツールは外部の Model Context Protocol サーバーとの統合を可
}
```
+
## Skills ツール
Skills ツールは ClawHub などのレジストリを通じたスキルの発見とインストールを設定します。
diff --git a/docs/tools_configuration.md b/docs/reference/tools_configuration.md
similarity index 99%
rename from docs/tools_configuration.md
rename to docs/reference/tools_configuration.md
index b043716ed..fa33f0bb4 100644
--- a/docs/tools_configuration.md
+++ b/docs/reference/tools_configuration.md
@@ -30,7 +30,7 @@ PicoClaw's tools configuration is located in the `tools` field of `config.json`.
Before tool results are sent to the LLM, PicoClaw can filter sensitive values (API keys, tokens, secrets) from the output. This prevents the LLM from seeing its own credentials.
-See [Sensitive Data Filtering](../sensitive_data_filtering.md) for full documentation.
+See [Sensitive Data Filtering](../security/sensitive_data_filtering.md) for full documentation.
| Config | Type | Default | Description |
|--------|------|---------|-------------|
diff --git a/docs/pt-br/tools_configuration.md b/docs/reference/tools_configuration.pt-br.md
similarity index 99%
rename from docs/pt-br/tools_configuration.md
rename to docs/reference/tools_configuration.pt-br.md
index 0eea7209a..3dae0f908 100644
--- a/docs/pt-br/tools_configuration.md
+++ b/docs/reference/tools_configuration.pt-br.md
@@ -1,6 +1,6 @@
# 🔧 Configuração de Ferramentas
-> Voltar ao [README](../../README.pt-br.md)
+> Voltar ao [README](../project/README.pt-br.md)
A configuração de ferramentas do PicoClaw está localizada no campo `tools` do `config.json`.
@@ -207,6 +207,7 @@ A ferramenta cron é usada para agendar tarefas periódicas.
|------------------------|------|--------|-----------------------------------------------------|
| `exec_timeout_minutes` | int | 5 | Tempo limite de execução em minutos, 0 significa sem limite |
+
## Ferramenta MCP
A ferramenta MCP permite a integração com servidores Model Context Protocol externos.
@@ -362,6 +363,7 @@ Em vez de carregar todas as ferramentas, o LLM recebe uma ferramenta de pesquisa
}
```
+
## Ferramenta Skills
A ferramenta skills configura a descoberta e instalação de habilidades via registros como o ClawHub.
diff --git a/docs/vi/tools_configuration.md b/docs/reference/tools_configuration.vi.md
similarity index 99%
rename from docs/vi/tools_configuration.md
rename to docs/reference/tools_configuration.vi.md
index 14abbfba7..7d65ca377 100644
--- a/docs/vi/tools_configuration.md
+++ b/docs/reference/tools_configuration.vi.md
@@ -1,6 +1,6 @@
# 🔧 Cấu Hình Công Cụ
-> Quay lại [README](../../README.vi.md)
+> Quay lại [README](../project/README.vi.md)
Cấu hình công cụ của PicoClaw nằm trong trường `tools` của `config.json`.
@@ -207,6 +207,7 @@ Công cụ cron được sử dụng để lên lịch các tác vụ định k
|--------------------------|------|----------|-----------------------------------------------------|
| `exec_timeout_minutes` | int | 5 | Thời gian chờ thực thi tính bằng phút, 0 nghĩa là không giới hạn |
+
## Công cụ MCP
Công cụ MCP cho phép tích hợp với các máy chủ Model Context Protocol bên ngoài.
@@ -362,6 +363,7 @@ Thay vì tải tất cả các công cụ, LLM được cung cấp một công c
}
```
+
## Công cụ Skills
Công cụ skills cấu hình khám phá và cài đặt kỹ năng thông qua các registry như ClawHub.
diff --git a/docs/zh/tools_configuration.md b/docs/reference/tools_configuration.zh.md
similarity index 99%
rename from docs/zh/tools_configuration.md
rename to docs/reference/tools_configuration.zh.md
index 9b3bfe4cf..3937a6254 100644
--- a/docs/zh/tools_configuration.md
+++ b/docs/reference/tools_configuration.zh.md
@@ -1,6 +1,6 @@
# 🔧 工具配置
-> 返回 [README](../../README.zh.md)
+> 返回 [README](../project/README.zh.md)
PicoClaw 的工具配置位于 `config.json` 的 `tools` 字段中。
@@ -32,7 +32,7 @@ PicoClaw 的工具配置位于 `config.json` 的 `tools` 字段中。
在将工具结果发送给 LLM 之前，PicoClaw 可以从输出中过滤敏感值（API 密钥、令牌、密码）。这可以防止 LLM 看到自己的凭据。
-详细说明请参阅[敏感数据过滤](../sensitive_data_filtering.md)。
+详细说明请参阅[敏感数据过滤](../security/sensitive_data_filtering.zh.md)。
| 配置项 | 类型 | 默认值 | 描述 |
|--------|------|--------|------|
@@ -234,6 +234,7 @@ Cron 工具用于调度周期性任务。
| `exec_timeout_minutes` | int | 5 | 执行超时时间（分钟），0 表示无限制 |
| `allow_command` | bool | false | 允许 cron 任务执行 shell 命令 |
+
## MCP 工具
MCP 工具支持与外部 Model Context Protocol 服务器集成。
@@ -389,6 +390,7 @@ LLM 不会加载所有工具，而是获得一个轻量级搜索工具（使用
}
```
+
## Skills 工具
Skills 工具配置通过 ClawHub 等注册表进行技能发现和安装。
diff --git a/docs/fr/ANTIGRAVITY_AUTH.md b/docs/security/ANTIGRAVITY_AUTH.fr.md
similarity index 99%
rename from docs/fr/ANTIGRAVITY_AUTH.md
rename to docs/security/ANTIGRAVITY_AUTH.fr.md
index 6cadf5238..8550c94e3 100644
--- a/docs/fr/ANTIGRAVITY_AUTH.md
+++ b/docs/security/ANTIGRAVITY_AUTH.fr.md
@@ -1,4 +1,4 @@
-> Retour au [README](../../README.fr.md)
+> Retour au [README](../project/README.fr.md)
# Guide d'authentification et d'intégration Antigravity
diff --git a/docs/ja/ANTIGRAVITY_AUTH.md b/docs/security/ANTIGRAVITY_AUTH.ja.md
similarity index 99%
rename from docs/ja/ANTIGRAVITY_AUTH.md
rename to docs/security/ANTIGRAVITY_AUTH.ja.md
index b55e4ab1b..e5ba91f8e 100644
--- a/docs/ja/ANTIGRAVITY_AUTH.md
+++ b/docs/security/ANTIGRAVITY_AUTH.ja.md
@@ -1,4 +1,4 @@
-> [README](../../README.ja.md) に戻る
+> [README](../project/README.ja.md) に戻る
# Antigravity 認証・統合ガイド
diff --git a/docs/ANTIGRAVITY_AUTH.md b/docs/security/ANTIGRAVITY_AUTH.md
similarity index 100%
rename from docs/ANTIGRAVITY_AUTH.md
rename to docs/security/ANTIGRAVITY_AUTH.md
diff --git a/docs/pt-br/ANTIGRAVITY_AUTH.md b/docs/security/ANTIGRAVITY_AUTH.pt-br.md
similarity index 99%
rename from docs/pt-br/ANTIGRAVITY_AUTH.md
rename to docs/security/ANTIGRAVITY_AUTH.pt-br.md
index d243783cb..626dc7433 100644
--- a/docs/pt-br/ANTIGRAVITY_AUTH.md
+++ b/docs/security/ANTIGRAVITY_AUTH.pt-br.md
@@ -1,4 +1,4 @@
-> Voltar ao [README](../../README.pt-br.md)
+> Voltar ao [README](../project/README.pt-br.md)
# Guia de Autenticação e Integração do Antigravity
diff --git a/docs/vi/ANTIGRAVITY_AUTH.md b/docs/security/ANTIGRAVITY_AUTH.vi.md
similarity index 99%
rename from docs/vi/ANTIGRAVITY_AUTH.md
rename to docs/security/ANTIGRAVITY_AUTH.vi.md
index 783dc5181..0800ce0f2 100644
--- a/docs/vi/ANTIGRAVITY_AUTH.md
+++ b/docs/security/ANTIGRAVITY_AUTH.vi.md
@@ -1,4 +1,4 @@
-> Quay lại [README](../../README.vi.md)
+> Quay lại [README](../project/README.vi.md)
# Hướng dẫn Xác thực và Tích hợp Antigravity
diff --git a/docs/zh/ANTIGRAVITY_AUTH.md b/docs/security/ANTIGRAVITY_AUTH.zh.md
similarity index 99%
rename from docs/zh/ANTIGRAVITY_AUTH.md
rename to docs/security/ANTIGRAVITY_AUTH.zh.md
index db7c81dea..5ae5c8afe 100644
--- a/docs/zh/ANTIGRAVITY_AUTH.md
+++ b/docs/security/ANTIGRAVITY_AUTH.zh.md
@@ -1,4 +1,4 @@
-> 返回 [README](../../README.zh.md)
+> 返回 [README](../project/README.zh.md)
# Antigravity 认证与集成指南
diff --git a/docs/security/README.md b/docs/security/README.md
new file mode 100644
index 000000000..7bd42da18
--- /dev/null
+++ b/docs/security/README.md
@@ -0,0 +1,8 @@
+# Security
+
+Security-focused docs covering configuration, secrets handling, and provider auth.
+
+- [Security Configuration](security_configuration.md): security-related config knobs and hardening guidance.
+- [Sensitive Data Filtering](sensitive_data_filtering.md): filtering secrets from tool output before model use.
+- [Credential Encryption](credential_encryption.md): encrypting stored API keys and credentials.
+- [Antigravity Authentication & Integration Guide](ANTIGRAVITY_AUTH.md): auth flow and integration notes for the Antigravity provider.
diff --git a/docs/fr/credential_encryption.md b/docs/security/credential_encryption.fr.md
similarity index 99%
rename from docs/fr/credential_encryption.md
rename to docs/security/credential_encryption.fr.md
index eec765039..67e2ed123 100644
--- a/docs/fr/credential_encryption.md
+++ b/docs/security/credential_encryption.fr.md
@@ -1,4 +1,4 @@
-> Retour au [README](../../README.fr.md)
+> Retour au [README](../project/README.fr.md)
# Chiffrement des identifiants
diff --git a/docs/ja/credential_encryption.md b/docs/security/credential_encryption.ja.md
similarity index 99%
rename from docs/ja/credential_encryption.md
rename to docs/security/credential_encryption.ja.md
index ea74b65d2..9eeba98b4 100644
--- a/docs/ja/credential_encryption.md
+++ b/docs/security/credential_encryption.ja.md
@@ -1,4 +1,4 @@
-> [README](../../README.ja.md) に戻る
+> [README](../project/README.ja.md) に戻る
# クレデンシャル暗号化
diff --git a/docs/credential_encryption.md b/docs/security/credential_encryption.md
similarity index 100%
rename from docs/credential_encryption.md
rename to docs/security/credential_encryption.md
diff --git a/docs/pt-br/credential_encryption.md b/docs/security/credential_encryption.pt-br.md
similarity index 99%
rename from docs/pt-br/credential_encryption.md
rename to docs/security/credential_encryption.pt-br.md
index 59a31e438..d4a84be8e 100644
--- a/docs/pt-br/credential_encryption.md
+++ b/docs/security/credential_encryption.pt-br.md
@@ -1,4 +1,4 @@
-> Voltar ao [README](../../README.pt-br.md)
+> Voltar ao [README](../project/README.pt-br.md)
# Criptografia de Credenciais
diff --git a/docs/vi/credential_encryption.md b/docs/security/credential_encryption.vi.md
similarity index 99%
rename from docs/vi/credential_encryption.md
rename to docs/security/credential_encryption.vi.md
index 9ba24588b..38d568b94 100644
--- a/docs/vi/credential_encryption.md
+++ b/docs/security/credential_encryption.vi.md
@@ -1,4 +1,4 @@
-> Quay lại [README](../../README.vi.md)
+> Quay lại [README](../project/README.vi.md)
# Mã hóa Thông tin Xác thực
diff --git a/docs/zh/credential_encryption.md b/docs/security/credential_encryption.zh.md
similarity index 99%
rename from docs/zh/credential_encryption.md
rename to docs/security/credential_encryption.zh.md
index 2105e4307..5083eee18 100644
--- a/docs/zh/credential_encryption.md
+++ b/docs/security/credential_encryption.zh.md
@@ -1,4 +1,4 @@
-> 返回 [README](../../README.zh.md)
+> 返回 [README](../project/README.zh.md)
# 凭据加密
diff --git a/docs/security_configuration.md b/docs/security/security_configuration.md
similarity index 100%
rename from docs/security_configuration.md
rename to docs/security/security_configuration.md
diff --git a/docs/sensitive_data_filtering.md b/docs/security/sensitive_data_filtering.md
similarity index 98%
rename from docs/sensitive_data_filtering.md
rename to docs/security/sensitive_data_filtering.md
index 0c10ff01d..e2d9de427 100644
--- a/docs/sensitive_data_filtering.md
+++ b/docs/security/sensitive_data_filtering.md
@@ -104,4 +104,4 @@ The model is using API key [FILTERED] and Telegram bot [FILTERED]
## Related
- [Credential Encryption](./credential_encryption.md) — encrypting API keys in config
-- [Tools Configuration](./tools_configuration.md)
+- [Tools Configuration](../reference/tools_configuration.md)
diff --git a/docs/zh/sensitive_data_filtering.md b/docs/security/sensitive_data_filtering.zh.md
similarity index 95%
rename from docs/zh/sensitive_data_filtering.md
rename to docs/security/sensitive_data_filtering.zh.md
index 4382706ed..6ff1acc20 100644
--- a/docs/zh/sensitive_data_filtering.md
+++ b/docs/security/sensitive_data_filtering.zh.md
@@ -103,5 +103,5 @@ The model is using API key [FILTERED] and Telegram bot [FILTERED]
## 相关文档
-- [凭据加密](../credential_encryption.md) — 配置中 API 密钥的加密
-- [工具配置](../tools_configuration.md)
+- [凭据加密](./credential_encryption.zh.md) — 配置中 API 密钥的加密
+- [工具配置](../reference/tools_configuration.zh.md)
diff --git a/pkg/audio/asr/README_zh.md b/pkg/audio/asr/README.zh.md
similarity index 100%
rename from pkg/audio/asr/README_zh.md
rename to pkg/audio/asr/README.zh.md
diff --git a/pkg/audio/tts/README_zh.md b/pkg/audio/tts/README.zh.md
similarity index 100%
rename from pkg/audio/tts/README_zh.md
rename to pkg/audio/tts/README.zh.md
diff --git a/pkg/isolation/README_CN.md b/pkg/isolation/README.zh.md
similarity index 100%
rename from pkg/isolation/README_CN.md
rename to pkg/isolation/README.zh.md
diff --git a/scripts/lint-docs.sh b/scripts/lint-docs.sh
new file mode 100755
index 000000000..7351298b6
--- /dev/null
+++ b/scripts/lint-docs.sh
@@ -0,0 +1,219 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+cd "$(git rev-parse --show-toplevel)"
+
+failures=0
+
+error() {
+ local path="$1"
+ local reason="$2"
+ local suggestion="${3:-}"
+
+ echo "docs lint: $path" >&2
+ echo " reason: $reason" >&2
+ if [[ -n "$suggestion" ]]; then
+ echo " fix: $suggestion" >&2
+ fi
+ failures=1
+}
+
+lowercase() {
+ printf '%s' "$1" | tr '[:upper:]' '[:lower:]'
+}
+
+suggest_noncanonical_translation_name() {
+ local path="$1"
+ local dir
+ local base
+ local stem
+ local locale
+
+ dir="$(dirname "$path")"
+ base="$(basename "$path")"
+
+ if [[ "$base" =~ ^(.+)_([A-Za-z]{2}(-[A-Za-z]{2})?)\.md$ ]]; then
+ stem="${BASH_REMATCH[1]}"
+ locale="$(lowercase "${BASH_REMATCH[2]}")"
+ printf '%s/%s.%s.md' "$dir" "$stem" "$locale"
+ return
+ fi
+
+ if [[ "$base" =~ ^(.+)\.([A-Za-z]{2}(-[A-Za-z]{2})?)\.md$ ]]; then
+ stem="${BASH_REMATCH[1]}"
+ locale="$(lowercase "${BASH_REMATCH[2]}")"
+ printf '%s/%s.%s.md' "$dir" "$stem" "$locale"
+ return
+ fi
+
+ printf 'rename it to use a lowercase ..md suffix beside the English source'
+}
+
+suggest_docs_language_bucket_target() {
+ local path="$1"
+ local locale
+ local file
+ local name
+ local -a matches
+
+ if [[ "$path" =~ ^docs/([A-Za-z]{2}(-[A-Za-z]{2})?)/.+\.md$ ]]; then
+ locale="$(lowercase "${BASH_REMATCH[1]}")"
+ file="$(basename "$path")"
+ name="${file%.md}"
+ mapfile -t matches < <(find docs/project docs/guides docs/reference docs/operations docs/security docs/architecture docs/channels docs/design docs/migration -type f -name "${name}.md" 2>/dev/null | sort)
+ if [[ "${#matches[@]}" -eq 1 ]]; then
+ printf '%s' "${matches[0]%.md}.${locale}.md"
+ return
+ fi
+ fi
+
+ printf 'move it to a typed docs directory and rename it to ..md beside the English source'
+}
+
+suggest_nested_locale_bucket_target() {
+ local path="$1"
+ local prefix
+ local locale
+ local rest
+
+ if [[ "$path" =~ ^(docs/(project|guides|reference|operations|security|architecture|design|migration))/([A-Za-z]{2}(-[A-Za-z]{2})?)/(.*)\.md$ ]]; then
+ prefix="${BASH_REMATCH[1]}"
+ locale="$(lowercase "${BASH_REMATCH[3]}")"
+ rest="${BASH_REMATCH[5]}"
+ printf '%s/%s.%s.md' "$prefix" "$rest" "$locale"
+ return
+ fi
+
+ if [[ "$path" =~ ^(docs/channels/[^/]+)/([A-Za-z]{2}(-[A-Za-z]{2})?)/(.*)\.md$ ]]; then
+ prefix="${BASH_REMATCH[1]}"
+ locale="$(lowercase "${BASH_REMATCH[2]}")"
+ rest="${BASH_REMATCH[4]}"
+ printf '%s/%s.%s.md' "$prefix" "$rest" "$locale"
+ return
+ fi
+
+ printf 'move the file beside its English source and rename it to ..md'
+}
+
+is_noncanonical_translation_name() {
+ local path="$1"
+ local base
+
+ base="$(basename "$path")"
+
+ [[ "$base" =~ ^.+_[A-Za-z]{2}(-[A-Za-z]{2})?\.md$ ]] && return 0
+ [[ "$base" =~ ^.+\.[A-Z]{2}(-[A-Z]{2})?\.md$ ]] && return 0
+ [[ "$base" =~ ^.+\.[a-z]{2}-[A-Z]{2}\.md$ ]] && return 0
+ [[ "$base" =~ ^.+\.[A-Z]{2}-[a-z]{2}\.md$ ]] && return 0
+
+ return 1
+}
+
+is_noncanonical_locale_bucket() {
+ local path="$1"
+
+ [[ "$path" =~ ^docs/(project|guides|reference|operations|security|architecture|design|migration)/[A-Za-z]{2}(-[A-Za-z]{2})?/ ]] && return 0
+ [[ "$path" =~ ^docs/channels/[^/]+/[A-Za-z]{2}(-[A-Za-z]{2})?/ ]] && return 0
+ return 1
+}
+
+is_root_docs_language_bucket() {
+ local path="$1"
+ [[ "$path" =~ ^docs/[A-Za-z]{2}(-[A-Za-z]{2})?/ ]]
+}
+
+is_translation_file() {
+ local path="$1"
+ [[ "$path" =~ ^(.+)\.([a-z]{2})(-[a-z]{2})?\.md$ ]]
+}
+
+translation_base() {
+ local path="$1"
+ local locale="$2"
+
+ if [[ "$path" == docs/project/* ]]; then
+ local rel="${path#docs/project/}"
+ echo "${rel%.$locale.md}.md"
+ return
+ fi
+
+ echo "${path%.$locale.md}.md"
+}
+
+while IFS= read -r path; do
+ [[ -f "$path" ]] || continue
+
+ case "$path" in
+ README.*.md)
+ error \
+ "$path" \
+ "translated project entry docs must live under docs/project/" \
+ "move it to docs/project/$(basename "$path")"
+ ;;
+ CONTRIBUTING.*.md)
+ error \
+ "$path" \
+ "translated project entry docs must live under docs/project/" \
+ "move it to docs/project/$(basename "$path")"
+ ;;
+ esac
+
+ if [[ "$path" =~ (^|/)README_[A-Za-z0-9-]+\.md$ ]]; then
+ error \
+ "$path" \
+ "legacy README translation names are not allowed" \
+ "rename it to use README..md, for example $(suggest_noncanonical_translation_name "$path")"
+ fi
+
+ if is_noncanonical_translation_name "$path"; then
+ error \
+ "$path" \
+ "translation files must use lowercase ..md suffixes and no underscore variants" \
+ "rename it to $(suggest_noncanonical_translation_name "$path")"
+ fi
+
+ if is_root_docs_language_bucket "$path"; then
+ error \
+ "$path" \
+ "language bucket directories under docs/ are not allowed" \
+ "move it to $(suggest_docs_language_bucket_target "$path")"
+ fi
+
+ if is_noncanonical_locale_bucket "$path"; then
+ error \
+ "$path" \
+ "translations must live beside the English source, not under locale-named subdirectories" \
+ "move it to $(suggest_nested_locale_bucket_target "$path")"
+ fi
+
+ if [[ "$path" =~ ^docs/[^/]+\.md$ && "$path" != "docs/README.md" ]]; then
+ error \
+ "$path" \
+ "top-level docs Markdown files must move into a typed docs/ subdirectory" \
+ "move it into one of docs/project/, docs/guides/, docs/reference/, docs/operations/, docs/security/, docs/architecture/, docs/channels/, docs/design/, or docs/migration/"
+ fi
+
+ if is_translation_file "$path"; then
+ locale="${BASH_REMATCH[2]}${BASH_REMATCH[3]}"
+
+ if [[ "$path" == docs/design/* ]]; then
+ continue
+ fi
+
+ base="$(translation_base "$path" "$locale")"
+ if [[ ! -f "$base" ]]; then
+ error \
+ "$path" \
+ "missing English source document '$base'" \
+ "add the English source document at '$base' or move this translation beside the correct English source"
+ fi
+ fi
+done < <(git ls-files --cached --others --exclude-standard -- '*.md')
+
+if [[ "$failures" -ne 0 ]]; then
+ echo "docs lint: failed" >&2
+ exit 1
+fi
+
+echo "docs lint: OK"
diff --git a/web/README.md b/web/README.md
index 9fc7007e9..0bda4b421 100644
--- a/web/README.md
+++ b/web/README.md
@@ -377,7 +377,7 @@ If you run only `make dev-backend`, either run `make dev-frontend` alongside it
## Related Docs
- Main project overview: [`../README.md`](../README.md)
-- Configuration guide: [`../docs/configuration.md`](../docs/configuration.md)
-- Providers: [`../docs/providers.md`](../docs/providers.md)
-- Troubleshooting: [`../docs/troubleshooting.md`](../docs/troubleshooting.md)
+- Configuration guide: [`../docs/guides/configuration.md`](../docs/guides/configuration.md)
+- Providers: [`../docs/guides/providers.md`](../docs/guides/providers.md)
+- Troubleshooting: [`../docs/operations/troubleshooting.md`](../docs/operations/troubleshooting.md)
- Official docs site: [docs.picoclaw.io](https://docs.picoclaw.io)
