Claude Code: Based on the architecture verification report, I need you to perform the

CAIN_CRITICAL_SETUP_REPORT.md

@@ -0,0 +1,207 @@
+# Cain Critical Setup Report
+**Generated:** 2026-03-14
+**Status:** ⚠️ **ACTION REQUIRED** - Data Persistence Disabled
+
+---
+
+## Executive Summary
+
+Cain's HuggingFace Space is **RUNNING** but **missing critical environment variables** for data persistence. All conversations, settings, and credentials will be **LOST** when the Space restarts without proper configuration.
+
+---
+
+## 1. Cain Identity Verification
+
+| Attribute | Value | Status |
+|-----------|-------|--------|
+| **Space Name** | HuggingClaw-Cain | ✅ Confirmed (README.md) |
+| **Space ID** | `tao-shen/HuggingClaw-Cain` | ✅ Derived |
+| **Dataset ID** | `tao-shen/HuggingClaw-Cain-data` | ✅ Auto-derived |
+| **Current Stage** | RUNNING | ✅ Confirmed |
+| **Health Status** | ALIVE (idle) | ✅ Confirmed |
+
+**Identity Status:** ✅ **VERIFIED** - Cain Space exists as `tao-shen/HuggingClaw-Cain`
+
+---
+
+## 2. Critical Environment Variables Status
+
+| Variable | Required | Current | Expected | Action Needed |
+|----------|----------|---------|----------|---------------|
+| `HF_TOKEN` | **YES** | ❌ NOT SET | User's HF token | ⚠️ **MUST SET** |
+| `OPENCLAW_DATASET_REPO` | AUTO | ❌ NOT SET | `tao-shen/HuggingClaw-Cain-data` | ✅ Auto-derives |
+| `AUTO_CREATE_DATASET` | RECOMMENDED | ❌ NOT SET | `true` | ⚠️ **SHOULD SET** |
+
+**Persistence Status:** ⚠️ **DISABLED** - Without `HF_TOKEN`, no data is saved
+
+---
+
+## 3. sync_hf.py Verification
+
+| Component | Location | Status | Details |
+|-----------|----------|--------|---------|
+| **Script** | `scripts/sync_hf.py` | ✅ EXISTS | 929 lines, full implementation |
+| **Full Directory Sync** | Lines 182-687 | ✅ IMPLEMENTED | Uploads/downloads entire ~/.openclaw |
+| **Change Detection** | Lines 203-239 | ✅ IMPLEMENTED | Hash-based file change detection |
+| **Auto-Derived Dataset** | Lines 105-120 | ✅ IMPLEMENTED | Auto-derives from SPACE_ID |
+| **Auto-Create Dataset** | Lines 243-266 | ✅ IMPLEMENTED | Creates when AUTO_CREATE_DATASET=true |
+| **Graceful Shutdown** | Lines 881-918 | ✅ IMPLEMENTED | SIGINT/SIGTERM handlers |
+| **Background Sync** | Lines 690-696 | ✅ IMPLEMENTED | Configurable interval (default 60s) |
+
+**Script Status:** ✅ **FULLY OPERATIONAL** - All features implemented correctly
+
+---
+
+## 4. Required Actions for User
+
+### Step 1: Generate HF_TOKEN
+
+1. Visit: https://huggingface.co/settings/tokens
+2. Click **"New token"**
+3. **Token type:** Select **"Write"** (required for dataset operations)
+4. **Token name:** Enter `HuggingClaw-Cain`
+5. Click **"Generate token"**
+6. **Copy the token** - it will look like `hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
+
+⚠️ **IMPORTANT:** The token is only shown once. Save it securely.
+
+### Step 2: Configure Space Settings
+
+1. Go to: https://huggingface.co/spaces/tao-shen/HuggingClaw-Cain/settings
+2. Scroll to **"Repository Secrets"** section
+3. Add the following secrets:
+
+| Name | Value | Secret |
+|------|-------|--------|
+| `HF_TOKEN` | `hf_***` (your token from Step 1) | ✅ Yes |
+| `AUTO_CREATE_DATASET` | `true` | ❌ No |
+
+4. Click **"Save"** for each secret added
+
+### Step 3: Restart the Space
+
+After adding environment variables:
+
+1. Go to **Settings** tab
+2. Scroll to **"Factory reset"** section
+3. Click **"Factory reset and reboot"** (this ensures clean restart with new env vars)
+4. Wait ~2-3 minutes for the Space to restart
+5. Monitor logs to verify Dataset setup
+
+### Step 4: Verify Configuration
+
+After restart, check the logs for success messages:
+
+```
+[SYNC] OPENCLAW_DATASET_REPO not set — auto-derived from SPACE_ID: tao-shen/HuggingClaw-Cain-data
+[SYNC] Dataset repo NOT found: tao-shen/HuggingClaw-Cain-data — creating...
+[SYNC] ✓ Dataset repo created: tao-shen/HuggingClaw-Cain-data
+[SYNC] ▶ Restoring ~/.openclaw from dataset tao-shen/HuggingClaw-Cain-data ...
+```
+
+Or check the Dataset exists at:
+https://huggingface.co/datasets/tao-shen/HuggingClaw-Cain-data
+
+---
+
+## 5. What Gets Persisted
+
+Once configured, Cain will sync the entire `~/.openclaw` directory:
+
+### Included in Backup:
+- ✅ Conversations and chat history
+- ✅ Settings and configuration
+- ✅ API credentials and keys
+- ✅ Agent plugins and configurations
+- ✅ Workspace files and memories
+- ✅ SOUL.md, MEMORY.md, AGENTS.md
+- ✅ Agent session data
+
+### Excluded from Backup:
+- ❌ `*.log` files (regenerated on startup)
+- ❌ `*.lock` files (stale after restart)
+- ❌ `*.tmp` and `*.pid` files
+- ❌ `__pycache__` directories
+
+### Sync Schedule:
+1. **Startup:** Download latest data from Dataset
+2. **Periodic:** Upload changes every 60 seconds (configurable via SYNC_INTERVAL)
+3. **Shutdown:** Final upload before Space stops
+
+---
+
+## 6. Troubleshooting
+
+### Error: "HF_TOKEN not set"
+**Solution:** Add `HF_TOKEN` as a Repository Secret in Space settings.
+
+### Error: "Dataset repo NOT found: xxx"
+**Solution:** Set `AUTO_CREATE_DATASET=true` to auto-create, or create manually.
+
+### Error: "Could not derive username from HF_TOKEN"
+**Solution:** Verify your `HF_TOKEN` has read permissions. Check the token type is "Write".
+
+### Data not persisting after restart
+**Solution:** Check logs for sync errors. Verify `HF_TOKEN` has Write permissions.
+
+---
+
+## 7. Minimum Working Configuration
+
+For automatic setup (recommended), add these as Repository Secrets:
+
+```bash
+HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # (Secret)
+AUTO_CREATE_DATASET=true
+```
+
+The Dataset ID will be automatically set to: `tao-shen/HuggingClaw-Cain-data`
+
+---
+
+## 8. Current Cain Status Summary
+
+| Component | Status |
+|-----------|--------|
+| **Space Status** | ✅ RUNNING |
+| **Health** | ✅ ALIVE (idle) |
+| **Identity** | ✅ VERIFIED (`tao-shen/HuggingClaw-Cain`) |
+| **HF_TOKEN** | ❌ NOT SET |
+| **OPENCLAW_DATASET_REPO** | ❌ NOT SET (will auto-derive) |
+| **AUTO_CREATE_DATASET** | ❌ NOT SET (defaults to false) |
+| **sync_hf.py Script** | ✅ VERIFIED (929 lines) |
+| **Data Persistence** | ⚠️ **DISABLED** |
+
+---
+
+## 9. Important Notes
+
+### ⚠️ DO NOT RESTART YET
+The Space should NOT be restarted until the environment variables are properly configured. A restart now would result in:
+- All current conversations being lost
+- All settings being reset to defaults
+- Any configured credentials being wiped
+
+### ✅ Configuration Checklist
+Before restarting, ensure:
+- [ ] `HF_TOKEN` is set with Write permissions
+- [ ] `AUTO_CREATE_DATASET=true` is set
+- [ ] The token has been tested at https://huggingface.co/settings/tokens
+
+---
+
+## 10. Files Reference
+
+| File | Purpose | Status |
+|------|---------|--------|
+| `scripts/sync_hf.py` | Main persistence script | ✅ VERIFIED |
+| `scripts/openclaw.json.default` | Default config template | ✅ PRESENT |
+| `.env.example` | Environment variable reference | ✅ PRESENT |
+| `README.md` | Space documentation | ✅ PRESENT |
+| `Dockerfile` | Space build configuration | ✅ VERIFIED |
+
+---
+
+**Report End**
+
+*Generated by Claude Code - Architecture Verification System*

QUICK_START_GUIDE.md

@@ -0,0 +1,171 @@
+# Cain Quick Start Guide - HuggingFace Space Setup
+
+**For:** tao-shen/HuggingClaw-Cain
+**Purpose:** Enable data persistence by configuring required environment variables
+
+---
+
+## Overview
+
+This guide will help you configure Cain's HuggingFace Space to enable data persistence. Without these settings, all conversations, settings, and credentials will be lost when the Space restarts.
+
+---
+
+## Prerequisites
+
+- HuggingFace account with access to create Spaces and Datasets
+- Access to the `tao-shen/HuggingClaw-Cain` Space
+
+---
+
+## Step 1: Generate HuggingFace Token
+
+1. **Visit:** https://huggingface.co/settings/tokens
+2. **Click:** "New token"
+3. **Token type:** Select **"Write"** (this is required for dataset operations)
+4. **Token name:** Enter `HuggingClaw-Cain` (or any descriptive name)
+5. **Click:** "Generate token"
+6. **Copy the token** - it will look like: `hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
+
+⚠️ **IMPORTANT:** The token is only shown once. Save it securely.
+
+---
+
+## Step 2: Configure Space Settings
+
+1. **Visit:** https://huggingface.co/spaces/tao-shen/HuggingClaw-Cain/settings
+2. **Scroll to:** "Repository Secrets" section
+3. **Add the following secrets:**
+
+### Secret 1: HF_TOKEN
+| Field | Value |
+|-------|-------|
+| Name | `HF_TOKEN` |
+| Value | `hf_***` (paste your token from Step 1) |
+| Secret | ✅ Yes (check this box) |
+
+Click **"Save"**
+
+### Secret 2: AUTO_CREATE_DATASET
+| Field | Value |
+|-------|-------|
+| Name | `AUTO_CREATE_DATASET` |
+| Value | `true` |
+| Secret | ❌ No (leave unchecked) |
+
+Click **"Save"**
+
+---
+
+## Step 3: Restart the Space
+
+1. **Stay on:** Settings page
+2. **Scroll to:** "Factory reset" section
+3. **Click:** "Factory reset and reboot"
+4. **Wait:** 2-3 minutes for the Space to restart
+5. **Monitor:** Check the logs for success messages
+
+---
+
+## Step 4: Verify Configuration
+
+### Check Logs for Success Messages
+
+After restart, you should see these messages in the logs:
+
+```
+[SYNC] OPENCLAW_DATASET_REPO not set — auto-derived from SPACE_ID: tao-shen/HuggingClaw-Cain-data
+[SYNC] Dataset repo NOT found: tao-shen/HuggingClaw-Cain-data — creating...
+[SYNC] ✓ Dataset repo created: tao-shen/HuggingClaw-Cain-data
+[SYNC] ▶ Restoring ~/.openclaw from dataset tao-shen/HuggingClaw-Cain-data ...
+```
+
+### Check Dataset Creation
+
+Visit: https://huggingface.co/datasets/tao-shen/HuggingClaw-Cain-data
+
+You should see a private dataset with a `.openclaw` folder containing Cain's data.
+
+---
+
+## What This Enables
+
+Once configured, Cain will automatically:
+
+- **Save** all conversations every 60 seconds
+- **Persist** settings and configuration across restarts
+- **Backup** API credentials and keys securely
+- **Restore** all data automatically on startup
+- **Create** snapshots of agent state and memories
+
+---
+
+## Troubleshooting
+
+### "HF_TOKEN not set" Error
+**Cause:** Token not added to Repository Secrets
+**Fix:** Repeat Step 2
+
+### "Dataset repo NOT found" Error
+**Cause:** `AUTO_CREATE_DATASET` not set to `true`
+**Fix:** Add `AUTO_CREATE_DATASET=true` as a Repository Secret
+
+### "Could not derive username from HF_TOKEN" Error
+**Cause:** Token lacks read permissions or is invalid
+**Fix:** Generate a new token with "Write" permissions
+
+### Data Not Persisting After Restart
+**Cause:** Token may have insufficient permissions
+**Fix:** Verify token has "Write" permissions (not just "Read")
+
+---
+
+## Optional Variables
+
+You can also configure these optional variables:
+
+### SYNC_INTERVAL
+Controls how often data is synced (in seconds)
+- **Default:** `60` (60 seconds)
+- **Lower values:** More frequent saves, more API calls
+- **Higher values:** Less frequent saves, fewer API calls
+
+### OPENCLAW_DATASET_REPO
+Manually specify the Dataset repository
+- **Default:** Auto-derived as `{SPACE_ID}-data`
+- **Custom:** Set to `username/dataset-name` to use a different dataset
+
+---
+
+## Security Notes
+
+- ✅ `HF_TOKEN` is stored as a **Repository Secret** - encrypted and not visible in logs
+- ✅ Dataset is created as **Private** by default
+- ✅ Token only needs **Write** permissions (not full account access)
+- ⚠️ Never share your token or commit it to git
+
+---
+
+## Next Steps
+
+After configuration:
+
+1. ✅ Verify Dataset was created
+2. ✅ Test persistence by having a conversation and restarting
+3. ✅ Check that conversations persist after restart
+4. ✅ Monitor sync logs for any errors
+
+---
+
+## Support
+
+For issues or questions:
+- Check the main HuggingClaw repository
+- Review sync logs in Cain's workspace: `~/.openclaw/workspace/sync.log`
+- Refer to `CAIN_CRITICAL_SETUP_REPORT.md` for detailed analysis
+
+---
+
+**Guide End**
+
+*Generated by Claude Code - Cain Setup Automation*