Move picoclaw_space to root for Hugging Face Spaces deployment

AGENT.md

@@ -1,38 +1,32 @@
-# Agent Persona: PicoClaw 🦀
-
-You are **PicoClaw**, an autonomous Senior Distributed Systems Engineer & AI Researcher. You are capable, persistent, and security-conscious. Your goal is to help the user build, debug, and understand complex software systems with minimal hand-holding.
-
-## Core Directives
-
-1.  **Be Autonomous**: Don't just suggest code; implement it, test it, and verify it works. Use your skills (`docker`, `go-dev`, `api-tester`) proactively.
-2.  **Be Secure**: Always use the `security-audit` skill before finalizing code changes. Never commit secrets or dangerous patterns.
-3.  **Be Organized**: For any task with >2 steps, YOU MUST use the `planner` skill to create a `PLAN.md`.
-4.  **Be Adaptive**: Learn from your mistakes. If a fix works, save the lesson using the `memory` skill for future reference.
-5.  **Be Communicative**:
-    -   Use clear, concise language (Indonesian/English as preferred by user).
-    -   If the user asks for a voice response, use the `voice-tts` skill immediately.
-    -   Use `diagrams` to explain complex architectures.
-
-## Skill Protocols
-
-### 🛠️ Engineering (Go, Docker, SQL)
--   **New Features**: Always check existing code patterns with `code-expert` first.
--   **Database**: Use `db-manager` to inspect state before and after migrations.
--   **Microservices**: Use `api-tester` and `network-utils` to verify connectivity between services.
-
-### 🧠 Research & Knowledge (AI, Memory)
--   **Unknown Topics**: Use `ai-research` to find ArXiv papers or latest docs.
--   **Long-term Memory**:
-    -   *Save*: `echo "Lesson: ..." > .memory/lessons/topic.md`
-    -   *Recall*: `grep -r "topic" .memory/`
-
-### 🛡️ Security & Quality
--   **Pre-Commit Check**: Run `security-audit` and `go-dev` (lint/vet) before asking for approval.
-
-## Voice Interaction
--   When speaking (via `voice-tts`), keep sentences short and natural.
--   Use Indonesian unless the technical context requires English terms.
-
-## Tone
--   **Professional yet Casual**: "Siap, laksanakan!" instead of "Affirmative, executing command."
--   **Direct**: Get straight to the solution.
+# Agent Behavior Protocol
+
+## Message Handling
+
+### Telegram Auto-Chunking Protocol
+To handle Telegram's message size limits (4096 characters), the agent implements an automatic chunking protocol:
+
+1. **Chunk Size**: Messages > 4000 characters are split into chunks.
+2. **Format**: Multi-part messages are prefixed with `[Part X/Y]`.
+3. **Splitting Logic**:
+   - Prefer natural boundaries (newlines, spaces).
+   - Protect code blocks (avoid splitting inside ```...```).
+   - If a code block must be split, ensure subsequent parts are correctly formatted (though current implementation tries to avoid this).
+4. **Rate Limiting**: A 1.5s delay is introduced between chunks to avoid API rate limits.
+5. **Fallback**: If HTML parsing fails (e.g., due to malformed tags in a chunk), the message is sent as plain text.
+
+## Context Management
+- Maximum context window: 500,000 tokens (theoretical), practical limit set to ~256k.
+- History truncation: Oldest messages are dropped when context limit is approached.
+
+## Tool Execution
+- **Parallelism**: Read-only tools (web_search, read_file, etc.) are executed in parallel.
+- **Caching**: Idempotent tool results are cached with TTL to save tokens and time.
+- **Error Recovery**: Transient errors trigger exponential backoff retries.
+- **Sandboxing**:
+  - Tools are executed with configurable resource limits (CPU time, memory).
+  - Environment variables are filtered.
+  - Dangerous commands (e.g., `rm -rf`, `mkfs`) are blocked via regex patterns.
+  - Output size is limited to prevent memory exhaustion (default 10MB).
+- **Observability**:
+  - Metrics are tracked for tool executions, cache hits/misses, and sandbox status.
+  - Available at `/metrics` endpoint.

README.md

@@ -1,63 +1,131 @@
 ---
 title: zeroclaw
-emoji: 🦀
+emoji: 🦞
 colorFrom: blue
-colorTo: purple
-sdk: static
+colorTo: indigo
+sdk: docker
 pinned: false
+app_port: 7860
 ---
+<div align="center">
+  <img src="assets/logo.jpg" alt="PicoClaw" width="512">
 
-# zeroclaw 🦀
+  <h1>PicoClaw: Autonomous Distributed Systems Engineer</h1>
 
-**Ultra-lightweight Autonomous AI Agent for Distributed Systems**
+  <h3>$10 Hardware · 10MB RAM · Voice-Enabled · Autonomous</h3>
 
-PicoClaw is an open-source AI agent built in Go, designed to assist engineers in building, debugging, and maintaining distributed systems with minimal resource footprint.
+  <p>
+    <img src="https://img.shields.io/badge/Go-1.21+-00ADD8?style=flat&logo=go&logoColor=white" alt="Go">
+    <img src="https://img.shields.io/badge/Arch-x86__64%2C%20ARM64%2C%20RISC--V-blue" alt="Hardware">
+    <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
+    <br>
+    <a href="https://picoclaw.io"><img src="https://img.shields.io/badge/Website-picoclaw.io-blue?style=flat&logo=google-chrome&logoColor=white" alt="Website"></a>
+    <a href="https://x.com/SipeedIO"><img src="https://img.shields.io/badge/X_(Twitter)-SipeedIO-black?style=flat&logo=x&logoColor=white" alt="Twitter"></a>
+  </p>
 
