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/CREDITS.md
+++ b/CREDITS.md
@@ -0,0 +1,309 @@
+# Credits & Acknowledgments
+
+## 🏗️ Core Projects
+
+zCode CLI X is built on top of several open-source projects. We're deeply grateful to their authors and contributors.
+
+### [Hermes Agent](https://github.com/nousresearch/hermes-agent)
+**NousResearch's Telegram AI agent framework**
+
+- **Used for**: Telegram bot framework, stream consumer patterns, RTK integration
+- **Contributions**:
+  - `src/bot/message-sender.js` — Adapted from `gateway/stream_consumer.py`
+  - RTK (Rust Token Killer) integration for 60-90% token savings
+  - Message formatting and HTML escaping patterns
+  - Webhook handling with grammy
+
+**License**: MIT
+
+---
+
+### [Claude Code](https://github.com/anthropics/claude-code)
+**Anthropic's agentic coding CLI**
+
+- **Used for**: Unified agentic loop architecture, tool call accumulation, SSE streaming patterns
+- **Contributions**:
+  - `src/bot/index.js` — Intelligence Routing (stream + non-stream unified loop)
+  - Tool call accumulation from SSE deltas
+  - Max 10-turn safety net design
+  - Bash tool with security hooks (adapted from `BashTool.tsx`)
+  - Cron scheduler patterns (from `cronScheduler.ts`)
+
+**License**: Proprietary (Anthropic)
+
+---
+
+### [Ruflo](https://github.com/ruvnet/ruflo)
+**Multi-agent orchestration framework**
+
+- **Used for**: Plugin system, multi-agent swarm, hook architecture, enhanced memory backend
+- **Contributions**:
+  - `src/plugins/` — PluginManager, PluginLoader, BasePlugin, ExtensionPoints
+  - `src/agents/` — Agent, Task, SwarmCoordinator, AgentOrchestrator
+  - `src/bot/hooks.js` — Pre/post tool/AI/session hooks
+  - `src/bot/memory-backend.js` — JSONBackend with LRU, InMemoryBackend with TTL
+  - 9 agent roles (coder, tester, reviewer, architect, devops, security, researcher, designer, coordinator)
+  - 16 extension points for plugin system
+  - 3 swarm topologies (simple, hierarchical, swarm)
+
+**License**: MIT
+
+---
+
+### [Opencode](https://github.com/opencode/opencode)
+**Open-source AI coding assistant**
+
+- **Used for**: Bash automation patterns, file operations, safety hooks, tool architecture
+- **Contributions**:
+  - `src/tools/BashTool/` — Security hooks, destructive command protection
+  - File read/write patterns with heredoc fallback
+  - Git integration with permission validation
+  - Web scraping with cheerio
+
+**License**: MIT
+
+---
+
+## 🛠️ Technologies & Libraries
+
+### Core Frameworks
+
+- **[grammy](https://grammy.dev)** — Telegram Bot Framework for Node.js
+  - Webhook handling
+  - Bot API wrapper
+  - Middleware system
+  - **License**: MIT
+
+- **[Express](https://expressjs.com)** — Web application framework
+  - HTTP server for webhooks
+  - WebSocket server setup
+  - **License**: MIT
+
+- **[Winston](https://github.com/winstonjs/winston)** — Logging library
+  - Structured logging
+  - Multiple transports (console, file)
+  - Log levels (debug, info, warn, error)
+  - **License**: MIT
+
+### AI/ML Libraries
+
+- **[Z.AI API](https://z.ai)** — GLM-5.1 model provider
+  - Primary AI model for code generation
+  - Coding Plan subscription
+  - SSE streaming support
+  - **License**: Proprietary (Z.AI)
+
+- **[Vosk](https://alphacephei.com/vosk/)** — Offline speech recognition
+  - Voice-to-text (STT)
+  - 68MB model (~95% accuracy)
+  - CPU-based, no GPU needed
+  - **License**: Apache 2.0
+
+- **[node-edge-tts](https://github.com/yayuyokit/Edge-TTS-node)** — Text-to-speech
+  - Microsoft Edge voices
+  - Text-to-voice (TTS)
+  - No download required
+  - **License**: MIT
+
+### Utilities
+
+- **[axios](https://axios-http.com)** — HTTP client
+  - Z.AI API calls
+  - Webhook requests
+  - **License**: MIT
+
+- **[dotenv](https://github.com/motdotla/dotenv)** — Environment variable loader
+  - `.env` file parsing
+  - Configuration management
+  - **License**: BSD-2-Clause
+
+- **[chalk](https://github.com/chalk/chalk)** — Terminal string styling
+  - Colored CLI output
+  - **License**: MIT
+
+- **[commander](https://github.com/tj/commander.js)** — Node.js command-line framework
+  - CLI argument parsing
+  - Command structure
+  - **License**: MIT
+
+- **[ws](https://github.com/websockets/ws)** — WebSocket library
+  - Real-time communication
+  - SSE fallback
+  - **License**: MIT
+
+- **[p-queue](https://github.com/sindresorhus/p-queue)** — Priority queue
+  - Request queue management
+  - Per-chat sequential processing
+  - **License**: MIT
+
+- **[glob](https://github.com/isaacs/node-glob)** — File pattern matching
+  - File search
+  - Asset discovery
+  - **License**: ISC
+
+- **[cheerio](https://github.com/cheeriojs/cheerio)** — Fast HTML parser
+  - Web scraping
+  - Content extraction
+  - **License**: MIT
+
+- **[discord.js](https://discord.js.org)** — Discord API wrapper
+  - Discord integration (unused but included)
+  - **License**: Apache 2.0
+
+- **[openai](https://github.com/openai/openai-node)** — OpenAI API client
+  - OpenAI compatibility layer
+  - **License**: Apache 2.0
+
+- **[fs-extra](https://github.com/jprichardson/node-fs-extra)** — File system utilities
+  - File operations
+  - Directory management
+  - **License**: MIT
+
+- **[execa](https://github.com/sindresorhus/execa)** — Process execution
+  - Child process management
+  - Command execution
+  - **License**: MIT
+
+- **[@grammyjs/auto-retry](https://github.com/grammyjs/auto-retry)** — Automatic retry logic
+  - Bot API error handling
+  - Exponential backoff
+  - **License**: MIT
+
+- **[@grammyjs/runner](https://github.com/grammyjs/runner)** — Bot runner
+  - Webhook polling
+  - Error handling
+  - **License**: MIT
+
+---
+
+## 🎯 Special Thanks
+
+### NousResearch
+The Hermes Agent team for creating an excellent Telegram bot framework and sharing patterns for:
+- Stream consumer architecture
+- RTK integration
+- Message formatting
+- Webhook handling
+
+We're grateful for their open-source contributions that made zCode's Telegram integration possible.
+
+### Anthropic
+The Claude Code team for pioneering the agentic coding CLI paradigm. Their work on:
+- Unified agentic loops
+- Tool call accumulation
+- SSE streaming patterns
+
+Influenced zCode's core architecture significantly.
+
+### RuvNet
+The Ruflo team for their innovative multi-agent orchestration system. Their plugin architecture, hook system, and swarm coordination patterns became the foundation for zCode's extensibility.
+
+### Community Contributors
+- All GitHub issue reporters who helped identify bugs
+- Pull request contributors who improved the codebase
+- Telegram users who provided feedback and feature requests
+- Twitter/X community members who shared use cases
+
+---
+
+## 📜 License
+
+zCode CLI X is released under the **MIT License**.
+
+This means you're free to:
+- Use zCode for personal or commercial projects
+- Modify the source code
+- Distribute copies
+- Use in proprietary software
+
+**Conditions**:
+- Include original copyright notice
+- Include MIT license text
+- No warranty provided
+
+See [LICENSE](./LICENSE) for full license text.
+
+---
+
+## 🙏 Third-Party Licenses
+
+### Open Source Components
+
+This project includes or depends on the following open-source software:
+
+| Component | License |
+|-----------|---------|
+| grammy | MIT |
+| @grammyjs/auto-retry | MIT |
+| @grammyjs/runner | MIT |
+| axios | MIT |
+| chalk | MIT |
+| cheerio | MIT |
+| commander | MIT |
+| discord.js | Apache 2.0 |
+| dotenv | BSD-2-Clause |
+| execa | MIT |
+| express | MIT |
+| fs-extra | MIT |
+| glob | ISC |
+| node-edge-tts | MIT |
+| openai | Apache 2.0 |
+| p-queue | MIT |
+| winston | MIT |
+| ws | MIT |
+| Vosk | Apache 2.0 |
+
+All licenses are permissive (MIT, BSD, Apache, ISC) and compatible with commercial use.
+
+---
+
+## 🌟 Contributors
+
+### Core Team
+- **Roman** (@uroma2) — Author, maintainer, primary developer
+  - Architecture design
+  - Implementation
+  - Integration of Hermes, Claude, Ruflo, Opencode
+
+### External Contributors
+- [List contributors here as they join]
+- [Add PR numbers and contributions]
+
+**Want to contribute?** See [CONTRIBUTING.md](./CONTRIBUTING.md)
+
+---
+
+## 📊 Attribution
+
+When using or referencing zCode CLI X in your work:
+
+```bibtex
+@software{zcode2026,
+  author = {Roman},
+  title = {zCode CLI X: The Ultimate Agentic Coding Assistant},
+  year = {2026},
+  url = {https://github.rommark.dev/admin/zCode-CLI-X},
+  license = {MIT}
+}
+```
+
+**Citation format**:
+> Roman. "zCode CLI X: The Ultimate Agentic Coding Assistant." GitHub, 2026. https://github.rommark.dev/admin/zCode-CLI-X
+
+---
+
+## 🔗 Links
+
+- **Project**: [github.rommark.dev/admin/zCode-CLI-X](https://github.rommark.dev/admin/zCode-CLI-X)
+- **Issues**: [Report bugs](https://github.rommark.dev/admin/zCode-CLI-X/issues)
+- **Discussions**: [Feature requests](https://github.rommark.dev/admin/zCode-CLI-X/discussions)
+- **Documentation**: [README.md](./README.md), [ARCHITECTURE.md](./ARCHITECTURE.md)
+
+---
+
+<div align="center">
+
+**Built with ❤️ using open-source software**  
+*Special thanks to all the projects and contributors listed above*
+
+</div>