Docs: English README as default, remove REPOSITORY_METADATA

- Move full English docs to root README.md; docs/README_EN.md redirects
- Update Arabic and cross-doc links; fix diagrams paths to root README
- Delete .github/REPOSITORY_METADATA.md (maintainer-only content)

Made-with: Cursor

Author: code-root

.github/REPOSITORY_METADATA.md

@@ -1,36 +1,248 @@
-# VFS Appointment Bot · بوت مواعيد VFS
+# VFS Appointment Bot
 
-**English:** Automates checks on **VFS Global** appointment flows (DE / IT / PT) with optional **GPM**, **Playwright**, multi-window runs, and **Telegram / Email / Twilio** alerts.
+**Default / English** — This file is the main project documentation.  
+**العربية:** [التوثيق الكامل بالعربية](docs/README_AR.md)
 
-**العربية:** أتمتة التحقق من مواعيد **VFS Global** (ألمانيا / إيطاليا / البرتغال) مع **GPM** و**Playwright** اختياريين، نوافذ متوازية، وإشعارات **Telegram / البريد / Twilio**.
+Automates checking (and related flows) on **VFS Global** appointment portals for selected destination countries, with optional **GoLogin Profile Manager (GPM)** integration, **multi-window** runs, and **Telegram / Email / Twilio** notifications.
+
+**Repository:** [github.com/code-root/vfs-appointment-bot](https://github.com/code-root/vfs-appointment-bot)
+
+### GitHub: CI & automation
+
+- **Workflow (Actions):** [`.github/workflows/ci.yml`](.github/workflows/ci.yml) — Python **3.10 / 3.12**, `pip install -r requirements.txt`, `compileall`, and a small import smoke test (no Playwright browser download in CI).
+- **Dependabot** (optional): [`.github/dependabot.yml`](.github/dependabot.yml) for `pip` and GitHub Actions updates.
 
 ---
 
-## Documentation / التوثيق
+### Disclaimer
 
-| Language | Guide |
-|----------|--------|
-| **English** | **[docs/README_EN.md](docs/README_EN.md)** — full documentation, setup, layout, support |
-| **العربية** | **[docs/README_AR.md](docs/README_AR.md)** — الشرح الكامل بالعربية |
+Use this software **only in line with VFS Global’s terms of service** and applicable law. The authors are not responsible for misuse, account restrictions, or failed appointments. Credentials and automation are **your responsibility**.
 
-**Repository:** [github.com/code-root/vfs-appointment-bot](https://github.com/code-root/vfs-appointment-bot)
+### Features
+
+- **Multi-country flows (destination):** Germany (**DE**), Italy (**IT**), Portugal (**PT**), selected by factory routing in `vfs_bot/vfs_bot_factory.py`.
+- **Source country** is an ISO 3166-1 alpha-2 code (e.g. **AE**); **VFS login URLs** are mapped in `config/vfs-url.ini` as `SOURCE-DESTINATION` keys.
+- **Playwright** automation with **playwright-stealth**, realistic browser fingerprints, and configurable **Chromium / Firefox / WebKit** via `config/browser.ini`.
+- **Optional GPM:** start/stop profiles over HTTP API (`config/gpm.ini`), optional **Selenium** helpers for GPM UI operations.
+- **Notifications:** Telegram, Email, Twilio (wired through `notification/notification_client_factory.py`).
+- **Parallel windows:** `run_vfs_bot.py` can run multiple threads (each driving its own browser session) until an appointment is found or you stop the process.
+- **Profile bookkeeping:** optional GPM group **`VFS_Bot`**, `used_profiles.json`, helpers to populate/reset — see [docs/PROFILE_MANAGEMENT_README.md](docs/PROFILE_MANAGEMENT_README.md).
+- **Proxy list support** via `utils/proxy_manager.py` and `proxies.txt` (see `.gitignore` — do not commit secrets).
+
+### Requirements
 
-### Quick links
+- **Python 3.8+** (3.10+ recommended for recent dependencies).
+- **Playwright browsers:** at least **Chromium**; **Firefox** if `browser.ini` uses `firefox`.
+- A valid **VFS Global** account and the correct **portal URL** for your source→destination pair.
+- **GPM** (optional): default API base `http://127.0.0.1:14517` (configurable).
 
-| Topic | English | العربية |
-|--------|---------|---------|
-| Run & install | [docs/README_RUN.md](docs/README_RUN.md) | نفس الملف (عربي داخل المستند) |
-| GPM | [docs/README_GPM.md](docs/README_GPM.md) | نفس الملف |
-| GitHub push | [docs/GITHUB.md](docs/GITHUB.md) | نفس الملف |
-| Repo metadata & CI | [.github/REPOSITORY_METADATA.md](.github/REPOSITORY_METADATA.md) | وصف ووسوم مقترحة + إنجليزي |
-| **مخططات العملية** | [docs/diagrams/PROCESS.md](docs/diagrams/PROCESS.md) (Mermaid) | [صورة SVG](docs/diagrams/vfs-journey-overview.svg) — من الإعداد إلى الحجز |
+### Python dependencies (`requirements.txt`)
+
+| Package | Purpose |
+|---------|---------|
+| `playwright` | Browser automation |
+| `playwright-stealth` | Stealth patches for Playwright |
+| `selenium` | GPM UI / profile workflows where used |
+| `twilio` | SMS / Twilio-backed notifications |
+| `tqdm` | Progress display in batch scripts |
+| `requests` | HTTP (GPM API, health checks) |
+
+Install:
 
 ```bash
-git clone https://github.com/code-root/vfs-appointment-bot.git
-cd vfs-appointment-bot
 pip install -r requirements.txt
 playwright install chromium
-python run_vfs_bot.py
+# If using Firefox in config/browser.ini:
+playwright install firefox
 ```
 
-*(Configure `config/` first — see the language-specific guides above.)*
+### Quick start
+
+1. **Clone**
+
+   ```bash
+   git clone https://github.com/code-root/vfs-appointment-bot.git
+   cd vfs-appointment-bot
+   ```
+
+2. **Configure `config/`** (all `*.ini` in `config/` are merged — see `utils/config_reader.py`)
+
+   - Copy GPM example if needed:
+     ```bash
+     cp config_gpm_example.ini config/gpm.ini
+     ```
+   - Create or edit **`config/vfs-credential.ini`**: VFS **email** and **password** (sensitive — listed in `.gitignore`).
+   - Edit **`config/vfs-url.ini`**: add lines `XX-YY = https://...` where `XX` is source and `YY` is destination (e.g. `AE-PT`).
+   - Edit **`config/notification.ini`** for Telegram / email / Twilio (sensitive — gitignored in template workflow).
+   - Optional: **`config/appointment-params.ini`** defaults for `visa_center`, `visa_category`, `visa_sub_category` per country prefix (`DE-`, `IT-`, `PT-`).
+   - Optional: **`config/browser.ini`**: `type` (`chromium` / `firefox` / `webkit`), `headless`, viewport-related options.
+   - Optional: **`config/gpm.ini`**: `enabled`, `api_url`, `profile_id`, HTTP paths/methods, `auto_stop`, optional `api_token`, optional `group_name` for profile pools (see profile docs).
+
+3. **Run (recommended entry point)**
+
+   ```bash
+   python run_vfs_bot.py
+   ```
+
+   On Windows you can use **`run.bat`** (UTF-8, dependency checks, then `python run_vfs_bot.py`). On Linux/macOS, **`run.sh`** runs `python3 run_vfs_bot.py` after basic checks.
+
+4. **Adjust behavior in `run_vfs_bot.py`**
+
+   At the top of `main()` you will find:
+
+   - `source_country_code`, `destination_country_code`
+   - `appointment_params` dict (or `None`)
+   - `max_iterations`, `number_of_windows` (parallel threads)
+   - Profile age window (**20 minutes** by default) before refreshing context
+   - Inner check interval (**5 seconds** when `continuous_check=True` in `vfs_bot.run`)
+
+### Alternative CLI: `main.py`
+
+`main.py` provides argparse flags:
+
+- `-sc` / `--source-country-code`
+- `-dc` / `--destination-country-code`
+- `-ap` / `--appointment-params` as `key=value,key2=value2`
+
+It runs a **single** bot instance in a loop with a countdown between iterations based on `config/default.ini` (`interval`).  
+**Note:** Run **`main.py` from the repository root** (same folder as `run_vfs_bot.py`). The file prepends the project root to `sys.path` so `utils` and `vfs_bot` import correctly.
+
+### Repository layout (detailed)
+
+#### Entry points and `scripts/` helpers
+
+Run **`scripts/*.py` from the repo root** so `config/` and relative paths resolve.
+
+| Path | Role |
+|------|------|
+| `run_vfs_bot.py` | Main runner: config validation, logging (UTF-8 on Windows), multi-threaded windows, calls `get_vfs_bot()` and `vfs_bot.run()`. |
+| `main.py` | Argparse-based CLI loop; logging to `app.log` + stdout. |
+| `scripts/create_gpm_profile.py` | Interactive creation of one GPM profile via `GpmSeleniumClient`. |
+| `scripts/create_gpm_profiles.py` | Batch creation (e.g. up to **100** profiles in group **`VFS_Bot`**) — see [docs/PROFILE_MANAGEMENT_README.md](docs/PROFILE_MANAGEMENT_README.md). |
+| `scripts/populate_used_profiles.py` | Marks existing profiles in the GPM group as used in `used_profiles.json`. |
+| `scripts/reset_used_profiles.py` | Resets used-profile tracking. |
+| `scripts/test_gpm_connection.py` | Probes GPM HTTP API (`/api/v3/profiles`, etc.) using `config/gpm.ini`. |
+
+#### Packages
+
+| Path | Role |
+|------|------|
+| `vfs_bot/vfs_bot.py` | Abstract `VfsBot` base: Playwright lifecycle, stealth, GPM integration hooks, login/appointment pipeline, notifications. |
+| `vfs_bot/vfs_bot_de.py` | Germany-specific implementation. |
+| `vfs_bot/vfs_bot_it.py` | Italy-specific implementation. |
+| `vfs_bot/vfs_bot_pt.py` | Portugal-specific implementation. |
+| `vfs_bot/vfs_bot_factory.py` | `get_vfs_bot(source, destination)` → `UnsupportedCountryError` if destination not DE/IT/PT. |
+| `notification/notification_client.py` | Notification abstraction. |
+| `notification/telegram_client.py` | Telegram bot API client. |
+| `notification/email_client.py` | Email notifications. |
+| `notification/twilio_client.py` | Twilio client. |
+| `notification/notification_client_factory.py` | `get_notification_client`: channels `telegram`, `email`, and `slack` (in code, `slack` is wired to the Twilio client—use `email` or `telegram` unless you rely on that mapping). |
+| `utils/config_reader.py` | Loads every `config/*.ini` plus optional `VFS_BOT_CONFIG_PATH` env override. |
+| `utils/config_writer.py` | INI write helpers. |
+| `utils/timer.py` | Countdown between checks (used by `main.py`). |
+| `utils/gpm_client.py` | HTTP client for GPM profile start/stop and related API usage. |
+| `utils/gpm_selenium_client.py` | Selenium-based GPM interactions (profile creation, etc.). |
+| `utils/profile_manager.py` | Tracks **used** GPM profiles per group (`used_profiles.json`). |
+| `utils/proxy_manager.py` | Proxy rotation / loading from `proxies.txt`. |
+| `utils/account_manager.py` | Account-related helpers used by the bot flows. |
+| `utils/email_reader.py` | Email reading utilities (e.g. OTP / mail workflows where implemented). |
+| `utils/date_utils.py` | Date/time helpers. |
+
+#### `config/` INI files
+
+| File | Section(s) | Purpose |
+|------|------------|---------|
+| `vfs-credential.ini` | `vfs-credential` | VFS login email/password (**do not commit**). |
+| `vfs-url.ini` | `vfs-url` | `SOURCE-DEST = full login URL` mappings. |
+| `default.ini` | `default` | `interval` (seconds) for `main.py` loop between attempts. |
+| `appointment-params.ini` | `appointment-params` | Default `DE-*`, `IT-*`, `PT-*` visa center/category keys. |
+| `browser.ini` | `browser` | Engine type, headless, optional UA/locale/timezone/viewport. |
+| `gpm.ini` | `gpm` | GPM toggle, API URL, `profile_id`, HTTP paths, `auto_stop`, optional token, optional `group_name`. |
+| `notification.ini` | (per implementation) | Telegram, email, Twilio settings (**do not commit** real secrets). |
+
+#### More documentation (`docs/`)
+
+| File | Content |
+|------|---------|
+| [docs/README_AR.md](docs/README_AR.md) | **Full documentation in Arabic.** |
+| [docs/README_GPM.md](docs/README_GPM.md) | GPM setup, troubleshooting. |
+| [docs/README_RUN.md](docs/README_RUN.md) | Run commands (batch/shell vs direct `python`). |
+| [docs/PROFILE_MANAGEMENT_README.md](docs/PROFILE_MANAGEMENT_README.md) | GPM group `VFS_Bot`, `used_profiles.json`, batch profiles. |
+| [docs/GITHUB.md](docs/GITHUB.md) | Creating the GitHub repo, push, auth, common errors. |
+| [docs/diagrams/PROCESS.md](docs/diagrams/PROCESS.md) | **Flowcharts (Mermaid):** config → browser/GPM → VFS login → appointment → slots → notify. |
+| [docs/diagrams/vfs-journey-overview.svg](docs/diagrams/vfs-journey-overview.svg) | **Illustrative SVG** (same journey, Arabic + English labels). |
+
+#### Quick reference
+
+| Topic | Link |
+|-------|------|
+| Run & install | [docs/README_RUN.md](docs/README_RUN.md) |
+| GPM | [docs/README_GPM.md](docs/README_GPM.md) |
+| GitHub push | [docs/GITHUB.md](docs/GITHUB.md) |
+| Process diagrams | [docs/diagrams/PROCESS.md](docs/diagrams/PROCESS.md) |
+
+#### Other tracked / generated artifacts
+
+| Item | Notes |
+|------|------|
+| `app.log` | Log file from runners; **gitignored**. |
+| `used_profiles.json` | GPM profile usage tracker; **gitignored**. |
+| `proxies.txt` | Proxy list; **gitignored**. |
+| `.env` | Environment variables locally; treat as **secret**. |
+| `docs/images/error_email_field_not_found.png` | Debug screenshot path (bot may overwrite). |
+| `assets/` | Optional static assets (e.g. README QR images). |
+
+### Supported countries (destination)
+
+| Code | Country |
+|------|---------|
+| DE | Germany |
+| IT | Italy |
+| PT | Portugal |
+
+Extend by adding a new `vfs_bot_*.py`, registering it in `vfs_bot_factory.py`, and supplying URLs + appointment parameter handling as required by that VFS site.
+
+### Logging & troubleshooting
+
+- Read **`app.log`** for stack traces and step logs.
+- Verify **`config/vfs-url.ini`** key matches your `source_country_code` and `destination_country_code` (e.g. `AE-PT`).
+- For GPM: run **`python scripts/test_gpm_connection.py`** and see **[docs/README_GPM.md](docs/README_GPM.md)**.
+- Windows: **`run.bat`** sets UTF-8 code page and `PYTHONIOENCODING` for Arabic/Unicode console output.
+
+### Contributing
+
+1. Fork the repository  
+2. Branch: `git checkout -b feature/your-feature`  
+3. Commit and push  
+4. Open a Pull Request  
+
+### License
+
+Open source — see repository policy. Use responsibly.
+
+### Acknowledgements
+
+- [Playwright](https://playwright.dev/)  
+- [GoLogin / GPM](https://gologin.com/) (ecosystem)  
+- Contributors and issue reporters  
+
+---
+
+### Support this project
+
+If this tool is useful to you, optional support helps maintain and improve it. Pick whatever works best for you.
+
+| Channel | How to support |
+|--------|----------------|
+| **PayPal** | [paypal.me/sofaapi](https://paypal.me/sofaapi) |
+| **Binance Pay / UID** | **1138751298** — send from the Binance app (Pay / internal transfer when available). |
+| **Binance — deposit (web)** | [Deposit crypto (Binance)](https://www.binance.com/en/my/wallet/account/main/deposit/crypto) — sign in, pick the asset, then select **BSC (BEP20)**. |
+| **BSC address (copy)** | `0x94c5005229784d9b7df4e7a7a0c3b25a08fd57bc` |
+
+> **Network:** Use **BSC (BEP-20)** only. This address is for **USDT (BEP-20)** and **BTC on BSC** (Binance-Peg / in-app “BTC” on BSC), matching the Binance deposit screens below. **Do not** send **native Bitcoin (on-chain BTC)**, **ERC-20**, or **NFTs** to this address.
+
+#### Deposit QR codes (scan in Binance or any BSC wallet)
+
+| USDT · BSC | BTC · BSC |
+|------------|-----------|
+| ![USDT deposit QR — BSC](assets/deposit-usdt-bsc.jpeg) | ![BTC on BSC deposit QR](assets/deposit-btc-bsc.jpeg) |

README.md

@@ -1,6 +1,6 @@
 # GitHub: إنشاء المستودع والرفع
 
-للدليل الكامل: [README_AR.md](README_AR.md) · [README_EN.md](README_EN.md)
+للدليل الكامل: [README.md (إنجليزي)](../README.md) · [README_AR.md (عربي)](README_AR.md)
 
 ## إنشاء مستودع جديد
 

docs/GITHUB.md

@@ -1,6 +1,6 @@
 # إدارة بروفايلات GPM
 
-للدليل الكامل: [README_AR.md](README_AR.md) · [README_EN.md](README_EN.md)
+للدليل الكامل: [README.md (إنجليزي)](../README.md) · [README_AR.md (عربي)](README_AR.md)
 
 ## نظرة عامة