-## ✨ Features
+ [中文](README.zh.md) | [日本語](README.ja.md) | **English**
+</div>
 
-- **Systems Engineering**: Docker management, Go development, network debugging
-- **Research**: ArXiv paper search and summarization
-- **Operations**: System monitoring, security auditing, log analysis
-- **Hardware Control**: I2C/SPI peripheral support for Sipeed boards (LicheeRV Nano, MaixCAM, NanoKVM)
-- **Visualization**: Architecture diagrams using Mermaid JS
-- **Extensible**: Modular skill system for adding new capabilities
+---
 
-## 🎯 Why PicoClaw?
+🦐 **PicoClaw** is an ultra-lightweight, autonomous personal AI agent written in Go. Designed as a **Distributed Systems Engineer**, it combines the speed of Go with the intelligence of modern LLMs to handle complex tasks like Docker management, network debugging, and system monitoring with minimal resource footprint.
+
+It runs on **$10 hardware** (like LicheeRV Nano) with **<10MB RAM**, making it 99% more efficient than Python-based alternatives.
+
+<table align="center">
+  <tr align="center">
+    <td align="center" valign="top">
+      <p align="center">
+        <img src="assets/picoclaw_mem.gif" width="360" height="240">
+      </p>
+    </td>
+    <td align="center" valign="top">
+      <p align="center">
+        <img src="assets/licheervnano.png" width="400" height="240">
+      </p>
+    </td>
+  </tr>
+</table>
+
+> [!CAUTION]
+> **🚨 SECURITY & OFFICIAL CHANNELS**
+>
+> * **NO CRYPTO:** PicoClaw has **NO** official token/coin. All claims on `pump.fun` or other trading platforms are **SCAMS**.
+> * **OFFICIAL DOMAIN:** The **ONLY** official website is **[picoclaw.io](https://picoclaw.io)**.
+> * **Warning:** PicoClaw is in Alpha. Do not deploy to critical production environments without review.
+
+## 🚀 Capabilities
+
+PicoClaw is more than just a chatbot. It's an autonomous engineer with specialized skills:
+
+*   **🗣️ Voice Interaction**: Speaks directly to you using Google TTS (Auto-configured).
+*   **🐳 Docker Management**: List, inspect, and manage containers via CLI.
+*   **🔬 AI Research**: Search ArXiv for papers and summarize findings.
+*   **🛠️ Go Development**: Assist with Go code, compilation, and debugging.
+*   **📊 Visualization**: Generate system architecture diagrams using Mermaid JS.
+*   **🌐 Network Utilities**: Debug DNS, ping hosts, and trace routes.
+*   **🛡️ Security Audit**: Scan code for secrets and vulnerabilities.
+*   **🧠 Memory & Planning**: Remembers context across sessions and plans complex tasks.
+
+## 📦 Installation
 
-- **Small Footprint**: Runs on $10 boards with <10MB RAM
-- **Autonomous**: Proactive problem detection and resolution
-- **Fast**: Written in Go for maximum performance
-- **Open Source**: MIT License, fully transparent
+```bash
+curl -fsSL https://picoclaw.io/install.sh | sh
+```
 
-## 🚀 Quick Start
+Or build from source:
 
 ```bash
-# Clone the repository
 git clone https://github.com/sipeed/picoclaw.git
 cd picoclaw
+make install
+```
 
-# Build
-go build -o picoclaw .
+## 🛠️ Usage
 
-# Run (requires LLM API key)
-export OPENAI_API_KEY=your_key_here
-./picoclaw
+### Quick Start
+
+Start the interactive agent. It will automatically set up required skills (Voice, etc.) on first run.
+
+```bash
+picoclaw agent -m "Hello, who are you?"
 ```
 
-## 📚 Documentation
+### Voice Mode
 
-- [GitHub Repository](https://github.com/sipeed/picoclaw)
-- [Configuration Guide](https://github.com/sipeed/picoclaw?tab=readme-ov-file#configuration)
-- [Skill Development](https://github.com/sipeed/picoclaw/tree/main/workspace/skills)
+PicoClaw can speak its responses! Ensure you have speakers connected.
 
-## 🤝 Contributing
+```bash
+# It will use the 'voice-tts' skill automatically when appropriate
+picoclaw agent -m "Please introduce yourself in a voice message."
+```
 
-Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) before submitting PRs.
+### Run as a Daemon (Gateway)
 
-## 📄 License
+Run PicoClaw as a background service to handle heartbeats, cron jobs, and multi-channel messages (Telegram/Discord/etc).
 
-MIT License - see [LICENSE](LICENSE) file for details.
+```bash
+picoclaw gateway
+```
 
----
+## 🐳 Docker Support
+
+PicoClaw is available as a Docker image.
+
+```bash
+# Run agent
+docker compose run --rm picoclaw-agent -m "Hello"
+
+# Run gateway
+docker compose up -d picoclaw-gateway
+```
+
+*Note: To use Voice or Docker skills within the container, you may need to mount `/dev/snd` or `/var/run/docker.sock`.*
+
+## 🤝 Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## 📄 License
 
-Built with ❤️ by the PicoClaw team
+MIT License