sipeed · fossler · Feb 19, 2026 · Feb 19, 2026 · Feb 19, 2026 · Feb 19, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,182 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build and Development Commands
+
+```bash
+# Download dependencies
+make deps
+
+# Build for current platform (runs go generate first)
+make build
+
+# Build for all platforms (linux-amd64, linux-arm64, linux-loong64, linux-riscv64, darwin-arm64, windows-amd64)
+make build-all
+
+# Run tests
+make test
+
+# Run specific test
+go test ./pkg/agent/... -v
+go test ./pkg/providers/... -v -run TestFallbackChain
+
+# Run linter
+make vet
+
+# Format code
+make fmt
+
+# Full check (deps, fmt, vet, test)
+make check
+
+# Install to ~/.local/bin
+make install
+
+# Run with message
+./build/picoclaw agent -m "Hello"
+
+# Run interactive mode
+./build/picoclaw agent
+
+# Start gateway (connects to Telegram, Discord, etc.)
+./build/picoclaw gateway
+
+# Debug mode
+./build/picoclaw agent --debug -m "Hello"
+```
+
+## Architecture Overview
+
+PicoClaw is an ultra-lightweight AI assistant written in Go. It follows a message bus architecture where channels (Telegram, Discord, etc.) publish inbound messages and subscribe to outbound responses.
+
+### Core Components
+
+```
+cmd/picoclaw/main.go     # Entry point, CLI commands
+pkg/
+├── agent/               # Core agent logic
+│   ├── loop.go          # AgentLoop - message processing, LLM iteration
+│   ├── instance.go      # AgentInstance - per-agent configuration
+│   ├── registry.go      # AgentRegistry - multi-agent support
+│   └── context.go       # ContextBuilder - builds LLM messages
+├── bus/                 # Message bus for async communication
+├── channels/            # Chat platform integrations (Telegram, Discord, etc.)
+├── providers/           # LLM provider implementations
+│   ├── openai_compat/   # OpenAI-compatible API (OpenRouter, Groq, etc.)
+│   ├── anthropic/       # Anthropic/Claude API
+│   └── fallback.go      # Fallback chain for model redundancy
+├── tools/               # Tool implementations (files, exec, web, spawn)
+├── session/             # Session/history management
+├── config/              # Configuration loading
+├── routing/             # Message routing to agents
+├── skills/              # Skill loading system
+├── cron/                # Scheduled tasks
+└── heartbeat/           # Periodic task execution
+```
+
+### Data Flow
+
+1. **Inbound**: Channel receives message → publishes to bus → AgentLoop consumes
+2. **Processing**: AgentLoop routes to agent → builds context → calls LLM → executes tools
+3. **Outbound**: Tool/agent publishes response → bus → channel sends to platform
+
+### Key Patterns
+
+- **Tool Interface** ([base.go](pkg/tools/base.go)): All tools implement `Tool` interface with `Name()`, `Description()`, `Parameters()`, `Execute()`
+- **ContextualTool**: Tools can implement `SetContext(channel, chatID)` to receive message context
+- **AsyncTool**: Tools can implement `SetCallback()` for async operations (spawn, cron)
+- **LLMProvider Interface** ([types.go](pkg/providers/types.go)): `Chat()` method with messages, tools, model, options
+- **Message Bus** ([bus.go](pkg/bus/bus.go)): Buffered channels (100 capacity) for inbound/outbound messages
+
+### LLM Provider Selection
+
+Providers are selected via config:
+1. Check `providers.openrouter.api_key` → use OpenRouter
+2. Check `providers.zhipu.api_key` → use Zhipu
+3. Check `providers.openai.api_key` → use OpenAI
+4. etc.
+
+Model format: `"provider/model"` (e.g., `"openrouter/anthropic/claude-opus-4-5"`) or just model name if provider is inferred.
+
+### Multi-Agent Support
+
+Agents are defined in `config.json` under `agents.list`. Each agent has:
+- `id`: Unique identifier
+- `workspace`: Isolated workspace directory
+- `model`: Model configuration with optional fallbacks
+- `subagents`: Allowed subagent IDs for spawn tool
+
+Routing binds channels to specific agents via `bindings` array.
+
+### Session Management
+
+Sessions are stored in `workspace/sessions/<session_key>.json`. Each session tracks:
+- Message history
+- Summary (auto-generated when history exceeds threshold)
+- Last access time
+
+### Security Sandbox
+
+When `restrict_to_workspace: true` (default):
+- File operations limited to workspace directory
+- Shell commands must execute within workspace
+- Dangerous commands always blocked (rm -rf, format, dd, shutdown)
+
+## Configuration
+
+Config file: `~/.picoclaw/config.json`
+
+Key environment variables (override config):
+- `PICOCLAW_AGENTS_DEFAULTS_MODEL` - Default model
+- `PICOCLAW_HEARTBEAT_ENABLED` - Enable periodic tasks
+- `PICOCLAW_TOOLS_WEB_DUCKDUCKGO_ENABLED` - Enable DuckDuckGo search
+
+Workspace layout:
+```
+~/.picoclaw/workspace/
+├── sessions/          # Conversation history
+├── memory/            # Long-term memory (MEMORY.md)
+├── cron/              # Scheduled jobs
+├── skills/            # Custom skills
+├── AGENT.md           # Agent behavior guide
+├── IDENTITY.md        # Agent identity
+└── HEARTBEAT.md       # Periodic task prompts
+```
+
+## Testing
+
+Tests use standard Go testing. Run with:
+```bash
+make test              # All tests
+go test ./pkg/... -v   # Verbose
+```
+
+Integration tests (require external APIs) are tagged with `//go:build integration`.
+
+## Code Style
+
+- Standard Go formatting (`gofmt`, `go fmt`)
+- Error wrapping with `fmt.Errorf("context: %w", err)`
+- Structured logging via `pkg/logger` with component and fields
+- JSON config uses `json:` tags with snake_case
+
+## Reference Documentation
+
+Read these documents when working on specific areas:
+
+| Document | When to Read |
+|----------|--------------|
+| [docs/developer-guide/architecture.md](docs/developer-guide/architecture.md) | Understanding system architecture, components, data flow |
+| [docs/developer-guide/data-flow.md](docs/developer-guide/data-flow.md) | Message bus, event processing, request lifecycle |
+| [docs/developer-guide/building.md](docs/developer-guide/building.md) | Building from source, cross-compilation, dependencies |
+| [docs/developer-guide/testing.md](docs/developer-guide/testing.md) | Running tests, writing new tests, test patterns |
+| [docs/developer-guide/extending/creating-tools.md](docs/developer-guide/extending/creating-tools.md) | Implementing new tools, Tool interface, parameters |
+| [docs/developer-guide/extending/creating-providers.md](docs/developer-guide/extending/creating-providers.md) | Adding LLM providers, LLMProvider interface |
+| [docs/developer-guide/extending/creating-channels.md](docs/developer-guide/extending/creating-channels.md) | Adding chat platforms, message handling |
+| [docs/developer-guide/extending/creating-skills.md](docs/developer-guide/extending/creating-skills.md) | Creating custom skills, skill structure |
+| [docs/configuration/config-file.md](docs/configuration/config-file.md) | Configuration schema, all options, environment variables |
+| [docs/operations/troubleshooting.md](docs/operations/troubleshooting.md) | Common issues, debugging, error resolution |
+| [docs/deployment/docker.md](docs/deployment/docker.md) | Docker setup, compose configuration |
+| [docs/deployment/security.md](docs/deployment/security.md) | Production security, sandbox configuration |
+| [docs/community/roadmap.md](docs/community/roadmap.md) | Project direction, planned features, priorities |
diff --git a/README.fr.md b/README.fr.md
@@ -50,7 +50,7 @@
 
 ## 📢 Actualités
 
