docs: add Malay README and docs, add v0.2.4 news to all languages

- Add README.my.md (full Malay translation from English, including
  macOS guide, MiMo provider, unified WeCom row, all sections)
- Add docs/my/ (chat-apps, configuration, debug, docker, spawn-tasks,
  troubleshooting) from upstream PR #1770
- Add [Malay](README.my.md) language link to all 8 existing READMEs
- Add v0.2.4 news entry to all 9 READMEs (en/zh/fr/ja/pt-br/vi/id/it/my)
- Move 2026-02-26 20K Stars entry into Earlier news in all READMEs

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/my/chat-apps.md

@@ -0,0 +1,431 @@
+# 💬 Konfigurasi Aplikasi Sembang
+
+> Kembali ke [README](../../README.my.md)
+
+## 💬 Aplikasi Sembang
+
+Berbual dengan picoclaw anda melalui Telegram, Discord, WhatsApp, Matrix, QQ, DingTalk, LINE, WeCom, Feishu, Slack, IRC, OneBot, MaixCam, atau Pico (protokol asli)
+
+> **Nota**: Semua saluran berasaskan webhook (LINE, WeCom, dan sebagainya) diservis pada satu pelayan HTTP Gateway yang dikongsi (`gateway.host`:`gateway.port`, lalai `127.0.0.1:18790`). Tiada port khusus per saluran untuk dikonfigurasikan. Nota: Feishu menggunakan mod WebSocket/SDK dan tidak menggunakan pelayan HTTP webhook yang dikongsi.
+
+| Saluran          | Penyediaan                                 |
+| ---------------- | ------------------------------------------ |
+| **Telegram**     | Mudah (hanya token)                        |
+| **Discord**      | Mudah (token bot + intents)                |
+| **WhatsApp**     | Mudah (asli: imbas QR; atau bridge URL)    |
+| **Matrix**       | Sederhana (homeserver + access token bot)  |
+| **QQ**           | Mudah (AppID + AppSecret)                  |
+| **DingTalk**     | Sederhana (kelayakan aplikasi)             |
+| **LINE**         | Sederhana (kelayakan + webhook URL)        |
+| **WeCom AI Bot** | Sederhana (Token + kunci AES)              |
+| **Feishu**       | Sederhana (App ID + Secret, mod WebSocket) |
+| **Slack**        | Sederhana (Bot token + App token)          |
+| **IRC**          | Sederhana (pelayan + konfigurasi TLS)      |
+| **OneBot**       | Sederhana (QQ melalui protokol OneBot)     |
+| **MaixCam**      | Mudah (integrasi perkakasan Sipeed)        |
+| **Pico**         | Protokol PicoClaw asli                     |
+
+<details>
+<summary><b>Telegram</b> (Disyorkan)</summary>
+
+**1. Cipta bot**
+
+* Buka Telegram, cari `@BotFather`
+* Hantar `/newbot`, ikut arahan
+* Salin token
+
+**2. Konfigurasi**
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allow_from": ["YOUR_USER_ID"],
+      "use_markdown_v2": false,
+    }
+  }
+}
+```
+
+> Dapatkan user ID anda daripada `@userinfobot` di Telegram.
+
+**3. Jalankan**
+
+```bash
+picoclaw gateway
+```
+
+**4. Menu arahan Telegram (auto-register semasa startup)**
+
+PicoClaw kini menyimpan definisi arahan dalam satu registry bersama. Semasa startup, Telegram akan mendaftarkan arahan bot yang disokong secara automatik (contohnya `/start`, `/help`, `/show`, `/list`) supaya menu arahan dan tingkah laku runtime sentiasa selari.
+Pendaftaran menu arahan Telegram kekal sebagai UX penemuan setempat saluran; pelaksanaan arahan generik dikendalikan secara berpusat dalam gelung agen melalui commands executor.
+
+Jika pendaftaran arahan gagal (ralat sementara rangkaian/API), saluran tetap akan bermula dan PicoClaw akan mencuba semula pendaftaran di latar belakang.
+
+**4. Pemformatan Lanjutan**
+Anda boleh menetapkan `use_markdown_v2: true` untuk mengaktifkan pilihan pemformatan yang lebih maju. Ini membolehkan bot menggunakan keseluruhan set ciri Telegram MarkdownV2, termasuk gaya bersarang, spoiler, dan blok lebar tetap tersuai.
+
+</details>
+
+<details>
+<summary><b>Discord</b></summary>
+
+**1. Cipta bot**
+
+* Pergi ke <https://discord.com/developers/applications>
+* Cipta aplikasi → Bot → Add Bot
+* Salin token bot
+
+**2. Aktifkan intents**
+
+* Dalam tetapan Bot, aktifkan **MESSAGE CONTENT INTENT**
+* (Pilihan) Aktifkan **SERVER MEMBERS INTENT** jika anda bercadang menggunakan allow list berasaskan data ahli
+
+**3. Dapatkan User ID anda**
+* Discord Settings → Advanced → aktifkan **Developer Mode**
+* Klik kanan avatar anda → **Copy User ID**
+
+**4. Konfigurasi**
+
+```json
+{
+  "channels": {
+    "discord": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allow_from": ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+**5. Jemput bot**
+
+* OAuth2 → URL Generator
+* Scopes: `bot`
+* Bot Permissions: `Send Messages`, `Read Message History`
+* Buka URL jemputan yang dijana dan tambahkan bot ke pelayan anda
+
+**Pilihan: Mod trigger kumpulan**
+
+Secara lalai bot membalas semua mesej dalam saluran pelayan. Untuk mengehadkan balasan kepada @mention sahaja, tambah:
+
+```json
+{
+  "channels": {
+    "discord": {
+      "group_trigger": { "mention_only": true }
+    }
+  }
+}
+```
+
+Anda juga boleh mencetuskan dengan awalan kata kunci (contohnya `!bot`):
+
+```json
+{
+  "channels": {
+    "discord": {
+      "group_trigger": { "prefixes": ["!bot"] }
+    }
+  }
+}
+```
+
+**6. Jalankan**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<details>
+<summary><b>WhatsApp</b> (asli melalui whatsmeow)</summary>
+
+PicoClaw boleh menyambung ke WhatsApp dalam dua cara:
+
+- **Asli (disyorkan):** Dalam proses menggunakan [whatsmeow](https://github.com/tulir/whatsmeow). Tiada bridge berasingan. Tetapkan `"use_native": true` dan biarkan `bridge_url` kosong. Pada larian pertama, imbas kod QR dengan WhatsApp (Linked Devices). Sesi disimpan di bawah workspace anda (contohnya `workspace/whatsapp/`). Saluran asli ini adalah **pilihan** untuk memastikan binari lalai kekal kecil; bina dengan `-tags whatsapp_native` (contohnya `make build-whatsapp-native` atau `go build -tags whatsapp_native ./cmd/...`).
+- **Bridge:** Sambung ke bridge WebSocket luaran. Tetapkan `bridge_url` (contohnya `ws://localhost:3001`) dan biarkan `use_native` sebagai false.
+
+**Konfigurasi (asli)**
+
+```json
+{
+  "channels": {
+    "whatsapp": {
+      "enabled": true,
+      "use_native": true,
+      "session_store_path": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+Jika `session_store_path` kosong, sesi akan disimpan dalam `<workspace>/whatsapp/`. Jalankan `picoclaw gateway`; pada larian pertama, imbas kod QR yang dipaparkan dalam terminal menggunakan WhatsApp → Linked Devices.
+
+</details>
+
+<details>
+<summary><b>QQ</b></summary>
+
+**1. Cipta bot**
+
+- Pergi ke [QQ Open Platform](https://q.qq.com/#)
+- Cipta aplikasi → Dapatkan **AppID** dan **AppSecret**
+
+**2. Konfigurasi**
+
+```json
+{
+  "channels": {
+    "qq": {
+      "enabled": true,
+      "app_id": "YOUR_APP_ID",
+      "app_secret": "YOUR_APP_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+> Tetapkan `allow_from` kepada kosong untuk membenarkan semua pengguna, atau nyatakan nombor QQ untuk mengehadkan akses.
+
+**3. Jalankan**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<details>
+<summary><b>DingTalk</b></summary>
+
+**1. Cipta bot**
+
+* Pergi ke [Open Platform](https://open.dingtalk.com/)
+* Cipta aplikasi dalaman
+* Salin Client ID dan Client Secret
+
+**2. Konfigurasi**
+
+```json
+{
+  "channels": {
+    "dingtalk": {
+      "enabled": true,
+      "client_id": "YOUR_CLIENT_ID",
+      "client_secret": "YOUR_CLIENT_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+> Tetapkan `allow_from` kepada kosong untuk membenarkan semua pengguna, atau nyatakan user ID DingTalk untuk mengehadkan akses.
+
+**3. Jalankan**
+
+```bash
+picoclaw gateway
+```
+</details>
+
+<details>
+<summary><b>Matrix</b></summary>
+
+**1. Sediakan akaun bot**
+
+* Gunakan homeserver pilihan anda (contohnya `https://matrix.org` atau self-hosted)
+* Cipta pengguna bot dan dapatkan access tokennya
+
+**2. Konfigurasi**
+
+```json
+{
+  "channels": {
+    "matrix": {
+      "enabled": true,
+      "homeserver": "https://matrix.org",
+      "user_id": "@your-bot:matrix.org",
+      "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**3. Jalankan**
+
+```bash
+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).
+
+</details>
+
+<details>
+<summary><b>LINE</b></summary>
+
+**1. Cipta Akaun Rasmi LINE**
+
+- Pergi ke [LINE Developers Console](https://developers.line.biz/)
+- Cipta provider → Cipta saluran Messaging API
+- Salin **Channel Secret** dan **Channel Access Token**
+
+**2. Konfigurasi**
+
+```json
+{
+  "channels": {
+    "line": {
+      "enabled": true,
+      "channel_secret": "YOUR_CHANNEL_SECRET",
+      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
+      "webhook_path": "/webhook/line",
+      "allow_from": []
+    }
+  }
+}
+```
+
+> Webhook LINE diservis pada pelayan Gateway yang dikongsi (`gateway.host`:`gateway.port`, lalai `127.0.0.1:18790`).
+
+**3. Tetapkan Webhook URL**
+
+LINE memerlukan HTTPS untuk webhook. Gunakan reverse proxy atau tunnel:
+
+```bash
+# Contoh dengan ngrok (port lalai gateway ialah 18790)
+ngrok http 18790
+```
+
+Kemudian tetapkan Webhook URL dalam LINE Developers Console kepada `https://your-domain/webhook/line` dan aktifkan **Use webhook**.
+
+**4. Jalankan**
+
+```bash
+picoclaw gateway
+```
+
+> Dalam sembang kumpulan, bot hanya membalas apabila @disebut. Balasan akan memetik mesej asal.
+
+</details>
+
+<details>
+<summary><b>WeCom (企业微信)</b></summary>
+
+PicoClaw menyokong tiga jenis integrasi WeCom:
+
+**Pilihan 1: WeCom Bot (Bot)** - Penyediaan lebih mudah, menyokong sembang kumpulan
+**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.
+
+**Quick Setup - WeCom Bot:**
+
+**1. Cipta bot**
+
+* Pergi ke WeCom Admin Console → Group Chat → Add Group Bot
+* Salin webhook URL (format: `https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx`)
+
+**2. Konfigurasi**
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+      "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY",
+      "webhook_path": "/webhook/wecom",
+      "allow_from": []
+    }
+  }
+}
+```
+
+> Webhook WeCom diservis pada pelayan Gateway yang dikongsi (`gateway.host`:`gateway.port`, lalai `127.0.0.1:18790`).
+
+**Quick Setup - WeCom App:**
+
+**1. Cipta aplikasi**
+
+* Pergi ke WeCom Admin Console → App Management → Create App
+* Salin **AgentId** dan **Secret**
+* Pergi ke halaman "My Company", salin **CorpID**
+
+**2. Konfigurasi penerimaan mesej**
+
+* Dalam butiran aplikasi, klik "Receive Message" → "Set API"
+* Tetapkan URL kepada `http://your-server:18790/webhook/wecom-app`
+* Jana **Token** dan **EncodingAESKey**
+
+**3. Konfigurasi**
+
+```json
+{
+  "channels": {
+    "wecom_app": {
+      "enabled": true,
+      "corp_id": "wwxxxxxxxxxxxxxxxx",
+      "corp_secret": "YOUR_CORP_SECRET",
+      "agent_id": 1000002,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_ENCODING_AES_KEY",
+      "webhook_path": "/webhook/wecom-app",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**4. Jalankan**
+
+```bash
+picoclaw gateway
+```
+
+> **Nota**: Callback webhook WeCom diservis pada port Gateway (lalai 18790). Gunakan reverse proxy untuk HTTPS.
+
+**Quick Setup - WeCom AI Bot:**
+
+**1. Cipta AI Bot**
+
+* Pergi ke WeCom Admin Console → App Management → AI Bot
+* Dalam tetapan AI Bot, konfigurasikan callback URL: `http://your-server:18791/webhook/wecom-aibot`
+* Salin **Token** dan klik "Random Generate" untuk **EncodingAESKey**
+
+**2. Konfigurasi**
+
+```json
+{
+  "channels": {
+    "wecom_aibot": {
+      "enabled": true,
+      "token": "YOUR_TOKEN",
+      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
+      "webhook_path": "/webhook/wecom-aibot",
+      "allow_from": [],
+      "welcome_message": "Hello! How can I help you?"
+    }
+  }
+}
+```
+
+**3. Jalankan**
+
+```bash
+picoclaw gateway
+```
+
+> **Nota**: WeCom AI Bot menggunakan protokol streaming pull — tiada isu timeout balasan. Tugasan panjang (>30 saat) akan bertukar secara automatik kepada penghantaran push `response_url`.
+
+</details>

docs/my/configuration.md

@@ -0,0 +1,216 @@
+# ⚙️ Panduan Konfigurasi
+
+> Kembali ke [README](../../README.my.md)
+
+## ⚙️ Konfigurasi
+
+Fail konfigurasi: `~/.picoclaw/config.json`
+
+### Pemboleh Ubah Persekitaran
+
+Anda boleh menggantikan laluan lalai menggunakan pemboleh ubah persekitaran. Ini berguna untuk pemasangan mudah alih, deployment dalam container, atau menjalankan picoclaw sebagai system service. Pemboleh ubah ini saling bebas dan mengawal laluan yang berbeza.
+
+| Pemboleh Ubah     | Penerangan                                                                                                                                          | Laluan Lalai              |
+| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
+| `PICOCLAW_CONFIG` | Menindih laluan ke fail konfigurasi. Ini memberitahu picoclaw secara terus fail `config.json` yang perlu dimuatkan, dengan mengabaikan lokasi lain. | `~/.picoclaw/config.json` |
+| `PICOCLAW_HOME`   | Menindih direktori root untuk data picoclaw. Ini mengubah lokasi lalai bagi `workspace` dan direktori data lain.                                    | `~/.picoclaw`             |
+
+**Contoh:**
+
+```bash
+# Jalankan picoclaw menggunakan fail config tertentu
+# Laluan workspace akan dibaca daripada fail config tersebut
+PICOCLAW_CONFIG=/etc/picoclaw/production.json picoclaw gateway
+
+# Jalankan picoclaw dengan semua data disimpan di /opt/picoclaw
+# Config akan dimuatkan dari lalai ~/.picoclaw/config.json
+# Workspace akan dicipta di /opt/picoclaw/workspace
+PICOCLAW_HOME=/opt/picoclaw picoclaw agent
+
+# Gunakan kedua-duanya untuk setup yang disesuaikan sepenuhnya
+PICOCLAW_HOME=/srv/picoclaw PICOCLAW_CONFIG=/srv/picoclaw/main.json picoclaw gateway
+```
+
+### Susun Atur Workspace
+
+PicoClaw menyimpan data dalam workspace yang dikonfigurasikan (lalai: `~/.picoclaw/workspace`):
+
+```
+~/.picoclaw/workspace/
+├── sessions/          # Sesi perbualan dan sejarah
+├── memory/            # Memori jangka panjang (MEMORY.md)
+├── state/             # Keadaan persisten (saluran terakhir, dll.)
+├── cron/              # Pangkalan data job berjadual
+├── skills/            # Skill tersuai
+├── AGENTS.md          # Panduan tingkah laku agen
+├── HEARTBEAT.md       # Prompt tugasan berkala (disemak setiap 30 minit)
+├── IDENTITY.md        # Identiti agen
+├── SOUL.md            # Jiwa agen
+└── USER.md            # Keutamaan pengguna
+```
+
+### Sumber Skill
+
+Secara lalai, skill dimuatkan daripada:
+
+1. `~/.picoclaw/workspace/skills` (workspace)
+2. `~/.picoclaw/skills` (global)
+3. `<current-working-directory>/skills` (builtin)
+
+Untuk setup lanjutan/ujian, anda boleh menindih root builtin skills dengan:
+
+```bash
+export PICOCLAW_BUILTIN_SKILLS=/path/to/skills
+```
+
+### Polisi Pelaksanaan Arahan Bersepadu
+
+- Generic slash command dilaksanakan melalui satu laluan dalam `pkg/agent/loop.go` melalui `commands.Executor`.
+- Adapter saluran tidak lagi menggunakan generic command secara setempat; ia memajukan teks masuk ke laluan bus/agent. Telegram masih auto-register arahan yang disokong semasa startup.
+- Slash command yang tidak dikenali (contohnya `/foo`) akan diteruskan ke pemprosesan LLM biasa.
+- Arahan yang didaftarkan tetapi tidak disokong pada saluran semasa (contohnya `/show` di WhatsApp) akan memulangkan ralat yang jelas kepada pengguna dan menghentikan pemprosesan lanjut.
+
+### 🔒 Security Sandbox
+
+PicoClaw berjalan dalam persekitaran bersandbox secara lalai. Agen hanya boleh mengakses fail dan melaksanakan arahan dalam workspace yang dikonfigurasikan.
+
+#### Konfigurasi Lalai
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "restrict_to_workspace": true
+    }
+  }
+}
+```
+
+| Option                  | Default                 | Description                               |
+| ----------------------- | ----------------------- | ----------------------------------------- |
+| `workspace`             | `~/.picoclaw/workspace` | Direktori kerja untuk agen                |
+| `restrict_to_workspace` | `true`                  | Hadkan akses fail/arahan kepada workspace |
+
+#### Tools yang Dilindungi
+
+Apabila `restrict_to_workspace: true`, tools berikut disandboxkan:
+
+| Tool          | Fungsi            | Sekatan                             |
+| ------------- | ----------------- | ----------------------------------- |
+| `read_file`   | Baca fail         | Hanya fail dalam workspace          |
+| `write_file`  | Tulis fail        | Hanya fail dalam workspace          |
+| `list_dir`    | Senarai direktori | Hanya direktori dalam workspace     |
+| `edit_file`   | Edit fail         | Hanya fail dalam workspace          |
+| `append_file` | Tambah ke fail    | Hanya fail dalam workspace          |
+| `exec`        | Jalankan arahan   | Laluan arahan mesti dalam workspace |
+
+#### Perlindungan Exec Tambahan
+
+Walaupun dengan `restrict_to_workspace: false`, tool `exec` menyekat arahan berbahaya berikut:
+
+* `rm -rf`, `del /f`, `rmdir /s` — Pemadaman pukal
+* `format`, `mkfs`, `diskpart` — Pemformatan cakera
+* `dd if=` — Pengimejan cakera
+* Menulis ke `/dev/sd[a-z]` — Tulis terus ke cakera
+* `shutdown`, `reboot`, `poweroff` — Penutupan sistem
+* Fork bomb `:(){ :|:& };:`
+
+### Kawalan Akses Fail
+
+| Kunci Config              | Jenis    | Lalai | Penerangan                                                      |
+| ------------------------- | -------- | ----- | --------------------------------------------------------------- |
+| `tools.allow_read_paths`  | string[] | `[]`  | Laluan tambahan yang dibenarkan untuk dibaca di luar workspace  |
+| `tools.allow_write_paths` | string[] | `[]`  | Laluan tambahan yang dibenarkan untuk ditulis di luar workspace |
+
+### Keselamatan Exec
+
+| Kunci Config                       | Jenis    | Lalai   | Penerangan                                                   |
+| ---------------------------------- | -------- | ------- | ------------------------------------------------------------ |
+| `tools.exec.allow_remote`          | bool     | `false` | Benarkan tool exec dari saluran jauh (Telegram/Discord dll.) |
+| `tools.exec.enable_deny_patterns`  | bool     | `true`  | Aktifkan pemintasan arahan berbahaya                         |
+| `tools.exec.custom_deny_patterns`  | string[] | `[]`    | Corak regex tersuai untuk disekat                            |
+| `tools.exec.custom_allow_patterns` | string[] | `[]`    | Corak regex tersuai untuk dibenarkan                         |
+
+> **Nota Keselamatan:** Perlindungan symlink diaktifkan secara lalai — semua laluan fail akan diselesaikan melalui `filepath.EvalSymlinks` sebelum dipadankan dengan whitelist, bagi mengelakkan serangan melarikan diri melalui symlink.
+
+#### Had yang Diketahui: Proses Anak Daripada Build Tools
+
+Pengawal keselamatan exec hanya memeriksa baris arahan yang PicoClaw lancarkan secara terus. Ia tidak memeriksa secara rekursif proses anak yang dilancarkan oleh tools pembangun yang dibenarkan seperti `make`, `go run`, `cargo`, `npm run`, atau skrip build tersuai.
+
+Ini bermakna arahan peringkat atas masih boleh mengkompil atau melancarkan binari lain selepas ia melepasi semakan awal pengawal. Dalam amalan, anggap build script, Makefile, package script, dan binari terjana sebagai kod boleh laksana yang memerlukan tahap semakan yang sama seperti arahan shell terus.
+
+Untuk persekitaran yang lebih berisiko:
+
+* Semak build script sebelum pelaksanaan.
+* Utamakan kelulusan/semakan manual untuk aliran kerja compile-and-run.
+* Jalankan PicoClaw dalam container atau VM jika anda memerlukan pengasingan yang lebih kuat daripada pengawal terbina dalam.
+
+#### Contoh Ralat
+
+```
+[ERROR] tool: Tool execution failed
+{tool=exec, error=Command blocked by safety guard (path outside working dir)}
+```
+
+```
+[ERROR] tool: Tool execution failed
+{tool=exec, error=Command blocked by safety guard (dangerous pattern detected)}
+```
+
+#### Menyahaktifkan Sekatan (Risiko Keselamatan)
+
+Jika anda perlu membenarkan agen mengakses laluan di luar workspace:
+
+**Kaedah 1: Fail config**
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "restrict_to_workspace": false
+    }
+  }
+}
+```
+
+**Kaedah 2: Pemboleh ubah persekitaran**
+
+```bash
+export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false
+```
+
+> ⚠️ **Amaran**: Menyahaktifkan sekatan ini membenarkan agen mengakses mana-mana laluan pada sistem anda. Gunakan dengan berhati-hati hanya dalam persekitaran terkawal.
+
+#### Ketekalan Sempadan Keselamatan
+
+Tetapan `restrict_to_workspace` digunakan secara konsisten merentas semua laluan pelaksanaan:
+
+| Execution Path   | Security Boundary           |
+| ---------------- | --------------------------- |
+| Main Agent       | `restrict_to_workspace` ✅   |
+| Subagent / Spawn | Inherits same restriction ✅ |
+| Heartbeat tasks  | Inherits same restriction ✅ |
+
+Semua laluan berkongsi sekatan workspace yang sama — tiada cara untuk memintas sempadan keselamatan melalui subagent atau tugasan berjadual.
+
+### Heartbeat (Tugasan Berkala)
+
+PicoClaw boleh melaksanakan tugasan berkala secara automatik. Cipta fail `HEARTBEAT.md` dalam workspace anda:
+
+```markdown
+# Periodic Tasks
+
+- Check my email for important messages
+- Review my calendar for upcoming events
+- Check the weather forecast
+```
+
+Agen akan membaca fail ini setiap 30 minit (boleh dikonfigurasi) dan melaksanakan sebarang tugasan menggunakan tools yang tersedia.
+
+#### Tugasan Async dengan Spawn
+
+Untuk tugasan yang berjalan lama (carian web, panggilan API), gunakan tool `spawn` untuk mencipta **subagent**:
+
+```markdown
+# Periodic Tasks

docs/my/debug.md

@@ -0,0 +1,33 @@
+# Penyahpepijatan PicoClaw
+
+PicoClaw melakukan pelbagai interaksi kompleks di sebalik tabir untuk setiap permintaan yang diterimanya, daripada menghala mesej dan menilai kerumitan, hinggalah melaksanakan tools dan menyesuaikan diri dengan kegagalan model. Keupayaan melihat dengan tepat apa yang sedang berlaku sangat penting, bukan sahaja untuk menyelesaikan masalah, malah untuk benar-benar memahami cara agen ini beroperasi.
+## Memulakan PicoClaw dalam Mod Debug
+
+Untuk mendapatkan maklumat terperinci tentang apa yang sedang dilakukan oleh agen (permintaan LLM, panggilan tool, penghalaan mesej), anda boleh memulakan gateway PicoClaw dengan flag debug:
+
+```bash
+picoclaw gateway --debug
+# or
+picoclaw gateway -d
+```
+
+Dalam mod ini, sistem akan memformat log dengan lebih terperinci dan memaparkan pratonton system prompt serta hasil pelaksanaan tool.
+
+## Menyahaktifkan Pemotongan Log (Log Penuh)
+
+Secara lalai, PicoClaw memotong rentetan yang sangat panjang (seperti *System Prompt* atau hasil output JSON yang besar) dalam log debug supaya konsol kekal mudah dibaca.
+
+Jika anda perlu memeriksa output penuh sesuatu arahan atau payload tepat yang dihantar kepada model LLM, anda boleh menggunakan flag `--no-truncate`.
+
+**Nota:** Flag ini *hanya* berfungsi apabila digabungkan dengan mod `--debug`.
+
+```bash
+picoclaw gateway --debug --no-truncate
+
+```
+
+Apabila flag ini aktif, fungsi pemotongan global dinyahaktifkan. Ini sangat berguna untuk:
+
+* Mengesahkan sintaks tepat mesej yang dihantar kepada penyedia.
+* Membaca output lengkap daripada tools seperti `exec`, `web_fetch`, atau `read_file`.
+* Menyahpepijat sejarah sesi yang disimpan dalam memori.

docs/my/docker.md

@@ -0,0 +1,166 @@
+# 🐳 Panduan Docker & Quick Start
+
+> Kembali ke [README](../../README.my.md)
+
+## 🐳 Docker Compose
+
+Anda juga boleh menjalankan PicoClaw menggunakan Docker Compose tanpa memasang apa-apa secara setempat.
+
+```bash
+# 1. Clone repo ini
+git clone https://github.com/sipeed/picoclaw.git
+cd picoclaw
+
+# 2. Larian pertama — jana docker/data/config.json secara automatik kemudian keluar
+docker compose -f docker/docker-compose.yml --profile gateway up
+# Container akan memaparkan "First-run setup complete." dan berhenti.
+
+# 3. Tetapkan kunci API anda
+vim docker/data/config.json   # Tetapkan API key penyedia, token bot, dan sebagainya.
+
+# 4. Mula
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
+
+> [!TIP]
+> **Pengguna Docker**: Secara lalai, Gateway mendengar pada `127.0.0.1` yang tidak boleh diakses dari host. Jika anda perlu mengakses health endpoint atau mendedahkan port, tetapkan `PICOCLAW_GATEWAY_HOST=0.0.0.0` dalam persekitaran anda atau kemas kini `config.json`.
+
+```bash
+# 5. Semak log
+docker compose -f docker/docker-compose.yml logs -f picoclaw-gateway
+
+# 6. Hentikan
+docker compose -f docker/docker-compose.yml --profile gateway down
+```
+
+### Mod Launcher (Konsol Web)
+
+Imej `launcher` merangkumi ketiga-tiga binari (`picoclaw`, `picoclaw-launcher`, `picoclaw-launcher-tui`) dan memulakan konsol web secara lalai, yang menyediakan UI berasaskan pelayar untuk konfigurasi dan sembang.
+
+```bash
+docker compose -f docker/docker-compose.yml --profile launcher up -d
+```
+
+Buka http://localhost:18800 dalam pelayar anda. Launcher mengurus proses gateway secara automatik.
+
+> [!WARNING]
+> Konsol web belum menyokong autentikasi. Elakkan mendedahkannya ke internet awam.
+
+### Mod Agent (One-shot)
+
+```bash
+# Tanyakan soalan
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent -m "What is 2+2?"
+
+# Mod interaktif
+docker compose -f docker/docker-compose.yml run --rm picoclaw-agent
+```
+
+### Kemas kini
+
+```bash
+docker compose -f docker/docker-compose.yml pull
+docker compose -f docker/docker-compose.yml --profile gateway up -d
+```
+
+### 🚀 Quick Start
+
+> [!TIP]
+> Tetapkan API Key anda dalam `~/.picoclaw/config.json`. Dapatkan API Key: [Volcengine (CodingPlan)](https://www.volcengine.com/activity/codingplan?utm_campaign=PicoClaw&utm_content=PicoClaw&utm_medium=devrel&utm_source=OWO&utm_term=PicoClaw) (LLM) · [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM). Carian web adalah pilihan — dapatkan [Tavily API](https://tavily.com) percuma (1000 pertanyaan percuma/bulan) atau [Brave Search API](https://brave.com/search/api) (2000 pertanyaan percuma/bulan).
+
+**1. Inisialisasi**
+
+```bash
+picoclaw onboard
+```
+
+**2. Konfigurasi** (`~/.picoclaw/config.json`)
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "model_name": "gpt-5.4",
+      "max_tokens": 8192,
+      "temperature": 0.7,
+      "max_tool_iterations": 20
+    }
+  },
+  "model_list": [
+    {
+      "model_name": "ark-code-latest",
+      "model": "volcengine/ark-code-latest",
+      "api_key": "sk-your-api-key",
+      "api_base":"https://ark.cn-beijing.volces.com/api/coding/v3"
+    },
+    {
+      "model_name": "gpt-5.4",
+      "model": "openai/gpt-5.4",
+      "api_key": "your-api-key",
+      "request_timeout": 300
+    },
+    {
+      "model_name": "claude-sonnet-4.6",
+      "model": "anthropic/claude-sonnet-4.6",
+      "api_key": "your-anthropic-key"
+    }
+  ],
+  "tools": {
+    "web": {
+      "enabled": true,
+      "fetch_limit_bytes": 10485760,
+      "format": "plaintext",
+      "brave": {
+        "enabled": false,
+        "api_key": "YOUR_BRAVE_API_KEY",
+        "max_results": 5
+      },
+      "tavily": {
+        "enabled": false,
+        "api_key": "YOUR_TAVILY_API_KEY",
+        "max_results": 5
+      },
+      "duckduckgo": {
+        "enabled": true,
+        "max_results": 5
+      },
+      "perplexity": {
+        "enabled": false,
+        "api_key": "YOUR_PERPLEXITY_API_KEY",
+        "max_results": 5
+      },
+      "searxng": {
+        "enabled": false,
+        "base_url": "http://your-searxng-instance:8888",
+        "max_results": 5
+      }
+    }
+  }
+}
+```
+
+> **Baharu**: Format konfigurasi `model_list` membolehkan penambahan penyedia tanpa perubahan kod. Lihat [Konfigurasi Model](#konfigurasi-model-model_list) untuk butiran.
+> `request_timeout` adalah pilihan dan menggunakan saat. Jika diabaikan atau ditetapkan kepada `<= 0`, PicoClaw menggunakan timeout lalai (120s).
+
+**3. Dapatkan API Key**
+
+* **Penyedia LLM**: [OpenRouter](https://openrouter.ai/keys) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) · [Anthropic](https://console.anthropic.com) · [OpenAI](https://platform.openai.com) · [Gemini](https://aistudio.google.com/api-keys)
+* **Carian Web** (pilihan):
+  * [Brave Search](https://brave.com/search/api) - Berbayar ($5/1000 pertanyaan, ~$5-6/bulan)
+  * [Perplexity](https://www.perplexity.ai) - Carian berkuasa AI dengan antara muka sembang
+  * [SearXNG](https://github.com/searxng/searxng) - Enjin meta-carian hos kendiri (percuma, tidak perlu API key)
+  * [Tavily](https://tavily.com) - Dioptimumkan untuk AI Agents (1000 permintaan/bulan)
+  * DuckDuckGo - Fallback terbina dalam (tidak memerlukan API key)
+
+> **Nota**: Lihat `config.example.json` untuk templat konfigurasi penuh.
+
+**4. Sembang**
+
+```bash
+picoclaw agent -m "What is 2+2?"
+```
+
+Itu sahaja! Anda kini mempunyai pembantu AI yang berfungsi dalam masa 2 minit.
+
+---

docs/my/spawn-tasks.md

@@ -0,0 +1,61 @@
+# 🔄 Spawn & Tugasan Async
+
+> Kembali ke [README](../../README.my.md)
+
+## Tugasan Cepat (balas terus)
+
+- Laporkan masa semasa
+
+## Tugasan Panjang (guna spawn untuk async)
+
+- Cari berita AI di web dan ringkaskan
+- Semak e-mel dan laporkan mesej penting
+```
+
+**Tingkah laku utama:**
+
+| Feature                 | Description                                               |
+| ----------------------- | --------------------------------------------------------- |
+| **spawn**               | Mencipta sub-agen async, tidak menyekat heartbeat         |
+| **Independent context** | Sub-agen mempunyai konteks sendiri, tiada sejarah sesi    |
+| **message tool**        | Sub-agen berkomunikasi terus dengan pengguna melalui message tool |
+| **Non-blocking**        | Selepas spawn, heartbeat terus ke tugasan seterusnya      |
+
+#### Cara Komunikasi Sub-agen Berfungsi
+
+```
+Heartbeat dicetuskan
+    ↓
+Agen membaca HEARTBEAT.md
+    ↓
+Untuk tugasan panjang: spawn sub-agen
+    ↓                           ↓
+Terus ke tugasan seterusnya  Sub-agen bekerja secara bebas
+    ↓                           ↓
+Semua tugasan selesai     Sub-agen menggunakan tool "message"
+    ↓                           ↓
+Balas HEARTBEAT_OK        Pengguna menerima hasil secara terus
+```
+
+Sub-agen mempunyai akses kepada tools (message, web_search, dan sebagainya) dan boleh berkomunikasi dengan pengguna secara bebas tanpa melalui agen utama.
+
+**Konfigurasi:**
+
+```json
+{
+  "heartbeat": {
+    "enabled": true,
+    "interval": 30
+  }
+}
+```
+
+| Option     | Default | Description                              |
+| ---------- | ------- | ---------------------------------------- |
+| `enabled`  | `true`  | Hidupkan/matikan heartbeat               |
+| `interval` | `30`    | Selang semakan dalam minit (minimum: 5) |
+
+**Pemboleh ubah persekitaran:**
+
+* `PICOCLAW_HEARTBEAT_ENABLED=false` untuk nyahaktifkan
+* `PICOCLAW_HEARTBEAT_INTERVAL=60` untuk menukar selang

