From 71eb46915474760cdd9c97cc812a9ab3432952ae Mon Sep 17 00:00:00 2001
From: arsam <me@asabbagh.com>
Date: Fri, 18 Sep 2026 23:14:00 +0330
Subject: [PATCH] Import documentation: v3/Tele2Rub/AGENTS.md

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

diff --git a/v3/Tele2Rub/AGENTS.md b/v3/Tele2Rub/AGENTS.md
new file mode 100644
index 0000000..6621bb5
--- /dev/null
+++ b/v3/Tele2Rub/AGENTS.md
@@ -0,0 +1,63 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+This repository is a small Python service that bridges Telegram bot uploads to Rubika Saved Messages. Core code lives at the repository root:
+
+- `main.py` starts both worker processes.
+- `telebot.py` handles Telegram bot input, downloads, queue updates, and user commands.
+- `rub.py` consumes queued tasks and uploads files to Rubika.
+- `requirements.txt` lists runtime dependencies.
+- `.env.example` documents required configuration keys.
+
+Runtime state is written to `downloads/`, `queue/`, `*.session`, `*.session-journal`, `rubsession.rp`, and `out.log`. Treat these as local artifacts; do not commit real sessions, downloaded files, logs, or secrets.
+
+## Build, Test, and Development Commands
+
+Create and activate a virtual environment:
+
+```bash
+python3 -m venv venv
+source venv/bin/activate
+```
+
+Install dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+Create local configuration:
+
+```bash
+cp .env.example .env
+```
+
+Run both Telegram and Rubika processes:
+
+```bash
+python3 main.py
+```
+
+Run individual components while debugging:
+
+```bash
+python3 telebot.py
+python3 rub.py
+```
+
+## Coding Style & Naming Conventions
+
+Use Python 3.10+ style. Follow the existing module pattern: constants in `UPPER_SNAKE_CASE`, functions and variables in `snake_case`, and classes in `PascalCase`. Keep paths based on `Path(__file__).resolve().parent` so scripts work from any current directory. Prefer JSONL queue records and UTF-8 file I/O, matching the current `queue/*.jsonl` format. Keep user-facing Persian status text readable and avoid changing message wording unless behavior changes require it.
+
+## Testing Guidelines
+
+There is currently no formal test suite. Before submitting changes, run the affected entry point locally with a disposable `.env` and verify the relevant queue flow. For queue logic, test with small files first, then direct URLs or larger files if upload behavior changed. If adding tests, place them under `tests/`, name files `test_*.py`, and prefer `pytest` for isolated helpers such as `safe_filename`, queue parsing, and retry decisions.
+
+## Commit & Pull Request Guidelines
+
+Recent history uses short imperative messages such as `Update README.md` and `fix disconnect session client when uploading`. Keep commits concise and focused, for example `fix empty caption handling` or `update queue cleanup`. Pull requests should include a short summary, manual test steps, affected commands, and any configuration or session implications. Include screenshots only when Telegram or Rubika message output changes.
+
+## Security & Configuration Tips
+
+Never commit `.env`, session files, downloaded media, or queue state containing user data. Required environment keys are `API_ID`, `API_HASH`, `BOT_TOKEN`, and `RUBIKA_SESSION`. Use `.env.example` for placeholders only.