docs: comprehensive documentation update for Ruflo integration

- Updated README.md with complete feature documentation: * Added Hermes Agent × Claude Code × Ruflo × Opencode branding * Comprehensive feature list (24/7 bot, self-learning, voice I/O, self-evolve) * Multi-agent swarm system (9 agent roles, 3 topologies) * Plugin system (16 extension points) * Hook system (pre/post tool/AI/session) * Enhanced memory backend (JSON + LRU) * Full feature comparison table vs Hermes/Claude/Ruflo * Architecture diagrams * Usage examples for all commands - Updated package.json: * Bumped version to 2.0.0 * Added comprehensive metadata (author, license, repository) * Added keywords for discoverability * Added support/funding links - Added INSTALLATION.md: * Complete setup guide (5-minute quick start) * Detailed installation steps (Node.js, ffmpeg, Python, Vosk) * Telegram bot configuration * Webhook setup (ngrok + domain) * Systemd service installation * Troubleshooting section * Advanced setup (Docker, multiple instances, SSL) - Added CREDITS.md: * Core project credits (Hermes Agent, Claude Code, Ruflo, Opencode) * Technology libraries (grammy, Express, Winston, Vosk, etc.) * Special thanks to NousResearch, Anthropic, RuvNet * Third-party license attribution - Added CONTRIBUTING.md: * How to contribute (bugs, features, docs, tests) * Development guidelines (code style, commit messages) * Architecture guidelines (plugins, hooks, agents) * Testing requirements * Security guidelines * Bug report and feature request templates * PR process and code review All documentation now reflects the complete Ruflo integration with 1,977 lines of new code.
2026-05-06 10:08:36 +00:00
parent 24d2da0b2d
commit 53b9fa8c8a
5 changed files with 2003 additions and 685 deletions
--- a/INSTALLATION.md
+++ b/INSTALLATION.md
@@ -0,0 +1,545 @@
+# zCode CLI X - Installation & Setup Guide
+
+## Prerequisites
+
+### Required
+- **Node.js** ≥ 20.0.0 ([Download](https://nodejs.org/))
+- **npm** ≥ 9.0.0 (comes with Node.js)
+- **Git** (for version control)
+- **systemd** (for 24/7 service on Linux)
+- **ffmpeg** (for voice I/O)
+- **Python 3.8+** (for Vosk STT)
+
+### Optional
+- **SSL certificate** (for HTTPS webhook)
+- **Domain name** (for custom webhook URL)
+- **Docker** (for containerized deployment - coming soon)
+
+---
+
+## Quick Start (5 Minutes)
+
+### 1. Clone Repository
+
+```bash
+git clone https://github.rommark.dev/admin/zCode-CLI-X.git
+cd zCode-CLI-X
+```
+
+### 2. Install Dependencies
+
+```bash
+npm install
+```
+
+### 3. Configure Environment
+
+```bash
+cp .env.example .env
+nano .env
+```
+
+Edit `.env` with your credentials:
+
+```env
+# Z.AI Configuration (Coding Plan)
+GLM_BASE_URL=https://api.z.ai/api/coding/paas/v4
+ZAI_API_KEY=your_zai_api_key_here
+
+# Telegram Bot Configuration
+TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
+TELEGRAM_ALLOWED_USERS=your_telegram_id,friend_id
+ZCODE_WEBHOOK_URL=https://your-domain.com/telegram/webhook
+```
+
+### 4. Test Run
+
+```bash
+# Test as CLI (temporary session)
+node bin/zcode.js
+
+# Test as bot (24/7)
+node bin/zcode.js --no-cli
+```
+
+### 5. Install as Systemd Service
+
+```bash
+# Copy service file
+cp scripts/zcode.service ~/.config/systemd/user/
+
+# Reload systemd
+systemctl --user daemon-reload
+
+# Enable and start service
+systemctl --user enable zcode
+systemctl --user start zcode
+
+# Check status
+systemctl --user status zcode
+
+# View logs
+journalctl --user -u zcode -f
+```
+
+✅ **Done!** Your bot is now running 24/7.
+
+---
+
+## Detailed Setup
+
+### Step 1: Install Node.js
+
+#### Ubuntu/Debian
+```bash
+curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
+sudo apt-get install -y nodejs
+node --version  # Should show v20.x or higher
+npm --version   # Should show 9.x or higher
+```
+
+#### macOS (Homebrew)
+```bash
+brew install node@20
+node --version
+npm --version
+```
+
+#### CentOS/RHEL
+```bash
+curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
+sudo yum install -y nodejs
+node --version
+npm --version
+```
+
+### Step 2: Install ffmpeg (for Voice I/O)
+
+#### Ubuntu/Debian
+```bash
+sudo apt-get update
+sudo apt-get install -y ffmpeg
+ffmpeg -version  # Verify installation
+```
+
+#### macOS
+```bash
+brew install ffmpeg
+ffmpeg -version
+```
+
+#### CentOS/RHEL
+```bash
+sudo yum install -y ffmpeg
+ffmpeg -version
+```
+
+### Step 3: Install Python & Vosk (for Voice STT)
+
+#### Install Python 3.8+
+```bash
+# Ubuntu/Debian
+sudo apt-get install -y python3 python3-pip
+
+# macOS
+brew install python
+
+# Verify
+python3 --version  # Should show 3.8+
+pip3 --version
+```
+
+#### Install Vosk Model
+```bash
+# Create model directory
+mkdir -p ~/vosk-models
+
+# Download small model (68MB, ~95% accuracy)
+cd ~/vosk-models
+wget https://alphacephei.com/vosk-models/vosk-model-small-0.15.zip
+unzip vosk-model-small-0.15.zip
+
+# Verify
+ls -la vosk-model-small-0.15/  # Should show model files
+```
+
+#### Install Vosk Python Package
+```bash
+pip3 install vosk
+pip3 install sounddevice  # For audio recording
+pip3 install scipy  # For audio processing
+```
+
+### Step 4: Configure Telegram Bot
+
+#### 1. Create Bot with BotFather
+1. Open Telegram and search for `@BotFather`
+2. Send `/newbot` command
+3. Follow prompts to name your bot
+4. Save the **API Token** (looks like: `123456789:ABCdefGHIjklMNOpqrsTUVwxyz`)
+
+#### 2. Get Your Telegram ID
+1. Search for `@userinfobot` in Telegram
+2. Send any message
+3. Copy your **User ID** (looks like: `123456789`)
+
+#### 3. Update `.env`
+```env
+TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
+TELEGRAM_ALLOWED_USERS=123456789,987654321  # Your ID + friends' IDs
+```
+
+### Step 5: Set Up Webhook
+
+#### Option A: Using ngrok (Quick Testing)
+```bash
+# Install ngrok
+npm install -g ngrok
+
+# Start local server
+node bin/zcode.js --no-cli &
+
+# Expose to internet (in new terminal)
+ngrok http 3001
+
+# Copy the HTTPS URL (e.g., https://abc123.ngrok.io)
+# Update .env:
+# ZCODE_WEBHOOK_URL=https://abc123.ngrok.io/telegram/webhook
+
+# Set webhook via API
+curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook?url=https://abc123.ngrok.io/telegram/webhook"
+```
+
+#### Option B: Using Domain (Production)
+```bash
+# 1. Set up Nginx reverse proxy
+sudo nano /etc/nginx/sites-available/zcode
+
+# Add:
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    location /telegram/webhook {
+        proxy_pass http://localhost:3001;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}
+
+# Enable site
+sudo ln -s /etc/nginx/sites-available/zcode /etc/nginx/sites-enabled/
+sudo nginx -t
+sudo systemctl restart nginx
+```
+
+```bash
+# 2. Get SSL certificate (Let's Encrypt)
+sudo apt-get install -y certbot python3-certbot-nginx
+sudo certbot --nginx -d your-domain.com
+
+# 3. Set webhook
+curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook?url=https://your-domain.com/telegram/webhook"
+```
+
+### Step 6: Install Systemd Service
+
+#### 1. Copy Service File
+```bash
+cp scripts/zcode.service ~/.config/systemd/user/
+```
+
+#### 2. Edit Service File (if needed)
+```bash
+nano ~/.config/systemd/user/zcode.service
+```
+
+Update paths if necessary:
+```ini
+[Service]
+ExecStart=/usr/bin/node /home/uroma2/zcode-cli-x/bin/zcode.js --no-cli
+WorkingDirectory=/home/uroma2/zcode-cli-x
+```
+
+#### 3. Enable and Start
+```bash
+systemctl --user daemon-reload
+systemctl --user enable zcode
+systemctl --user start zcode
+```
+
+#### 4. Verify
+```bash
+systemctl --user status zcode
+# Should show: Active: active (running)
+
+journalctl --user -u zcode -f
+# Should show: zCode CLI X running 24/7
+```
+
+---
+
+## Configuration Reference
+
+### Environment Variables
+
+| Variable | Required | Description | Example |
+|----------|----------|-------------|---------|
+| `GLM_BASE_URL` | ✅ | Z.AI API base URL | `https://api.z.ai/api/coding/paas/v4` |
+| `ZAI_API_KEY` | ✅ | Z.AI API key | `d88afea988...` |
+| `TELEGRAM_BOT_TOKEN` | ✅ | Telegram bot token | `123456789:ABCdef...` |
+| `TELEGRAM_ALLOWED_USERS` | ✅ | Comma-separated user IDs | `123456789,987654321` |
+| `ZCODE_WEBHOOK_URL` | ✅ | Webhook endpoint URL | `https://your-domain.com/telegram/webhook` |
+| `VOSK_MODEL_PATH` | ❌ | Path to Vosk model | `~/vosk-models/vosk-model-small-0.15` |
+| `FFMPEG_PATH` | ❌ | Path to ffmpeg binary | `/usr/bin/ffmpeg` |
+| `RTK_PATH` | ❌ | Path to RTK binary | `~/.local/bin/rtk` |
+| `LOG_LEVEL` | ❌ | Logging level | `debug`, `info`, `warn`, `error` |
+| `LOG_FILE` | ❌ | Log file path | `logs/zcode.log` |
+
+### Config File (`.zcode.config.json`)
+
+```json
+{
+  "api": {
+    "baseUrl": "https://api.z.ai/api/coding/paas/v4",
+    "models": {
+      "default": "glm-5.1",
+      "fallback": "glm-4v"
+    }
+  },
+  "telegram": {
+    "allowedUsers": ["123456789"],
+    "webhookUrl": "https://your-domain.com/telegram/webhook"
+  },
+  "memory": {
+    "maxEntries": 500,
+    "evictionPolicy": "lru"
+  },
+  "agents": {
+    "enabled": ["coder", "reviewer", "architect"],
+    "maxTurns": 10
+  }
+}
+```
+
+---
+
+## Troubleshooting
+
+### Bot Not Starting
+
+**Error**: `EADDRINUSE: address already in use :::3001`
+```bash
+# Kill existing process
+lsof -ti:3001 | xargs kill -9
+systemctl --user restart zcode
+```
+
+**Error**: `Telegram bot token not configured`
+```bash
+# Check .env file
+cat .env | grep TELEGRAM_BOT_TOKEN
+# Should show: TELEGRAM_BOT_TOKEN=123456789:ABCdef...
+```
+
+### Voice I/O Not Working
+
+**Error**: `Vosk model not found`
+```bash
+# Check model path
+ls -la ~/vosk-models/vosk-model-small-0.15/
+# Should show: model.json, graphs, etc.
+
+# Update .env
+VOSK_MODEL_PATH=/home/uroma2/vosk-models/vosk-model-small-0.15
+```
+
+**Error**: `ffmpeg not found`
+```bash
+# Install ffmpeg
+sudo apt-get install -y ffmpeg
+
+# Verify
+ffmpeg -version
+```
+
+### Webhook Not Receiving Messages
+
+**Error**: `Webhook not set`
+```bash
+# Manually set webhook
+curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook?url=https://your-domain.com/telegram/webhook"
+
+# Check webhook info
+curl -X GET "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getWebhookInfo"
+```
+
+**Error**: `Connection timeout`
+```bash
+# Check firewall
+sudo ufw status
+# Should allow port 80 and 443
+
+# Check Nginx
+sudo nginx -t
+sudo systemctl status nginx
+```
+
+### Service Not Running
+
+**Error**: `Active: inactive (dead)`
+```bash
+# Check logs
+journalctl --user -u zcode -n 50 --no-pager
+
+# Restart service
+systemctl --user restart zcode
+
+# Check status
+systemctl --user status zcode
+```
+
+---
+
+## Advanced Setup
+
+### Docker Deployment (Coming Soon)
+
+```bash
+# Build image
+docker build -t zcode-cli-x .
+
+# Run container
+docker run -d \
+  --name zcode \
+  -v $(pwd)/.env:/app/.env \
+  -v $(pwd)/logs:/app/logs \
+  -p 3001:3001 \
+  zcode-cli-x
+```
+
+### Multiple Instances
+
+```bash
+# Copy service file with different name
+cp scripts/zcode.service ~/.config/systemd/user/zcode-2.service
+
+# Edit service file
+nano ~/.config/systemd/user/zcode-2.service
+# Change: ExecStart=/usr/bin/node /home/uroma2/zcode-cli-x/bin/zcode.js --no-cli
+# To: ExecStart=/usr/bin/node /home/uroma2/zcode-cli-x/bin/zcode.js --no-cli --instance 2
+
+# Enable and start
+systemctl --user enable zcode-2
+systemctl --user start zcode-2
+```
+
+### Custom Domain with SSL
+
+```bash
+# 1. Get domain DNS record
+# Add A record: your-domain.com -> YOUR_SERVER_IP
+
+# 2. Install Nginx
+sudo apt-get install -y nginx
+
+# 3. Configure Nginx
+sudo nano /etc/nginx/sites-available/zcode
+
+server {
+    listen 80;
+    server_name your-domain.com;
+
+    location /telegram/webhook {
+        proxy_pass http://localhost:3001;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    }
+}
+
+# 4. Enable site
+sudo ln -s /etc/nginx/sites-available/zcode /etc/nginx/sites-enabled/
+sudo nginx -t
+sudo systemctl restart nginx
+
+# 5. Get SSL certificate
+sudo certbot --nginx -d your-domain.com
+
+# 6. Set webhook
+curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook?url=https://your-domain.com/telegram/webhook"
+```
+
+---
+
+## Verification
+
+### Check All Components
+
+```bash
+# 1. Node.js version
+node --version  # Should show v20.x+
+
+# 2. npm version
+npm --version   # Should show 9.x+
+
+# 3. ffmpeg
+ffmpeg -version  # Should show version info
+
+# 4. Python & Vosk
+python3 --version  # Should show 3.8+
+python3 -c "import vosk; print(vosk.__version__)"  # Should print version
+
+# 5. Service status
+systemctl --user status zcode  # Should show: active (running)
+
+# 6. Webhook info
+curl -X GET "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getWebhookInfo"
+# Should show: {"ok":true,"url":"https://your-domain.com/telegram/webhook"}
+
+# 7. Test bot
+curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getMe"
+# Should show your bot info
+```
+
+### Run Smoke Tests
+
+```bash
+# Run Ruflo smoke tests
+node test-ruflo-smoke.mjs
+
+# Should show:
+# ✅ PluginSystem: 10/10
+# ✅ HookSystem: 4/4
+# ✅ AgentSystem: 9/9
+# ✅ SwarmCoordinator: 12/12
+# ✅ AgentOrchestrator: 4/4
+# ✅ MemoryBackend: 14/14
+# Total: 53/53
+```
+
+---
+
+## Next Steps
+
+1. ✅ **Test the bot** — Send `/start` in Telegram
+2. ✅ **Explore features** — Try `/tools`, `/agents`, `/memory`
+3. ✅ **Configure voice** — Set up Vosk model and ffmpeg
+4. ✅ **Customize** — Edit `.zcode.config.json` for your needs
+5. ✅ **Monitor** — Use `journalctl --user -u zcode -f` to watch logs
+
+---
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.rommark.dev/admin/zCode-CLI-X/issues)
+- **Discussions**: [GitHub Discussions](https://github.rommark.dev/admin/zCode-CLI-X/discussions)
+- **Documentation**: [README.md](./README.md), [ARCHITECTURE.md](./ARCHITECTURE.md)
+
+---
+
+<div align="center">
+
+**Ready to deploy?** Follow the steps above and your bot will be running in minutes! 🚀
+
+</div>