feat: Build the Dream Weaver interior restyling workflow to preserve room geometry while changing aesthetics (#5)

#3 Self-approved and unit tests passed with flying colors. Co-authored-by: Sagnik <sagnik7896@gmail.com> Reviewed-on: #5
2026-03-10 01:36:27 +05:30
parent cb6c752c8e
commit 55bb5e5a90
53 changed files with 11956 additions and 2222 deletions
--- a/Context/Tech/Customer
+++ b/Context/Tech/Customer
@@ -0,0 +1,195 @@
+This rational-based list categorizes brands based on **Sales Cycle Speed** vs. **Budget Depth**, which is critical for your software pitch.
+
+**Strategic Overview for Your Sales Team**
+
+* **Tier 1 (The Whales):** Massive budgets but 6–12 month sales cycles. **Strategy:** Pitch "Data Sovereignty" and "Security" first.  
+* **Tier 2 (The Aggressors):** High volume, hungry for differentiation. **Strategy:** Pitch "Sales Velocity" and "Lead Leakage Prevention."  
+* **Tier 3 (The Entry Points):** Smaller teams, owner-operated. **Strategy:** **Start here.** You can often close the CEO in one meeting. They need your "iPad Wow Factor" to compete with giants.
+
+---
+
+**A. Real Estate Developers (The Product Buyers)**  
+*These clients buy your software to install in their Sales Galleries.*  
+**Tier 1: The "Government & State-Backed" Giants**  
+**Rationale:** They own the master communities. Bureaucratic, but a single contract here is a company-maker.
+
+* **Pitch:** "Sovereign Data Compliance" (Your local server model is perfect for them).
+
+| Brand | Rationale | Key Person | Contact Intelligence |
+| :---: | :---: | :---: | :---: |
+|  |  |  |  |
+| **Emaar** | The market leader ($40B+ assets). Toughest to crack but the ultimate validator. | **Junaid Siddiqui** (Head of Sales) | **Format:** `jsiddiqui@emaar.ae` **Alt:** `sales@emaar.ae` (Ask for Procurement) |
+| **Nakheel** | Creator of Palm Jumeirah. Recently merged into Dubai Holding. Massive waterfront inventory. | **Rasha Hassan** (Chief Commercial Officer) | **Format:** `firstname.lastname@nakheel.com` **Direct:** `rasha.hassan@nakheel.com` |
+| **Aldar** (Abu Dhabi) | The "Emaar of Abu Dhabi." Dominates Yas/Saadiyat. Very tech-forward. | **Jonathan Emery** (CEO, Aldar Development) | **Format:** `jemery@aldar.com` **HQ:** \+971 2 810 5555 |
+
+**Tier 2: The "High-Velocity" Private Developers**
+
+**Rationale:** Family-owned billionaires. They move FAST. They care about **speed of sales** above all else. **Your Sweet Spot.**
+
+| Brand | Rationale | Key Person | Contact Intelligence |
+| :---: | :---: | :---: | :---: |
+| **DAMAC** | The "Marketing King." Known for wild promotions. They will love the "Biometric Sentiment" tool. | **Mert Kal** (Sr. Director, Marketing) | **Format:** `mert.kal@damacgroup.com` **Format:** `firstname.lastname@damacgroup.com` |
+| **Sobha Realty** | Obsessed with "Quality" and "Detail." Pitch your Unity engine's visual fidelity here. | **Ashish Parakh** (Chief Sales Officer) | **Email:** `ashish@sobha-me.com` **HQ:** \+971 4 423 8064 |
+| **Binghatti** | **Top Target.** Fastest growing. Known for "Hyper-Towers" and branded residences (Bugatti/Mercedes). | **Salma Hussein** (Sales Manager) | **Direct Mobile:** `+971 50 918 2533` **Email:** `salma.hussein@binghatti.com` |
+| **Danube** | "1% Man" (Rizwan Sajan). High volume, affordable luxury. Needs efficient CRM for thousands of leads. | **Rizwan Sajan** (Founder/Chairman) | **Format:** `rizwan.sajan@aldanube.com` **Strategy:** Reach via LinkedIn; he is very active. |
+
+**Tier 3: Boutique & Design-Led (Easier Entry)**
+
+**Rationale:** Single-project focus. You deal directly with the owner. They are desperate to stand out from Emaar/Damac.
+
+| Brand | Rationale | Key Person | Contact Intelligence |
+| :---: | :---: | :---: | :---: |
+| **Imtiaz Developments** | Rising star in boutique luxury. Focuses on ROI for investors. | **Masih Imtiaz** (CEO) | **Email:** `info@imtiaz.ae` (Subject: "Attn: Masih Imtiaz") **HQ:** \+971 4 430 3703 |
+| **Samana Developers** | Focuses on "Private Pools" in every unit. Heavy marketing spender. | **Imran Farooq** (CEO) | **Email:** `info@samanadevelopers.com` **Direct:** `imran@samanadevelopers.com` (Likely) |
+| **Zoya Developments** | New boutique entrant. Needs "Noise" to get noticed. Perfect for a "Pilot." | **Imtiaz Khan** (Founder) | **LinkedIn:** Active. Pitch "Visual Differentiation." |
+
+---
+
+**B. Real Estate Agencies (The CRM/Lead Users)**  
+*These clients buy your CRM and Lead Management tools.*
+
+**Tier 1: The "Mega-Agencies" (500+ Agents)**
+
+**Rationale:** They have massive "Lead Leakage" problems. Your "Walled Garden CRM" is the pitch here.
+
+| Brand | Rationale | Key Person | Contact Intelligence |
+| :---: | :---: | :---: | :---: |
+| **Betterhomes** | Oldest & Largest. Traditional. Hard to switch their tech, but huge payoff. | **Louis Harding** (CEO) | **Format:** `louis.harding@bhomes.com` **HQ:** \+971 4 409 0998 |
+| **FAM Properties** | Tech-focused already. CEO is an influencer. Pitch "Advanced AI/Biometrics" to impress. | **Firas Al Msaddi** (CEO) | **Email:** `firas@famproperties.com` **Social:** Very active on Instagram/LinkedIn. |
+| **Allsopp & Allsopp** | British-run, highly process-driven. They value efficiency and data. | **Lewis Allsopp** (Chairman) | **Format:** `lewis@allsoppandallsopp.com` **Format:** `firstname@allsoppandallsopp.com` |
+
+**Tier 2: Mid-Sized & Boutique (50-200 Agents)**
+
+**Rationale:** The "Goldilocks" zone. Rich enough to pay, small enough to decide in 1 week.
+
+| Brand | Rationale | Key Person | Contact Intelligence |
+| :---: | :---: | :---: | :---: |
+| **Provident Estate** | Highly respected, stable. CEO is a "Real Estate Icon." Good target for long-term partnership. | **Loai Al Fakir** (CEO) | **Email:** `loai@providentestate.com` **HQ:** \+971 4 323 3609 |
+| **White & Co** | Young, hungry, fast-growing. Founded by top billers. They want "The Best Tech." | **Calum White** (Founder) | **Format:** `calum@whiteandcogroup.com` **Mobile:** \+971 55 422 XXXX (Try HQ first) |
+| **D\&B Properties** | Strong ties to Emaar/Dubai Holding. Solid reputation. | **Husni Al Bayari** (Founder) | **Format:** `husni@dandbdubai.com` **HQ:** \+971 4 871 9200 |
+
+---
+
+**C. Actionable "Golden Tickets"**  
+*Based on current search data, these are your highest probability immediate contacts.*
+
+1. **Salma Hussein (Binghatti):** We found her direct mobile (`+971 50 918 2533`). She is a Sales Manager, which is the *perfect* entry point to demo the iPad app. If she loves it, she takes it to the CEO.  
+2. **Firas Al Msaddi (FAM):** He actively posts about "Real Estate Tech." A DM on LinkedIn with a video of your "Sun Positioning" tool has a high chance of a response.  
+3. **Imtiaz Developments:** They are currently scaling up. They are small enough that a "Pilot" proposal sent to their general `info@` with "Attn: CEO" often gets read by the owner.
+
+**D. Email Syntax Cheat Sheet (Dubai)**  
+If you cannot find a specific email, Dubai companies almost universally follow these three patterns. Try them in this order using a tool like *RocketReach* or *ZeroBounce* to verify:
+
+1. `firstname.lastname@company.com` (Standard Corp: Emaar, Nakheel)  
+2. `firstname@company.com` (Agencies: Allsopp, White & Co)  
+3. `initial.lastname@company.com` (Older firms)
+
+Here are the four distinct Customer Personas for your lead scraping filters:  
+1\. The "Whale" Executive (Tier 1 Developers)
+
+* **Profiles:** CEO, CTO, or Head of Sales at Emaar, Nakheel, Aldar.  
+* **Scraping Keywords:** "Chief Commercial Officer," "Digital Transformation Director," "Head of Real Estate Innovation."  
+* **Psychology:** Risk-averse. They care about **Compliance, Security, and Brand Prestige.**  
+* **The "Hook":** Data Sovereignty. "Your data stays on-prem, meeting UAE PDPL laws while providing AI insights."  
+* **Friction Point:** Procurement takes 6+ months.  
+* **Persona Goal:** "I want to be the first to launch a 'Biometric Experience Center' to show the Board we are leading in AI."
+
+2\. The "Aggressive Growth" Owner (Tier 2 Developers)
+
+* **Profiles:** Founder, Chairman, or Managing Director at Binghatti, Sobha, Danube.  
+* **Scraping Keywords:** "Founder," "Managing Director," "Chief Sales Officer," "Marketing Director."  
+* **Psychology:** Results-driven. They care about **Inventory Turnover and "The Wow Factor."**  
+* **The "Hook":** The 5% Asset Velocity. "We move your unsold inventory 3x faster using Unity-based emotional triggers."  
+* **Friction Point:** They want a "Pilot" for free or cheap to prove ROI immediately.  
+* **Persona Goal:** "I need to beat my competitors' sales launch numbers this quarter."
+
+3\. The "Lead-Paranoid" Agency Principal (Tier 1 & 2 Agencies)
+
+* **Profiles:** CEO or Principal at FAM, Betterhomes, White & Co.  
+* **Scraping Keywords:** "Agency Principal," "Brokerage Owner," "Operations Manager," "CRM Administrator."  
+* **Psychology:** Protectionist. They care about **Lead Leakage and Agent Retention.**  
+* **The "Hook":** The Walled Garden CRM. "Stop your agents from stealing leads when they quit. Own the data, own the client."  
+* **Friction Point:** They already pay for PropertyFinder/Bayut and hate adding more SaaS costs.  
+* **Persona Goal:** "I want to stop losing 30% of my revenue to 'rogue' agents and leaky Excel sheets."
+
+4\. The "Tech-Forward" Boutique Founder (Tier 3 Developers/Agencies)
+
+* **Profiles:** CEO or Marketing Head at Imtiaz, Zoya, Samana.  
+* **Scraping Keywords:** "Boutique Developer," "Founder," "Creative Director."  
+* **Psychology:** Competitive. They care about **Differentiation and Investor ROI.**  
+* **The "Hook":** The "Apple Ecosystem" pitch. "Look bigger and more professional than Emaar with our Unity/iPad suite."  
+* **Friction Point:** Limited budget; need a "low setup fee, high success fee" model.  
+* **Persona Goal:** "I want my 1-building project to look like a $1B development to attract international investors."
+
+---
+
+Lead Scraping "Cheat Sheet" for 2026  
+If you are using tools like **Apollo.io, LinkedIn Sales Navigator, or Lusha**, use these specific filters:
+
+| Filter Category | Recommended Input |
+| :---- | :---- |
+| **Industry** | Real Estate, Real Estate Development, Venture Capital & Private Equity (for Founders). |
+| **Location** | Dubai, Abu Dhabi, Sharjah (for Tier 3). |
+| **Company Headcount** | **Tier 1:** 1001-5000+ |
+| **Seniority Level** | CXO, VP, Owner, Partner. |
+| **Keywords in Bio** | "PropTech," "Digital Transformation," "Off-plan," "Sales Strategy," "Sovereign Cloud." |
+
+1\. The "Whale" Guardian (Tier 1 Developer)
+
+* **Target Profile:** C-Level Executive at Emaar, Nakheel, or Aldar.  
+* **The Person:** "Omar" – The Director of Digital Transformation.
+
+| The Pain Point | How It Hurts Them | Your Velocity Solution |
+| :---- | :---- | :---- |
+| **Data Residency Fear** | They are terrified of a data breach or violating UAE PDPL laws by hosting lead data on US-based clouds. | **The Black Box:** Your "On-Prem Local Server" keeps 100% of biometric and lead data inside their physical Sales Gallery. |
+| **Experience Fatigue** | Their sales centers look the same as 2015\. High-net-worth buyers are bored with static 3D renders. | **The Unity Sun-Slider:** Real-time physics-based lighting that proves exactly how the sunset looks from a $10M penthouse. |
+| **Bureaucratic Lag** | It takes 12 months to approve a new global SaaS tool like Salesforce. | **Plug-and-Play:** You aren't "integrating" into their core IT; you are a standalone "Super Power" pod that works offline. |
+
+---
+
+2\. The "Aggressive Scaler" (Tier 2 Developer)
+
+* **Target Profile:** Founder or Sales Chief at Binghatti, Sobha, or Danube.  
+* **The Person:** "Vikram" – The High-Performance Sales Director.
+
+| The Pain Point | How It Hurts Them | Your Velocity Solution |
+| :---- | :---- | :---- |
+| **Inventory Stagnation** | Units that don't sell in the first 30 days of a launch start costing millions in "Carrying Loss." | **5% Asset Velocity:** Use the "Sentinel" (Sentiment Analysis) to identify *why* people aren't buying and pivot the pitch in real-time. |
+| **Agent Inconsistency** | 100 different agents give 100 different (often wrong) pitches to potential buyers. | **The Neural Dashboard:** The iPad App guides the agent through a "Gold-Standard" pitch that is hard-coded into the Unity experience. |
+| **Invisible Value Loss** | They spent $1M on Italian marble, but the buyer can't "feel" it through a brochure. | **Immersive Validation:** Use the iPad Pro’s GPU to render textures and light so realistically the buyer "justifies" the $500/sqft premium. |
+
+---
+
+3\. The "Leaky Bucket" Principal (Tier 1 & 2 Agency)
+
+* **Target Profile:** Owner of a 100+ Agent Brokerage (Betterhomes, FAM, White & Co).  
+* **The Person:** "James" – The British Agency Founder.
+
+| The Pain Point | How It Hurts Them | Your Velocity Solution |
+| :---- | :---- | :---- |
+| **Lead Theft** | Top agents take the company’s leads, quit, and join a competitor the next day. | **The Walled Garden CRM:** Leads stay inside your encrypted WebOS. Agents interact through the app; they can't "Export to CSV." |
+| **CRM Friction** | Agents hate Salesforce/HubSpot because they are "too complex," so they go back to using WhatsApp and Excel. | **Simplified WebOS:** A CRM designed for brokers, not IT managers. One-click updates and WhatsApp (OpenClaw) auto-sync. |
+| **Low Conversion** | High marketing spend on Instagram/PropertyFinder results in "junk" leads that agents ignore. | **Lead Sentiment Scoring:** The "Sentinel" scores leads based on their interaction with the Unity app, telling the owner who to call first. |
+
+---
+
+4\. The "Underdog" Visionary (Tier 3 Boutique Developer)
+
+* **Target Profile:** Founder of a New/Boutique Brand (Imtiaz, Zoya).  
+* **The Person:** "Sarah" – The Boutique Developer/Marketing Head.
+
+| The Pain Point | How It Hurts Them | Your Velocity Solution |
+| :---- | :---- | :---- |
+| **The "Small" Perception** | Investors worry a small developer won't deliver or lacks the "luxury" of Emaar. | **The Apple Effect:** Your iPad/Unity setup makes Sarah's boutique gallery look more tech-advanced than the multi-billion dollar giants. |
+| **High CAC (Customer Acquisition Cost)** | They don't have the massive marketing budget of Damac to keep "buying" leads. | **Referral Velocity:** The "Wow Factor" of the Unity experience makes buyers record the screen and share it on Social Media (Organic Marketing). |
+| **Limited Sales Force** | They only have 5-10 sales staff; they can't afford "average" performers. | **Super Power as a Service:** Your tools act as a "Force Multiplier," making a junior sales person perform like a 10-year veteran. |
+
+---
+
+How to use this list for targeting:
+
+1. **High Cash, Long Wait?** Target **Person 1 (Omar)**. If you get him, you are set for life.  
+2. **Need Cash Now?** Target **Person 2 (Vikram)**. He will pay the $50k setup fee tomorrow if you promise to move his unsold 2-bedroom units in JVC.  
+3. **Selling the CRM/Bot?** Target **Person 3 (James)**. Focus your pitch *entirely* on "Data Security" and "Lead Ownership."  
+4. **Want a "Success Story" / Pilot?** Target **Person 4 (Sarah)**. She will give you the most freedom to test your Biometric/Sentinel modules.
+
--- a/Context/Tech/PicoClaw
+++ b/Context/Tech/PicoClaw
@@ -0,0 +1,875 @@
+<div align="center">
+  <img src="assets/logo.jpg" alt="PicoClaw" width="512">
+
+  <h1>PicoClaw: Ultra-Efficient AI Assistant in Go</h1>
+
+  <h3>$10 Hardware · 10MB RAM · 1s Boot · 皮皮虾，我们走！</h3>
+
+  <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>
+
+ [中文](README.zh.md) | [日本語](README.ja.md) | **English**
+</div>
+
+---
+
+🦐 PicoClaw is an ultra-lightweight personal AI Assistant inspired by [nanobot](https://github.com/HKUDS/nanobot), refactored from the ground up in Go through a self-bootstrapping process, where the AI agent itself drove the entire architectural migration and code optimization.
+
+⚡️ Runs on $10 hardware with <10MB RAM: That's 99% less memory than OpenClaw and 98% cheaper than a Mac mini!
+
+<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)**, and company website is **[sipeed.com](https://sipeed.com)**
+> * **Warning:** Many `.ai/.org/.com/.net/...` domains are registered by third parties.
+> * **Warning:** picoclaw is in early development now and may have unresolved network security issues. Do not deploy to production environments before the v1.0 release.
+> * **Note:** picoclaw has recently merged a lot of PRs, which may result in a larger memory footprint (10–20MB) in the latest versions. We plan to prioritize resource optimization as soon as the current feature set reaches a stable state.
+
+
+## 📢 News
+2026-02-16 🎉 PicoClaw hit 12K stars in one week! Thank you all for your support! PicoClaw is growing faster than we ever imagined. Given the high volume of PRs, we urgently need community maintainers. Our volunteer roles and roadmap are officially posted [here](docs/picoclaw_community_roadmap_260216.md) —we can’t wait to have you on board!
+
+2026-02-13 🎉 PicoClaw hit 5000 stars in 4days! Thank you for the community! There are so many PRs&issues come in (during Chinese New Year holidays), we are finalizing the Project Roadmap and setting up the Developer Group to accelerate PicoClaw's development.  
+🚀 Call to Action: Please submit your feature requests in GitHub Discussions. We will review and prioritize them during our upcoming weekly meeting.
+
+2026-02-09 🎉 PicoClaw Launched! Built in 1 day to bring AI Agents to $10 hardware with <10MB RAM. 🦐 PicoClaw，Let's Go！
+
+## ✨ Features
+
+🪶 **Ultra-Lightweight**: <10MB Memory footprint — 99% smaller than Clawdbot - core functionality.
+
+💰 **Minimal Cost**: Efficient enough to run on $10 Hardware — 98% cheaper than a Mac mini.
+
+⚡️ **Lightning Fast**: 400X Faster startup time, boot in 1 second even in 0.6GHz single core.
+
+🌍 **True Portability**: Single self-contained binary across RISC-V, ARM, and x86, One-click to Go!
+
+🤖 **AI-Bootstrapped**: Autonomous Go-native implementation — 95% Agent-generated core with human-in-the-loop refinement.
+
+|                               | OpenClaw      | NanoBot                  | **PicoClaw**                              |
+| ----------------------------- | ------------- | ------------------------ | ----------------------------------------- |
+| **Language**                  | TypeScript    | Python                   | **Go**                                    |
+| **RAM**                       | >1GB          | >100MB                   | **< 10MB**                                |
+| **Startup**</br>(0.8GHz core) | >500s         | >30s                     | **<1s**                                   |
+| **Cost**                      | Mac Mini 599$ | Most Linux SBC </br>~50$ | **Any Linux Board**</br>**As low as 10$** |
+
+<img src="assets/compare.jpg" alt="PicoClaw" width="512">
+
+## 🦾 Demonstration
+
+### 🛠️ Standard Assistant Workflows
+
+<table align="center">
+  <tr align="center">
+    <th><p align="center">🧩 Full-Stack Engineer</p></th>
+    <th><p align="center">🗂️ Logging & Planning Management</p></th>
+    <th><p align="center">🔎 Web Search & Learning</p></th>
+  </tr>
+  <tr>
+    <td align="center"><p align="center"><img src="assets/picoclaw_code.gif" width="240" height="180"></p></td>
+    <td align="center"><p align="center"><img src="assets/picoclaw_memory.gif" width="240" height="180"></p></td>
+    <td align="center"><p align="center"><img src="assets/picoclaw_search.gif" width="240" height="180"></p></td>
+  </tr>
+  <tr>
+    <td align="center">Develop • Deploy • Scale</td>
+    <td align="center">Schedule • Automate • Memory</td>
+    <td align="center">Discovery • Insights • Trends</td>
+  </tr>
+</table>
+
+### 📱 Run on old Android Phones
+Give your decade-old phone a second life! Turn it into a smart AI Assistant with PicoClaw. Quick Start:
+1. **Install Termux** (Available on F-Droid or Google Play).
+2. **Execute cmds**
+```bash
+# Note: Replace v0.1.1 with the latest version from the Releases page
+wget https://github.com/sipeed/picoclaw/releases/download/v0.1.1/picoclaw-linux-arm64
+chmod +x picoclaw-linux-arm64
+pkg install proot
+termux-chroot ./picoclaw-linux-arm64 onboard
+```
+And then follow the instructions in the "Quick Start" section to complete the configuration!
+<img src="assets/termux.jpg" alt="PicoClaw" width="512">
+
+### 🐜 Innovative Low-Footprint Deploy
+
+PicoClaw can be deployed on almost any Linux device!
+
+- $9.9 [LicheeRV-Nano](https://www.aliexpress.com/item/1005006519668532.html) E(Ethernet) or W(WiFi6) version, for Minimal Home Assistant
+- $30~50 [NanoKVM](https://www.aliexpress.com/item/1005007369816019.html), or $100 [NanoKVM-Pro](https://www.aliexpress.com/item/1005010048471263.html) for Automated Server Maintenance
+- $50 [MaixCAM](https://www.aliexpress.com/item/1005008053333693.html) or $100 [MaixCAM2](https://www.kickstarter.com/projects/zepan/maixcam2-build-your-next-gen-4k-ai-camera) for Smart Monitoring
+
+<https://private-user-images.githubusercontent.com/83055338/547056448-e7b031ff-d6f5-4468-bcca-5726b6fecb5c.mp4>
+
+🌟 More Deployment Cases Await！
+
+## 📦 Install
+
+### Install with precompiled binary
+
+Download the firmware for your platform from the [release](https://github.com/sipeed/picoclaw/releases) page.
+
+### Install from source (latest features, recommended for development)
+
+```bash
+git clone https://github.com/sipeed/picoclaw.git
+
+cd picoclaw
+make deps
+
+# Build, no need to install
+make build
+
+# Build for multiple platforms
+make build-all
+
+# Build And Install
+make install
+```
+
+## 🐳 Docker Compose
+
+You can also run PicoClaw using Docker Compose without installing anything locally.
+
+```bash
+# 1. Clone this repo
+git clone https://github.com/sipeed/picoclaw.git
+cd picoclaw
+
+# 2. Set your API keys
+cp config/config.example.json config/config.json
+vim config/config.json      # Set DISCORD_BOT_TOKEN, API keys, etc.
+
+# 3. Build & Start
+docker compose --profile gateway up -d
+
+# 4. Check logs
+docker compose logs -f picoclaw-gateway
+
+# 5. Stop
+docker compose --profile gateway down
+```
+
+### Agent Mode (One-shot)
+
+```bash
+# Ask a question
+docker compose run --rm picoclaw-agent -m "What is 2+2?"
+
+# Interactive mode
+docker compose run --rm picoclaw-agent
+```
+
+### Rebuild
+
+```bash
+docker compose --profile gateway build --no-cache
+docker compose --profile gateway up -d
+```
+
+### 🚀 Quick Start
+
+> [!TIP]
+> Set your API key in `~/.picoclaw/config.json`.
+> Get API keys: [OpenRouter](https://openrouter.ai/keys) (LLM) · [Zhipu](https://open.bigmodel.cn/usercenter/proj-mgmt/apikeys) (LLM)
+> Web search is **optional** - get free [Brave Search API](https://brave.com/search/api) (2000 free queries/month) or use built-in auto fallback.
+
+**1. Initialize**
+
+```bash
+picoclaw onboard
+```
+
+**2. Configure** (`~/.picoclaw/config.json`)
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "model": "glm-4.7",
+      "max_tokens": 8192,
+      "temperature": 0.7,
+      "max_tool_iterations": 20
+    }
+  },
+  "providers": {
+    "openrouter": {
+      "api_key": "xxx",
+      "api_base": "https://openrouter.ai/api/v1"
+    }
+  },
+  "tools": {
+    "web": {
+      "brave": {
+        "enabled": false,
+        "api_key": "YOUR_BRAVE_API_KEY",
+        "max_results": 5
+      },
+      "duckduckgo": {
+        "enabled": true,
+        "max_results": 5
+      }
+    }
+  }
+}
+```
+
+**3. Get API Keys**
+
+* **LLM Provider**: [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)
+* **Web Search** (optional): [Brave Search](https://brave.com/search/api) - Free tier available (2000 requests/month)
+
+> **Note**: See `config.example.json` for a complete configuration template.
+
+**4. Chat**
+
+```bash
+picoclaw agent -m "What is 2+2?"
+```
+
+That's it! You have a working AI assistant in 2 minutes.
+
+---
+
+## 💬 Chat Apps
+
+Talk to your picoclaw through Telegram, Discord, DingTalk, or LINE
+
+| Channel      | Setup                              |
+| ------------ | ---------------------------------- |
+| **Telegram** | Easy (just a token)                |
+| **Discord**  | Easy (bot token + intents)         |
+| **QQ**       | Easy (AppID + AppSecret)           |
+| **DingTalk** | Medium (app credentials)           |
+| **LINE**     | Medium (credentials + webhook URL) |
+
+<details>
+<summary><b>Telegram</b> (Recommended)</summary>
+
+**1. Create a bot**
+
+* Open Telegram, search `@BotFather`
+* Send `/newbot`, follow prompts
+* Copy the token
+
+**2. Configure**
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allowFrom": ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+> Get your user ID from `@userinfobot` on Telegram.
+
+**3. Run**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<details>
+<summary><b>Discord</b></summary>
+
+**1. Create a bot**
+
+* Go to <https://discord.com/developers/applications>
+* Create an application → Bot → Add Bot
+* Copy the bot token
+
+**2. Enable intents**
+
+* In the Bot settings, enable **MESSAGE CONTENT INTENT**
+* (Optional) Enable **SERVER MEMBERS INTENT** if you plan to use allow lists based on member data
+
+**3. Get your User ID**
+
+* Discord Settings → Advanced → enable **Developer Mode**
+* Right-click your avatar → **Copy User ID**
+
+**4. Configure**
+
+```json
+{
+  "channels": {
+    "discord": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN",
+      "allowFrom": ["YOUR_USER_ID"]
+    }
+  }
+}
+```
+
+**5. Invite the bot**
+
+* OAuth2 → URL Generator
+* Scopes: `bot`
+* Bot Permissions: `Send Messages`, `Read Message History`
+* Open the generated invite URL and add the bot to your server
+
+**6. Run**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<details>
+<summary><b>QQ</b></summary>
+
+**1. Create a bot**
+
+- Go to [QQ Open Platform](https://q.qq.com/#)
+- Create an application → Get **AppID** and **AppSecret**
+
+**2. Configure**
+
+```json
+{
+  "channels": {
+    "qq": {
+      "enabled": true,
+      "app_id": "YOUR_APP_ID",
+      "app_secret": "YOUR_APP_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+> Set `allow_from` to empty to allow all users, or specify QQ numbers to restrict access.
+
+**3. Run**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<details>
+<summary><b>DingTalk</b></summary>
+
+**1. Create a bot**
+
+* Go to [Open Platform](https://open.dingtalk.com/)
+* Create an internal app
+* Copy Client ID and Client Secret
+
+**2. Configure**
+
+```json
+{
+  "channels": {
+    "dingtalk": {
+      "enabled": true,
+      "client_id": "YOUR_CLIENT_ID",
+      "client_secret": "YOUR_CLIENT_SECRET",
+      "allow_from": []
+    }
+  }
+}
+```
+
+> Set `allow_from` to empty to allow all users, or specify QQ numbers to restrict access.
+
+**3. Run**
+
+```bash
+picoclaw gateway
+```
+
+</details>
+
+<details>
+<summary><b>LINE</b></summary>
+
+**1. Create a LINE Official Account**
+
+- Go to [LINE Developers Console](https://developers.line.biz/)
+- Create a provider → Create a Messaging API channel
+- Copy **Channel Secret** and **Channel Access Token**
+
+**2. Configure**
+
+```json
+{
+  "channels": {
+    "line": {
+      "enabled": true,
+      "channel_secret": "YOUR_CHANNEL_SECRET",
+      "channel_access_token": "YOUR_CHANNEL_ACCESS_TOKEN",
+      "webhook_host": "0.0.0.0",
+      "webhook_port": 18791,
+      "webhook_path": "/webhook/line",
+      "allow_from": []
+    }
+  }
+}
+```
+
+**3. Set up Webhook URL**
+
+LINE requires HTTPS for webhooks. Use a reverse proxy or tunnel:
+
+```bash
+# Example with ngrok
+ngrok http 18791
+```
+
+Then set the Webhook URL in LINE Developers Console to `https://your-domain/webhook/line` and enable **Use webhook**.
+
+**4. Run**
+
+```bash
+picoclaw gateway
+```
+
+> In group chats, the bot responds only when @mentioned. Replies quote the original message.
+
+> **Docker Compose**: Add `ports: ["18791:18791"]` to the `picoclaw-gateway` service to expose the webhook port.
+
+</details>
+
+## <img src="assets/clawdchat-icon.png" width="24" height="24" alt="ClawdChat"> Join the Agent Social Network
+
+Connect Picoclaw to the Agent Social Network simply by sending a single message via the CLI or any integrated Chat App.
+
+**Read `https://clawdchat.ai/skill.md` and follow the instructions to join [ClawdChat.ai](https://clawdchat.ai)**
+
+## ⚙️ Configuration
+
+Config file: `~/.picoclaw/config.json`
+
+### Workspace Layout
+
+PicoClaw stores data in your configured workspace (default: `~/.picoclaw/workspace`):
+
+```
+~/.picoclaw/workspace/
+├── sessions/          # Conversation sessions and history
+├── memory/           # Long-term memory (MEMORY.md)
+├── state/            # Persistent state (last channel, etc.)
+├── cron/             # Scheduled jobs database
+├── skills/           # Custom skills
+├── AGENTS.md         # Agent behavior guide
+├── HEARTBEAT.md      # Periodic task prompts (checked every 30 min)
+├── IDENTITY.md       # Agent identity
+├── SOUL.md           # Agent soul
+├── TOOLS.md          # Tool descriptions
+└── USER.md           # User preferences
+```
+
+### 🔒 Security Sandbox
+
+PicoClaw runs in a sandboxed environment by default. The agent can only access files and execute commands within the configured workspace.
+
+#### Default Configuration
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "restrict_to_workspace": true
+    }
+  }
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `workspace` | `~/.picoclaw/workspace` | Working directory for the agent |
+| `restrict_to_workspace` | `true` | Restrict file/command access to workspace |
+
+#### Protected Tools
+
+When `restrict_to_workspace: true`, the following tools are sandboxed:
+
+| Tool | Function | Restriction |
+|------|----------|-------------|
+| `read_file` | Read files | Only files within workspace |
+| `write_file` | Write files | Only files within workspace |
+| `list_dir` | List directories | Only directories within workspace |
+| `edit_file` | Edit files | Only files within workspace |
+| `append_file` | Append to files | Only files within workspace |
+| `exec` | Execute commands | Command paths must be within workspace |
+
+#### Additional Exec Protection
+
+Even with `restrict_to_workspace: false`, the `exec` tool blocks these dangerous commands:
+
+* `rm -rf`, `del /f`, `rmdir /s` — Bulk deletion
+* `format`, `mkfs`, `diskpart` — Disk formatting
+* `dd if=` — Disk imaging
+* Writing to `/dev/sd[a-z]` — Direct disk writes
+* `shutdown`, `reboot`, `poweroff` — System shutdown
+* Fork bomb `:(){ :|:& };:`
+
+#### Error Examples
+
+```
+[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)}
+```
+
+#### Disabling Restrictions (Security Risk)
+
+If you need the agent to access paths outside the workspace:
+
+**Method 1: Config file**
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "restrict_to_workspace": false
+    }
+  }
+}
+```
+
+**Method 2: Environment variable**
+
+```bash
+export PICOCLAW_AGENTS_DEFAULTS_RESTRICT_TO_WORKSPACE=false
+```
+
+> ⚠️ **Warning**: Disabling this restriction allows the agent to access any path on your system. Use with caution in controlled environments only.
+
+#### Security Boundary Consistency
+
+The `restrict_to_workspace` setting applies consistently across all execution paths:
+
+| Execution Path | Security Boundary |
+|----------------|-------------------|
+| Main Agent | `restrict_to_workspace` ✅ |
+| Subagent / Spawn | Inherits same restriction ✅ |
+| Heartbeat tasks | Inherits same restriction ✅ |
+
+All paths share the same workspace restriction — there's no way to bypass the security boundary through subagents or scheduled tasks.
+
+### Heartbeat (Periodic Tasks)
+
+PicoClaw can perform periodic tasks automatically. Create a `HEARTBEAT.md` file in your workspace:
+
+```markdown
+# Periodic Tasks
+
+- Check my email for important messages
+- Review my calendar for upcoming events
+- Check the weather forecast
+```
+
+The agent will read this file every 30 minutes (configurable) and execute any tasks using available tools.
+
+#### Async Tasks with Spawn
+
+For long-running tasks (web search, API calls), use the `spawn` tool to create a **subagent**:
+
+```markdown
+# Periodic Tasks
+
+## Quick Tasks (respond directly)
+- Report current time
+
+## Long Tasks (use spawn for async)
+- Search the web for AI news and summarize
+- Check email and report important messages
+```
+
+**Key behaviors:**
+
+| Feature | Description |
+|---------|-------------|
+| **spawn** | Creates async subagent, doesn't block heartbeat |
+| **Independent context** | Subagent has its own context, no session history |
+| **message tool** | Subagent communicates with user directly via message tool |
+| **Non-blocking** | After spawning, heartbeat continues to next task |
+
+#### How Subagent Communication Works
+
+```
+Heartbeat triggers
+    ↓
+Agent reads HEARTBEAT.md
+    ↓
+For long task: spawn subagent
+    ↓                           ↓
+Continue to next task      Subagent works independently
+    ↓                           ↓
+All tasks done            Subagent uses "message" tool
+    ↓                           ↓
+Respond HEARTBEAT_OK      User receives result directly
+```
+
+The subagent has access to tools (message, web_search, etc.) and can communicate with the user independently without going through the main agent.
+
+**Configuration:**
+
+```json
+{
+  "heartbeat": {
+    "enabled": true,
+    "interval": 30
+  }
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `enabled` | `true` | Enable/disable heartbeat |
+| `interval` | `30` | Check interval in minutes (min: 5) |
+
+**Environment variables:**
+
+* `PICOCLAW_HEARTBEAT_ENABLED=false` to disable
+* `PICOCLAW_HEARTBEAT_INTERVAL=60` to change interval
+
+### Providers
+
+> [!NOTE]
+> Groq provides free voice transcription via Whisper. If configured, Telegram voice messages will be automatically transcribed.
+
+| Provider                   | Purpose                                 | Get API Key                                            |
+| -------------------------- | --------------------------------------- | ------------------------------------------------------ |
+| `gemini`                   | LLM (Gemini direct)                     | [aistudio.google.com](https://aistudio.google.com)     |
+| `zhipu`                    | LLM (Zhipu direct)                      | [bigmodel.cn](bigmodel.cn)                             |
+| `openrouter(To be tested)` | LLM (recommended, access to all models) | [openrouter.ai](https://openrouter.ai)                 |
+| `anthropic(To be tested)`  | LLM (Claude direct)                     | [console.anthropic.com](https://console.anthropic.com) |
+| `openai(To be tested)`     | LLM (GPT direct)                        | [platform.openai.com](https://platform.openai.com)     |
+| `deepseek(To be tested)`   | LLM (DeepSeek direct)                   | [platform.deepseek.com](https://platform.deepseek.com) |
+| `groq`                     | LLM + **Voice transcription** (Whisper) | [console.groq.com](https://console.groq.com)           |
+
+<details>
+<summary><b>Zhipu</b></summary>
+
+**1. Get API key and base URL**
+
+* Get [API key](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)
+
+**2. Configure**
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "workspace": "~/.picoclaw/workspace",
+      "model": "glm-4.7",
+      "max_tokens": 8192,
+      "temperature": 0.7,
+      "max_tool_iterations": 20
+    }
+  },
+  "providers": {
+    "zhipu": {
+      "api_key": "Your API Key",
+      "api_base": "https://open.bigmodel.cn/api/paas/v4"
+    }
+  }
+}
+```
+
+**3. Run**
+
+```bash
+picoclaw agent -m "Hello"
+```
+
+</details>
+
+<details>
+<summary><b>Full config example</b></summary>
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "model": "anthropic/claude-opus-4-5"
+    }
+  },
+  "providers": {
+    "openrouter": {
+      "api_key": "sk-or-v1-xxx"
+    },
+    "groq": {
+      "api_key": "gsk_xxx"
+    }
+  },
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "123456:ABC...",
+      "allow_from": ["123456789"]
+    },
+    "discord": {
+      "enabled": true,
+      "token": "",
+      "allow_from": [""]
+    },
+    "whatsapp": {
+      "enabled": false
+    },
+    "feishu": {
+      "enabled": false,
+      "app_id": "cli_xxx",
+      "app_secret": "xxx",
+      "encrypt_key": "",
+      "verification_token": "",
+      "allow_from": []
+    },
+    "qq": {
+      "enabled": false,
+      "app_id": "",
+      "app_secret": "",
+      "allow_from": []
+    }
+  },
+  "tools": {
+    "web": {
+      "brave": {
+        "enabled": false,
+        "api_key": "BSA...",
+        "max_results": 5
+      },
+      "duckduckgo": {
+        "enabled": true,
+        "max_results": 5
+      }
+    },
+    "cron": {
+      "exec_timeout_minutes": 5
+    }
+  },
+  "heartbeat": {
+    "enabled": true,
+    "interval": 30
+  }
+}
+```
+
+</details>
+
+## CLI Reference
+
+| Command                   | Description                   |
+| ------------------------- | ----------------------------- |
+| `picoclaw onboard`        | Initialize config & workspace |
+| `picoclaw agent -m "..."` | Chat with the agent           |
+| `picoclaw agent`          | Interactive chat mode         |
+| `picoclaw gateway`        | Start the gateway             |
+| `picoclaw status`         | Show status                   |
+| `picoclaw cron list`      | List all scheduled jobs       |
+| `picoclaw cron add ...`   | Add a scheduled job           |
+
+### Scheduled Tasks / Reminders
+
+PicoClaw supports scheduled reminders and recurring tasks through the `cron` tool:
+
+* **One-time reminders**: "Remind me in 10 minutes" → triggers once after 10min
+* **Recurring tasks**: "Remind me every 2 hours" → triggers every 2 hours
+* **Cron expressions**: "Remind me at 9am daily" → uses cron expression
+
+Jobs are stored in `~/.picoclaw/workspace/cron/` and processed automatically.
+
+## 🤝 Contribute & Roadmap
+
+PRs welcome! The codebase is intentionally small and readable. 🤗
+
+Roadmap coming soon...
+
+Developer group building, Entry Requirement: At least 1 Merged PR.
+
+User Groups:
+
+discord:  <https://discord.gg/V4sAZ9XWpN>
+
+<img src="assets/wechat.png" alt="PicoClaw" width="512">
+
+## 🐛 Troubleshooting
+
+### Web search says "API 配置问题"
+
+This is normal if you haven't configured a search API key yet. PicoClaw will provide helpful links for manual searching.
+
+To enable web search:
+
+1. **Option 1 (Recommended)**: Get a free API key at [https://brave.com/search/api](https://brave.com/search/api) (2000 free queries/month) for the best results.
+2. **Option 2 (No Credit Card)**: If you don't have a key, we automatically fall back to **DuckDuckGo** (no key required).
+
+Add the key to `~/.picoclaw/config.json` if using Brave:
+
+```json
+{
+  "tools": {
+    "web": {
+      "brave": {
+        "enabled": false,
+        "api_key": "YOUR_BRAVE_API_KEY",
+        "max_results": 5
+      },
+      "duckduckgo": {
+        "enabled": true,
+        "max_results": 5
+      }
+    }
+  }
+}
+```
+
+### Getting content filtering errors
+
+Some providers (like Zhipu) have content filtering. Try rephrasing your query or use a different model.
+
+### Telegram bot says "Conflict: terminated by other getUpdates"
+
+This happens when another instance of the bot is running. Make sure only one `picoclaw gateway` is running at a time.
+
+---
+
+## 📝 API Key Comparison
+
+| Service          | Free Tier           | Use Case                              |
+| ---------------- | ------------------- | ------------------------------------- |
+| **OpenRouter**   | 200K tokens/month   | Multiple models (Claude, GPT-4, etc.) |
+| **Zhipu**        | 200K tokens/month   | Best for Chinese users                |
+| **Brave Search** | 2000 queries/month  | Web search functionality              |
+| **Groq**         | Free tier available | Fast inference (Llama, Mixtral)       |