From d30e1c6573f96e4f6cc57e2b043a9fd44dedbcff Mon Sep 17 00:00:00 2001
From: MoltBot Service <moltbot@moltbot.tailf7372d.ts.net>
Date: Sat, 14 Feb 2026 06:43:57 +0000
Subject: [PATCH] add README.md for Gitea repo page

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 README.md | 130 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 130 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2f5cd0d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,130 @@
+# Echo Core
+
+AI-powered personal assistant bot with Discord, Telegram, and WhatsApp bridges. Uses Claude Code CLI for conversation, with persistent sessions, cron scheduling, semantic memory search, and heartbeat monitoring.
+
+## Quick Start
+
+```bash
+# Interactive setup wizard (recommended for first install)
+bash setup.sh
+```
+
+The wizard handles prerequisites, virtual environment, bridge tokens, config, and systemd services in 10 guided steps.
+
+### Manual Setup
+
+```bash
+# 1. Create venv and install dependencies
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+
+# 2. Store Discord token in keyring
+./cli.py secrets set discord_token
+
+# 3. Edit config.json (bot name, owner ID, channels)
+
+# 4. Start
+systemctl --user start echo-core
+```
+
+## Architecture
+
+```
+                    ┌─────────────┐
+                    │  Claude CLI  │
+                    └──────┬──────┘
+                           │
+                    ┌──────┴──────┐
+                    │   Router    │
+                    └──────┬──────┘
+              ┌────────────┼────────────┐
+              │            │            │
+        ┌─────┴─────┐ ┌───┴───┐ ┌──────┴──────┐
+        │  Discord   │ │Telegram│ │  WhatsApp   │
+        │  (d.py)    │ │(ptb)   │ │(Baileys+py) │
+        └────────────┘ └────────┘ └─────────────┘
+```
+
+- **Discord**: slash commands via discord.py
+- **Telegram**: commands + inline keyboards via python-telegram-bot
+- **WhatsApp**: Node.js Baileys bridge + Python polling adapter
+- All three run concurrently in the same asyncio event loop
+
+## Key Components
+
+| Component | Description |
+|-----------|-------------|
+| `src/main.py` | Entry point — starts all adapters + scheduler + heartbeat |
+| `src/router.py` | Routes messages to Claude or handles commands |
+| `src/claude_session.py` | Claude Code CLI wrapper with `--resume` sessions |
+| `src/credential_store.py` | Keyring-based secrets manager |
+| `src/scheduler.py` | APScheduler cron jobs |
+| `src/heartbeat.py` | Periodic health checks |
+| `src/memory_search.py` | Ollama embeddings + SQLite semantic search |
+| `cli.py` | CLI tool — status, doctor, logs, secrets, cron, etc. |
+| `setup.sh` | Interactive 10-step setup wizard |
+| `bridge/whatsapp/` | Node.js WhatsApp bridge (Baileys + Express) |
+
+## CLI Usage
+
+```bash
+./cli.py status              # Bot online/offline, uptime
+./cli.py doctor              # Full diagnostic check
+./cli.py logs                # Tail echo-core.log
+./cli.py restart             # Restart the service
+./cli.py secrets list        # Show stored credentials
+./cli.py cron list           # Show scheduled jobs
+./cli.py whatsapp status     # WhatsApp bridge connection
+```
+
+## Configuration
+
+`config.json` — runtime configuration:
+
+```json
+{
+  "bot": {
+    "name": "Echo",
+    "default_model": "opus",
+    "owner": "DISCORD_USER_ID",
+    "admins": ["TELEGRAM_USER_ID"]
+  },
+  "channels": { },
+  "telegram_channels": { },
+  "whatsapp": {
+    "enabled": true,
+    "bridge_url": "http://127.0.0.1:8098",
+    "owner": "PHONE_NUMBER"
+  },
+  "whatsapp_channels": { }
+}
+```
+
+Secrets (Discord/Telegram tokens) are stored in the system keyring, not in config files.
+
+## Services
+
+Echo Core runs as systemd user services:
+
+```bash
+systemctl --user start echo-core              # Start bot
+systemctl --user start echo-whatsapp-bridge   # Start WA bridge
+systemctl --user status echo-core             # Check status
+journalctl --user -u echo-core -f             # Follow logs
+```
+
+## Requirements
+
+- Python 3.12+
+- Claude Code CLI
+- Node.js 22+ (only for WhatsApp bridge)
+
+## Tests
+
+```bash
+source .venv/bin/activate
+pytest tests/
+```
+
+440 tests, zero failures.