-2026-02-16 🎉 PicoClaw a atteint 12K étoiles en une semaine ! Merci à tous pour votre soutien ! PicoClaw grandit plus vite que nous ne l'avions jamais imaginé. Vu le volume élevé de PR, nous avons un besoin urgent de mainteneurs communautaires. Nos rôles de bénévoles et notre feuille de route sont officiellement publiés [ici](docs/picoclaw_community_roadmap_260216.md) — nous avons hâte de vous accueillir !
+2026-02-16 🎉 PicoClaw a atteint 12K étoiles en une semaine ! Merci à tous pour votre soutien ! PicoClaw grandit plus vite que nous ne l'avions jamais imaginé. Vu le volume élevé de PR, nous avons un besoin urgent de mainteneurs communautaires. Nos rôles de bénévoles et notre feuille de route sont officiellement publiés [ici](docs/community/roadmap.md) — nous avons hâte de vous accueillir !
 
 2026-02-13 🎉 PicoClaw a atteint 5000 étoiles en 4 jours ! Merci à la communauté ! Nous finalisons la **Feuille de Route du Projet** et mettons en place le **Groupe de Développeurs** pour accélérer le développement de PicoClaw.
 🚀 **Appel à l'action :** Soumettez vos demandes de fonctionnalités dans les GitHub Discussions. Nous les examinerons et les prioriserons lors de notre prochaine réunion hebdomadaire.