docs/my/troubleshooting.md

@@ -0,0 +1,43 @@
+# Penyelesaian Masalah
+
+## "model ... not found in model_list" atau OpenRouter "free is not a valid model ID"
+
+**Gejala:** Anda akan melihat salah satu daripada mesej berikut:
+
+- `Error creating provider: model "openrouter/free" not found in model_list`
+- OpenRouter memulangkan 400: `"free is not a valid model ID"`
+
+**Punca:** Medan `model` dalam entri `model_list` anda ialah nilai yang dihantar ke API. Untuk OpenRouter, anda mesti menggunakan ID model **penuh**, bukan bentuk singkatan.
+
+- **Salah:** `"model": "free"` → OpenRouter menerima `free` dan menolaknya.
+- **Betul:** `"model": "openrouter/free"` → OpenRouter menerima `openrouter/free` (routing auto free-tier).
+
+**Penyelesaian:** Dalam `~/.picoclaw/config.json` (atau laluan config anda):
+
+1. **agents.defaults.model** mesti sepadan dengan `model_name` dalam `model_list` (contohnya `"openrouter-free"`).
+2. Medan **model** bagi entri tersebut mesti merupakan ID model OpenRouter yang sah, contohnya:
+  - `"openrouter/free"` – auto free-tier
+  - `"google/gemini-2.0-flash-exp:free"`
+  - `"meta-llama/llama-3.1-8b-instruct:free"`
+
+Example snippet:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": "openrouter-free"
+    }
+  },
+  "model_list": [
+    {
+      "model_name": "openrouter-free",
+      "model": "openrouter/free",
+      "api_key": "sk-or-v1-YOUR_OPENROUTER_KEY",
+      "api_base": "https://openrouter.ai/api/v1"
+    }
+  ]
+}
+```
+
+Dapatkan kunci anda di [OpenRouter Keys](https://openrouter.ai/keys).