Document project structure and development guidelines

AGENTS.md

@@ -0,0 +1,39 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+This repository contains a Python Telegram bot. `bot.py` is the entry point and registers command, text, photo, image-document, and inline handlers. `handlers/` contains Telegram-facing command and update handlers, grouped by feature (`admin.py`, `chat.py`, `inline.py`, `help.py`). `services/` contains external integrations and shared business logic such as AI calls, auth persistence, and saved runtime settings. `utils/` contains reusable helpers for context, formatting, chunking, and Persian-language handling. Runtime state and credentials live in `.env`, `settings.json`, `authorized_users.json`, and `*.session` files; do not treat these as source assets.
+
+## Build, Test, and Development Commands
+
+Create an isolated environment before installing dependencies:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+Run the bot locally with:
+
+```bash
+python bot.py
+```
+
+Use `.env.example` as the template for required environment variables, then set `TELEGRAM_TOKEN`, `GOOGLE_API_KEY`, and `OWNER_ID` in `.env`. Runtime choices such as active provider, model, public mode, system prompt, and per-user settings are saved in `settings.json`.
+
+## Coding Style & Naming Conventions
+
+Follow idiomatic Python with 4-space indentation, clear function names, and small modules organized by responsibility. Handler functions use the `cmd_<command>` pattern for commands, such as `cmd_ping` or `cmd_setmodel`; keep new command names consistent with the registered Telegram command. Prefer async functions for Telegram callbacks and service calls. Keep configuration values centralized in `config.py` rather than scattering `os.getenv` calls.
+
+## Testing Guidelines
+
+No test suite is currently present. For new behavior, add focused `pytest` tests under a future `tests/` directory and name files `test_<module>.py`. Prioritize pure helpers in `utils/` and service logic that can be tested without Telegram network access. Until tests exist, validate changes by running `python bot.py` with a development bot token and exercising the affected command or message path.
+
+## Commit & Pull Request Guidelines
+
+The local `.git` directory has no usable history, so no existing commit convention is available. Use concise imperative commit messages, for example `Add image OCR command` or `Fix auth file reload handling`. Pull requests should include a short summary, configuration changes, manual test steps, and screenshots or chat transcripts when user-visible Telegram behavior changes.
+
+## Security & Configuration Tips
+
+Never commit `.env`, session files, API keys, bot tokens, or real user authorization data. Keep `.env.example` updated when adding configuration. Treat `authorized_users.json` as local runtime state unless a sanitized fixture is intentionally needed for tests.