@@ -913,7 +913,7 @@ Cette conception permet également le **support multi-agent** avec une sélectio
 | **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [Obtenir Clé](https://cerebras.ai) |
 | **Volcengine** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [Obtenir Clé](https://console.volcengine.com) |
 | **ShengsuanYun** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | - |
-| **Antigravity** | `antigravity/` | Google Cloud | Custom | OAuth uniquement |
+| **Antigravity** | `antigravity/` | Google Cloud | Custom | [OAuth uniquement](docs/user-guide/ide-setup/antigravity.md) |
 | **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | - |
 
 #### Configuration de Base
@@ -1062,17 +1062,45 @@ PicoClaw prend en charge les rappels planifiés et les tâches récurrentes via
 
 Les tâches sont stockées dans `~/.picoclaw/workspace/cron/` et traitées automatiquement.
 
+---
+
+## 📚 Documentation Complète
+
+Pour des guides et références complets, consultez le répertoire [docs/](docs/) :
+
+- **[Démarrage](docs/getting-started/README.md)** - Installation et guide rapide
+- **[Guide Utilisateur](docs/user-guide/README.md)** - Documentation complète des fonctionnalités
+- **[Guide Développeur](docs/developer-guide/README.md)** - Architecture et contribution
+- **[Déploiement](docs/deployment/README.md)** - Docker, systemd, guides SBC
+- **[Référence Configuration](docs/configuration/README.md)** - Référence complète des options
+- **[Communauté](docs/community/README.md)** - Feuille de route, contribution, support
+
 ## 🤝 Contribuer & Feuille de Route
 
+### Points Forts de la Feuille de Route
+
+| Domaine Clé | Objectif |
+|-------------|----------|
+| **Optimisation Core** | Fonctionner sur appareils 64MB RAM avec <20MB mémoire |
+| **Sécurité Renforcée** | Défense injection prompt, protection SSRF, sandbox |
+| **Connectivité** | Architecture protocole-first, standard OneBot |
+| **Fonctionnalités Avancées** | Support MCP, automatisation navigateur, multi-agents |
+| **Expérience Développeur** | Démarrage zéro-config, documentation complète |
+
+### Contribuer
+
 Les PR sont les bienvenues ! Le code source est volontairement petit et lisible. 🤗
 
-Feuille de route à venir...
+- **Voie Rapide** : 1 PR fusionnée = accès au Discord développeurs
+- **Voie Candidature** : Email à `support@sipeed.com` avec sujet `[Apply Join PicoClaw Dev Group] + compte GitHub`
 
-Groupe de développeurs en construction. Condition d'entrée : au moins 1 PR fusionnée.
+### Communauté
 
-Groupes d'utilisateurs :
+- **Discord** : https://discord.gg/V4sAZ9XWpN
+- **Twitter** : Mentionnez @SipeedIO avec #picoclaw
+- **Bilibili** : @Sipeed矽速科技
 
-Discord : <https://discord.gg/V4sAZ9XWpN>
+Consultez [docs/community/roadmap.md](docs/community/roadmap.md) pour la feuille de route détaillée.
 
 <img src="assets/wechat.png" alt="PicoClaw" width="512">
 

diff --git a/README.ja.md b/README.ja.md
@@ -85,9 +85,9 @@
 ### 🐜 革新的な省フットプリントデプロイ
 PicoClaw はほぼすべての Linux デバイスにデプロイできます！
 
-- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) E(Ethernet) または W(WiFi6) バージョン、最小ホームアシスタントに
-- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html) または $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) サーバー自動メンテナンスに
-- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) または $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) スマート監視に
+- \$9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) E(Ethernet) または W(WiFi6) バージョン、最小ホームアシスタントに
+- \$30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html) または \$100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) サーバー自動メンテナンスに
+- \$50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) または \$100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) スマート監視に
 
 https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4
 
