docs: add project documentation

Add comprehensive documentation for the Thon project, including project overview, architecture, usage examples, and development conventions. Update the README.md file to provide clear installation instructions, usage examples, and project structure. Remove the unused CLI entry point from pyproject.toml.

GEMINI.md

@@ -0,0 +1,59 @@
+# GEMINI.md - Project Context: Thon
+
+## Project Overview
+**Thon** is a Python library for converting and processing Telegram sessions. It is designed to be integrated into other projects as a dependency. It leverages `telethon` to handle `.session` files, converting them into a structured JSON format and providing an asynchronous framework for automated session management.
+
+### Main Technologies
+- **Python 3.10+**
+- **Telethon**: Core library for Telegram interaction.
+- **aiofiles**: Asynchronous file operations.
+- **asyncio**: Powers the asynchronous iterator and processing logic.
+- **Setuptools**: Build system for packaging.
+
+---
+
+## Architecture and Key Modules
+- **`thon.Thon`**: The main class and asynchronous iterator. Orchestrates the flow from raw session files to an active, authorized client.
+- **`thon.converter.Converter`**: Internal module that transforms raw `.session` files into JSON metadata files (containing `string_session` and proxy info).
+- **`thon.process.ProcessThon`**: A context manager that wraps a `telethon.TelegramClient`. It handles connection, authorization checks, and provides high-level methods like `search_code`.
+- **`thon.models`**: Organized data structures:
+    - `ThonOptions`: Configuration for retries, timeouts, and checks.
+    - `ThonSession`: The object yielded by the iterator, containing both metadata and the processing instance.
+- **`thon.utils`**: Shared utilities for JSON I/O, regex extraction, and file system management.
+
+---
+
+## Usage and Integration
+### Installation
+Install as a library:
+```bash
+pip install git+https://github.com/your-username/thon.git
+```
+
+### Core Pattern
+The library is designed around the `async for` pattern:
+```python
+from thon import Thon
+from thon.models.options import ThonOptions
+
+async def run():
+    options = ThonOptions(retries=5)
+    async for ts in Thon(options, sessions_folder=Path("path/to/sessions")):
+        async with ts.thon as client:
+            # client is an authorized Telethon instance
+            pass
+```
+
+---
+
+## Development Conventions
+- **Asynchronous Flow**: All I/O and network calls must be `async`.
+- **Session Management**: Automatically handles "banned" status by moving files if configured.
+- **Proxy Support**: Integrated into the connection logic via `thon.proxy`.
+- **Zero CLI**: The project does not provide a CLI entry point by design.
+
+---
+
+## Important Notes
+- The library uses a hardcoded `api_id` and `api_hash` in `Converter` for internal session string generation, but allows external apps to use their own via session data.
+- Banned sessions are moved to a `banned` subfolder relative to the sessions directory by default.

README.md

@@ -0,0 +1,110 @@
+# Thon ⚡️
+
+**Thon** is a lightweight, extensible Python library designed for processing Telegram sessions. It provides a clean, asynchronous interface to handle session conversion and automated processing tasks.
+
+---
+
+## 📥 Installation
+
+Install the library directly from the repository:
+
+```bash
+pip install git+https://github.com/your-username/thon.git
+```
+
+---
+
+## 🛠 Usage Examples
+
+### 1. Basic Session Iteration
+Iterate through your `.session` files automatically. Thon converts them on the fly and provides an authorized `telethon` client for each.
+
+```python
+import asyncio
+from pathlib import Path
+from thon import Thon
+from thon.models.options import ThonOptions
+
+async def main():
+    # Folder containing your .session files
+    sessions_path = Path("my_sessions")
+    
+    # Basic options
+    options = ThonOptions(retries=5, timeout=15)
+    
+    async for thon_session in Thon(options, sessions_folder=sessions_path):
+        # thon_session.thon is an active ProcessThon instance
+        # thon_session.session contains session metadata
+        
+        me = thon_session.thon.me
+        print(f"Logged in as: {me.first_name} (@{me.username})")
+        
+        # Access the underlying Telethon client
+        client = thon_session.thon.client
+        await client.send_message('me', 'Hello from Thon!')
+
+asyncio.run(main())
+```
+
+### 2. Searching for Verification Codes
+A common task is waiting for a verification code (e.g., from Telegram or a bot). Thon has built-in support for this.
+
+```python
+from thon.models.misc import ThonSearchCodeOptions
+
+async def wait_for_code(thon_instance):
+    search_options = ThonSearchCodeOptions(
+        wait_time=60,    # How long to wait for the message (seconds)
+        date_delta=300,  # Only look at messages from the last 5 minutes
+        regexp=r'\d{5}'  # Custom regex for the code
+    )
+    
+    code = await thon_instance.search_code(search_options)
+    if code:
+        print(f"Found code: {code}")
+    else:
+        print("Code not found.")
+```
+
+### 3. Handling Banned Sessions and Errors
+You can provide a callback to handle errors and automatically move banned sessions to a separate folder.
+
+```python
+def on_error():
+    print("An error occurred with a session!")
+
+async def process_with_safety():
+    options = ThonOptions()
+    bot = Thon(
+        options,
+        sessions_folder=Path("sessions"),
+        move_banned_folder=True,  # Automatically moves banned sessions to sessions/banned/
+        callback_error=on_error
+    )
+    
+    async for thon_session in bot:
+        # Only valid, unbanned sessions reach here
+        pass
+```
+
+---
+
+## 📁 Project Structure
+
+```text
+thon/
+├── thon/               # Core package directory
+│   ├── __init__.py     # Library entry point (Thon class)
+│   ├── converter.py    # Session conversion logic
+│   ├── process.py      # Main processing logic (ProcessThon)
+│   ├── models/         # Data models and options
+│   └── utils.py        # Utility functions
+├── pyproject.toml      # Build system and metadata
+└── README.md           # Documentation
+```
+
+---
+
+## 📜 License
+
+This project is licensed under the MIT License.

pyproject.toml

@@ -11,9 +11,6 @@ dependencies = [
     "telethon>=1.42.0",
 ]
 
-[project.scripts]
-thon = "thon:main"
-
 [build-system]
 requires = ["setuptools>=61.0"]
 build-backend = "setuptools.build_meta"