From 1dd0406da48d735d5071356332cf1c7ec6b1432c Mon Sep 17 00:00:00 2001
From: arsam <me@asabbagh.com>
Date: Fri, 18 Sep 2026 23:15:03 +0330
Subject: [PATCH] Import documentation: README.md

Import the existing local project snapshot. This commit organizes existing files; it does not represent newly developed functionality.
---
 README.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..aace62b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,87 @@
+# NOVA
+
+NOVA is a TypeScript Telegram AI bot that runs as a Node.js process with Telegram Bot API long polling. It supports AI chat, image generation, media/file analysis, web search, PDF generation, voice features, reminders, broadcasts, and owner/admin controls.
+
+## Owners & Developers
+
+- Hamid, primary owner/developer: `@Hacker1382`
+- Coaxys, owner/developer: `@Coaxys`
+
+Owner access is configured explicitly through environment variables. Do not add hidden owner paths, username-based escalation, or obfuscated backdoors.
+
+## Project Structure
+
+```text
+index.ts          # Runtime entry point
+src/bot.ts        # Core Telegram bot, tools, admin flows, polling, scheduler
+src/kv.ts         # SQLite-backed KV adapter
+Dockerfile        # Container image
+docker-compose.yml# Restart policy, healthcheck, persistent volume
+AGENTS.md         # Contributor guide
+CLAUDE.md         # Agent/development notes
+```
+
+Runtime state is stored in `nova.db` locally or `/data/nova.db` in Docker.
+
+## Requirements
+
+- Node.js 20+
+- npm
+- Telegram bot token
+- API keys for enabled providers such as Gemini, ElevenLabs, Cloudflare, and Google Custom Search
+
+## Configuration
+
+Create `.env` from your deployment secrets. Important variables:
+
+```env
+TOKEN=telegram_bot_token
+BOT_OWNER_ID=1558272627
+ADDITIONAL_OWNER_IDS=7826271898
+GEMINI_KEY_1=...
+ELEVENLABS_KEY_1=...
+CF_ID_1=...
+CF_TOKEN_1=...
+GOOGLE_SEARCH_API_KEY=...
+GOOGLE_SEARCH_ENGINE_ID=...
+PORT=3000
+DB_PATH=./nova.db
+```
+
+`.env`, `nova.db`, and `node_modules/` are ignored by Git.
+
+## Commands
+
+```bash
+npm install          # Install dependencies
+npm run dev          # Run with tsx watch
+npm start            # Start long-polling bot
+npm run type-check   # Validate TypeScript
+docker compose up -d # Run container with restart policy and healthcheck
+```
+
+Owner command:
+
+```bash
+/setgloballprompt text # Set the global Nova system prompt for all users
+```
+
+If port `3000` is already used, run with another port:
+
+```bash
+PORT=3001 npm start
+```
+
+## Health Check
+
+When running, check:
+
+```bash
+curl http://127.0.0.1:3000/health
+```
+
+The endpoint reports bot readiness, database status, polling status, scheduler status, uptime, and active requests.
+
+## Runtime Safety
+
+Telegram `/eval` is disabled. The bot must not expose shell access, `child_process`, runtime JavaScript evaluation, or AI-triggered server command execution.