@@ -832,7 +832,7 @@ HEARTBEAT_OK 応答         ユーザーが直接結果を受け取る
 | **Cerebras** | `cerebras/` | `https://api.cerebras.ai/v1` | OpenAI | [キーを取得](https://cerebras.ai) |
 | **Volcengine** | `volcengine/` | `https://ark.cn-beijing.volces.com/api/v3` | OpenAI | [キーを取得](https://console.volcengine.com) |
 | **ShengsuanYun** | `shengsuanyun/` | `https://router.shengsuanyun.com/api/v1` | OpenAI | - |
-| **Antigravity** | `antigravity/` | Google Cloud | カスタム | OAuthのみ |
+| **Antigravity** | `antigravity/` | Google Cloud | カスタム | [OAuthのみ](docs/user-guide/ide-setup/antigravity.md) |
 | **GitHub Copilot** | `github-copilot/` | `localhost:4321` | gRPC | - |
 
 #### 基本設定
@@ -969,11 +969,45 @@ HEARTBEAT_OK 応答         ユーザーが直接結果を受け取る
 | `picoclaw gateway` | ゲートウェイを起動 |
 | `picoclaw status` | ステータスを表示 |
 
+---
+
+## 📚 完全なドキュメント
+
+包括的なガイドとリファレンスについては、[docs/](docs/) ディレクトリをご覧ください：
+
+- **[はじめに](docs/getting-started/README.md)** - インストールとクイックスタート
+- **[ユーザーガイド](docs/user-guide/README.md)** - 完全な機能ドキュメント
+- **[開発者ガイド](docs/developer-guide/README.md)** - アーキテクチャとコントリビューション
+- **[デプロイ](docs/deployment/README.md)** - Docker、systemd、SBC ガイド
+- **[設定リファレンス](docs/configuration/README.md)** - 設定オプションの完全なリファレンス
+- **[コミュニティ](docs/community/README.md)** - ロードマップ、コントリビュート、サポート
+
 ## 🤝 コントリビュート＆ロードマップ
 
-PR 歓迎！コードベースは意図的に小さく読みやすくしています。🤗
+### ロードマップハイライト
+
+| 重点分野 | 目標 |
+|----------|------|
+| **コア最適化** | 64MB RAM デバイスで <20MB メモリで動作 |
+| **セキュリティ強化** | プロンプトインジェクション対策、SSRF 保護、サンドボックス |
+| **接続性** | プロトコルファーストアーキテクチャ、OneBot 標準対応 |
+| **高度機能** | MCP 対応、ブラウザ自動化、マルチエージェント協調 |
+| **開発者体験** | ゼロ設定スタート、包括的なドキュメント |
+
+### コントリビュート
+
+PR を歓迎します！コードベースは意図的に小さく読みやすくしています。🤗
+
+- **高速トラック**: 1 つのマージされた PR で開発者 Discord に参加可能
+- **アプリケーショントラック**: `support@sipeed.com` にメール（件名: `[Apply Join PicoClaw Dev Group] + GitHub アカウント`）
+
+### コミュニティ
+
+- **Discord**: https://discord.gg/V4sAZ9XWpN
+- **Twitter**: #picoclaw で @SipeedIO をメンション
+- **Bilibili**: @Sipeed矽速科技
 
-Discord: https://discord.gg/V4sAZ9XWpN
+詳細なロードマップについては [docs/community/roadmap.md](docs/community/roadmap.md) をご覧ください。
 
 <img src="assets/wechat.png" alt="PicoClaw" width="512">