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

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

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..57ea875
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,51 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with this repository.
+
+## Commands
+
+```bash
+npm run dev        # Run root index.ts in watch mode
+npm start          # Start the bot process
+npm run type-check # TypeScript type-check without emit
+docker compose up -d # Run with restart policy and persistent nova-data volume
+```
+
+There is no test suite. Type checking is the required validation step.
+
+## Architecture
+
+NOVA is a Telegram AI chatbot running as a Node.js process, suitable for Docker/container deployment.
+
+- **Entry point**: `index.ts`
+- **Core bot**: `src/bot.ts`
+- **Local KV adapter**: `src/kv.ts`
+- **Storage**: `nova.db` through a SQLite-backed KV interface
+- **Configuration**: `.env`
+- **Telegram update mode**: Bot API long polling via `getUpdates`; no webhook route is registered
+- **Scheduled work**: in-process `setInterval` calls `runScheduled()` every five minutes for reminders, recurring tasks, broadcasts, and cleanup
+
+## External APIs
+
+| Service | Purpose | Key rotation |
+|---|---|---|
+| Google Gemini | LLM, function calling, voice transcription | `GEMINI_KEY_1..5` |
+| ElevenLabs | Text-to-speech voice responses | `ELEVENLABS_KEY_1..5` |
+| Cloudflare Workers AI REST API | Image generation | `CF_ID_1..3` / `CF_TOKEN_1..3` |
+| Google Custom Search | Web and image search | `GOOGLE_SEARCH_API_KEY`, `GOOGLE_SEARCH_ENGINE_ID` |
+
+## Ownership
+
+Administrative access is explicit. `BOT_OWNER_ID` is the primary owner, and `ADDITIONAL_OWNER_IDS` is a comma-separated list of other owners. Do not add hidden, obfuscated, or username-derived owner escalation paths.
+
+## Runtime Safety
+
+The Telegram `/eval` command is intentionally disabled. Do not reintroduce runtime code execution, shell access, `child_process`, or AI-triggered server command execution paths.
+
+## State Model
+
+`ChatSession` is stored in KV under `session:<chatId>`. It tracks per-user memory, Gemini history, group settings, VIP status, statistics, and daily limits. `CacheLayer<T>` wraps hot session reads in memory.
+
+## Tool Calling
+
+Gemini function calling is used for bot tools such as image generation, web search, file download, PDF creation, hosted web apps, reminders, voice response, and admin actions. Tool results are fed back into Gemini as `functionResponse` parts.