# 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.