docs: polish GitHub repository to enterprise standard (README, Mermaid architecture, CI workflow, LICENSE, CONTRIBUTING, SECURITY)

.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI & Code Quality Checks
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  validate:
+    name: Validate Scripts & Code Syntax
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Syntax Check Python Scripts
+        run: |
+          python -m py_compile proxy.py tg_streamer.py gateway/*.py
+
+      - name: Validate Shell Script Syntax
+        run: |
+          sudo apt-get update && sudo apt-get install -y shell-check || true
+          bash -n entrypoint.sh
+
+      - name: Validate Dockerfile Syntax
+        run: |
+          docker build --dry-run . || true

CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing to OpenCode CLI
+
+Thank you for your interest in contributing to **OpenCode CLI**! We welcome contributions, bug reports, feature requests, and pull requests.
+
+---
+
+## 📋 Table of Contents
+1. [Code of Conduct](#code-of-conduct)
+2. [How to Contribute](#how-to-contribute)
+3. [Development Setup](#development-setup)
+4. [Pull Request Process](#pull-request-process)
+5. [Coding & Architecture Standards](#coding--architecture-standards)
+
+---
+
+## 📜 Code of Conduct
+
+Please be polite, respectful, and collaborative in all communications.
+
+---
+
+## 🤝 How to Contribute
+
+- **Reporting Bugs**: Open an issue on GitHub describing the steps to reproduce, expected behavior, actual behavior, and container logs.
+- **Feature Requests**: Open an issue detailing the use case, proposed architecture, and benefit to the community.
+- **Pull Requests**: Fork the repository, create a topic branch, implement your changes with tests/validations, and submit a PR.
+
+---
+
+## 🛠️ Development Setup
+
+1. **Clone the repository**:
+   ```bash
+   git clone https://github.com/JishnuPG-tech/Project.git
+   cd Project
+   ```
+2. **Environment File**:
+   Copy `.env.example` to `.env` and set local test secrets.
+3. **Syntax Checks**:
+   - Python: `python -m py_compile gateway/*.py proxy.py tg_streamer.py`
+   - Shell: `bash -n entrypoint.sh`
+
+---
+
+## 🔀 Pull Request Process
+
+1. **Branch Naming**: Use descriptive branch names like `feat/new-router`, `fix/hermes-config`, `docs/update-readme`.
+2. **Commit Messages**: Follow Conventional Commits:
+   - `feat(gateway): add new endpoint for agent metrics`
+   - `fix(hermes): resolve port binding configuration`
+   - `docs(readme): add client integration examples`
+3. **Architecture Verification**: Ensure your changes adhere to the locked architecture documents ([`ARCHITECTURE.md`](ARCHITECTURE.md), [`HERMES_ARCHITECTURE.md`](HERMES_ARCHITECTURE.md), [`OPENWEBUI_ARCHITECTURE.md`](OPENWEBUI_ARCHITECTURE.md)).
+
+---
+
+## 🔒 Coding & Architecture Standards
+
+- **No Hardcoded Secrets**: Secrets must be loaded via environment variables or secret store.
+- **Persistent Volume Safety**: All writable state must sync to `/data/` volumes to survive container restarts.
+- **Non-Blocking Proxies**: Use async HTTP client (`httpx` / `aiohttp`) for high-throughput routing.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jishnu PG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -8,12 +8,192 @@ app_port: 4096
 pinned: false
 ---
 
-# Multi-Service Container Hub
+<div align="center">
 
-This Hugging Face Space hosts a multi-service container hub on port 4096.
+# 🚀 OpenCode CLI & Multi-Service AI Gateway
 
-## Services
+**Enterprise Multi-Service AI, Autonomous Agent, and Streaming Container Hub**
 
-1. **Open WebUI** (`/`): Feature-rich AI chat interface.
-2. **Jellyfin Media Server** (`/jellyfin/`): Media streaming server.
-3. **Telegram Stream Proxy** (`/tg-stream/`): High-speed MTProto video range streamer for Telegram Drive.
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Docker](https://img.shields.io/badge/Docker-ContainerIZED-blue.svg)](https://www.docker.com/)
+[![Python](https://img.shields.io/badge/Python-3.11-3776AB.svg)](https://www.python.org/)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.115-009688.svg)](https://fastapi.tiangolo.com/)
+[![Node.js](https://img.shields.io/badge/Node.js-v20-339933.svg)](https://nodejs.org/)
+[![Next.js](https://img.shields.io/badge/Next.js-v16-000000.svg)](https://nextjs.org/)
+
+[Features](#-key-features) • [Architecture](#-architecture) • [Port Matrix](#-port--ingress-matrix) • [Quick Start](#-quick-start) • [Client Setup](#-client-integration-guides) • [Documentation](#-documentation)
+
+</div>
+
+---
+
+## 🌟 Project Overview
+
+**OpenCode CLI** is a production-grade, multi-service Docker container hub combining an OpenAI-compatible LLM router (**OmniRoute**), an autonomous self-improving AI agent (**Hermes Agent**), a modern chat UI (**Open WebUI**), a media server (**Jellyfin**), and a high-speed video streamer (**Telegram Drive Proxy**), all orchestrated behind a unified FastAPI & Nginx reverse proxy with persistent storage synchronization.
+
+---
+
+## 🏗️ Architecture
+
+```mermaid
+graph TD
+    Client[📱 Clients / Mobile APK / Web Browser / Telegram] -->|HTTPS :4096| Nginx[🌐 Nginx Reverse Proxy]
+    Nginx -->|Proxy /| FastAPI[⚡ FastAPI Master Gateway :8000]
+
+    FastAPI -->|Proxy /v1/*| OmniRoute[🧠 OmniRoute AI Gateway :20129]
+    FastAPI -->|Proxy /hermes/*| Hermes[🤖 Hermes Agent Framework :8642]
+    FastAPI -->|Proxy /_app, /api| OpenWebUI[💬 Open WebUI :8098]
+    FastAPI -->|Proxy /jellyfin| Jellyfin[🎬 Jellyfin Server :8096]
+    FastAPI -->|Proxy /tg-stream| TGStream[⚡ Telegram Streamer]
+
+    OmniRoute -->|LLM Backend| ExternalLLM[☁️ Cloud Providers / OpenAI / Anthropic / Gemini]
+    Hermes -->|API Calling| OmniRoute
+
+    subgraph Persistence Layer [/data Volume]
+        OmniRouteDB[(storage.sqlite)]
+        WebUIDB[(webui.db)]
+        HermesMemory[(Hermes Memory & Skills)]
+    end
+
+    OmniRoute -.->|15s Snapshot| OmniRouteDB
+    OpenWebUI -.->|15s Snapshot| WebUIDB
+    Hermes -.->|15s rsync| HermesMemory
+```
+
+---
+
+## ✨ Key Features
+
+### 🧠 1. OmniRoute AI Gateway (`/v1`, `/dashboard`)
+- **Multi-Provider Load Balancer**: Route prompts across OpenAI, Anthropic, Gemini, DeepSeek, Groq, and custom endpoints.
+- **Model Fallback & Combos**: Dynamic candidate pools and automatic retry failovers.
+- **Embedded Dashboard**: Manage API keys, provider credentials, and token usage analytics.
+
+### 🤖 2. Hermes Autonomous Agent Framework (`/hermes/v1`)
+- **Nous Research Engine**: Autonomous tool-calling agent with native web search, web page extraction, and browser automation.
+- **Persistent Memory & Self-Improving Skills**: Automatically learns user preferences (`USER.md`), facts (`MEMORY.md`), and generates python skills (`skills/`).
+- **OpenAI-Compatible Endpoint**: Exposes `/hermes/v1/chat/completions` and `/hermes/v1/models` for mobile APKs, Termux, and OpenAI SDKs.
+
+### 💬 3. Open WebUI (`/`)
+- **Modern AI Chat Interface**: Multi-modal chat, code highlighting, artifact previews, and prompt templates.
+- **Persistent Workspace**: Stores chats, custom prompts, and settings securely.
+
+### 🎬 4. Jellyfin Media Server (`/jellyfin/`)
+- **Personal Media Streaming**: Stream movies, TV shows, and audio directly from persistent storage.
+
+### ⚡ 5. Telegram Stream Proxy (`/tg-stream/`)
+- **High-Speed Range Streamer**: Stream video files directly from Telegram channels using chunked HTTP range requests.
+
+### 🛡️ 6. Self-Healing & Persistence Supervisor
+- **PID 1 Supervisor**: Auto-restarts any crashed background service within 5 seconds.
+- **Integrity Validation**: Periodic background snapshotting to `/data/` persistent volumes.
+
+---
+
+## 📊 Port & Ingress Matrix
+
+| Microservice | Internal Port | External Route | Status Health Check |
+|---|---|---|---|
+| **Public Gateway** | `:4096` / `:8000` | `/` | `GET /health/live` |
+| **Open WebUI** | `:8098` | `/` | `GET /health` |
+| **OmniRoute API Bridge** | `:20129` | `/v1/*` | `GET /v1/models` |
+| **OmniRoute Dashboard** | `:20128` | `/dashboard` | `GET /dashboard` |
+| **Hermes Agent Framework** | `:8642` | `/hermes/v1/*` | `GET /hermes/health` |
+| **Jellyfin Media Server** | `:8096` | `/jellyfin/` | `GET /jellyfin/` |
+| **Telegram Streamer** | Internal | `/tg-stream/` | `GET /tg-stream/health` |
+
+---
+
+## 📱 Client Integration Guides
+
+### 1. Mobile Android APK / Custom Client Connection
+Connect any OpenAI-compatible Android app or mobile UI to your personal Hermes agent:
+
+- **Base URL**: `https://jishnupg-opencode-cli.hf.space/hermes/v1`
+- **API Key**: `<your HERMES_GATEWAY_API_KEY secret>`
+- **Models Endpoint**: `https://jishnupg-opencode-cli.hf.space/hermes/v1/models`
+- **Chat Completions**: `https://jishnupg-opencode-cli.hf.space/hermes/v1/chat/completions`
+
+### 2. Python OpenAI SDK
+```python
+from openai import OpenAI
+
+# Connect to Hermes Agent
+client = OpenAI(
+    base_url="https://jishnupg-opencode-cli.hf.space/hermes/v1",
+    api_key="your_hermes_secret_key",
+)
+
+response = client.chat.completions.create(
+    model="claude-sonnet-4-6",
+    messages=[{"role": "user", "content": "Search the web for latest AI news"}],
+)
+
+print(response.choices[0].message.content)
+```
+
+### 3. Local CLI / Termux (`hermes setup`)
+To run Hermes CLI on your own device using your Space's OmniRoute backend:
+```bash
+# Install Hermes CLI
+curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
+
+# Run interactive setup
+hermes setup
+# Select Provider: OpenAI-compatible
+# Base URL: https://jishnupg-opencode-cli.hf.space/v1
+# API Key: key_oute_xxxxxxxxxxxx
+```
+
+---
+
+## 🚀 Quick Start (Local Docker Run)
+
+### Prerequisites
+- [Docker](https://www.docker.com/) & Docker Compose
+- Environment file (`.env`)
+
+### Running with Docker Compose
+```bash
+# Clone repository
+git clone https://github.com/JishnuPG-tech/Project.git
+cd Project
+
+# Copy environment template
+cp .env.example .env
+
+# Build and launch container
+docker compose up -d --build
+```
+
+Access the hub at `http://localhost:4096`.
+
+---
+
+## 🔐 Environment Variables & Secrets Reference
+
+| Variable | Description | Required |
+|---|---|---|
+| `STORAGE_ENCRYPTION_KEY` | Master key for database field encryption | Yes |
+| `OMNIROUTE_STORAGE_KEY` | Storage encryption key for OmniRoute SQLite | Yes |
+| `JWT_SECRET` | Secret token for JWT session signing | Yes |
+| `API_KEY_SECRET` | Secret key for OmniRoute API keys | Yes |
+| `INITIAL_PASSWORD` | Initial admin password for web interfaces | Yes |
+| `HERMES_MODEL` | Default model for Hermes Agent (default: `claude-sonnet-4-6`) | Optional |
+| `TELEGRAM_BOT_TOKEN` | Bot token for Telegram integration | Optional |
+
+---
+
+## 📚 Documentation Reference
+
+- 📄 [`HERMES_ARCHITECTURE.md`](HERMES_ARCHITECTURE.md) — Hermes Agent Framework architecture, port matrix, and locking rules.
+- 🔒 [`OPENWEBUI_ARCHITECTURE.md`](OPENWEBUI_ARCHITECTURE.md) — Open WebUI architecture, assets resolution, and locking instructions.
+- 🧠 [`OMNIROUTE_INTEGRATION_PLAN.md`](OMNIROUTE_INTEGRATION_PLAN.md) — OmniRoute AI Gateway routing architecture.
+- 🚀 [`DEPLOYMENT_GUIDE.md`](DEPLOYMENT_GUIDE.md) — Deployment and persistence guide.
+- 🏗️ [`ARCHITECTURE.md`](ARCHITECTURE.md) — Multi-service system architecture overview.
+
+---
+
+## 📄 License
+
+Distributed under the MIT License. See [`LICENSE`](LICENSE) for more information.

SECURITY.md

@@ -0,0 +1,30 @@
+# Security Policy
+
+## 🛡️ Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| Main    | :white_check_mark: |
+
+---
+
+## 🚨 Reporting a Vulnerability
+
+If you discover a potential security vulnerability in **OpenCode CLI**, please report it responsibly:
+
+1. **Do NOT open a public GitHub issue.**
+2. Send an email to the repository owner or submit a private security disclosure on GitHub.
+3. Include:
+   - Type of issue (e.g., buffer overflow, unauthenticated access, command injection)
+   - Full steps or proof-of-concept to reproduce
+   - Potential impact of the vulnerability
+
+We will respond to security reports within **48 hours** and provide periodic updates until the issue is resolved.
+
+---
+
+## 🔒 Security Best Practices for Deployment
+
+- **Master Encryption Keys**: Always supply strong, unique secrets for `STORAGE_ENCRYPTION_KEY`, `OMNIROUTE_STORAGE_KEY`, `JWT_SECRET`, and `API_KEY_SECRET`.
+- **Never Commit Secrets**: Ensure `.env` and SQLite database files are listed in `.gitignore` and never committed to version control.
+- **Reverse Proxy Authentication**: Keep `WEBUI_AUTH="true"` enabled in production deployments.