# Workspace Rules & Instructions

## Usage and Quota Commands (/usage-ai, /usage, /quota, or natural language)
- Whenever the user asks about AGY limits, 5-hour quota, 7-day quota, or sends commands like `/usage-ai`, `/usage`, `وضعیت مصرف`, `سهمیه`:
  1. Execute `agy --print "/usage"` and `agy --print "/credits"`.
  2. Parse the quotas (Gemini, Claude, GPT limits, reset timestamps, credits).
  3. Analyze the results and report them clearly to the user (in Persian if user communicates in Persian).

## Project Directory Structure & Explicit Creation
- NEVER create, initialize, or add a new project on your own or without the user's explicit request. Projects must ONLY be created when the user explicitly asks to create a new project.
- When the user explicitly requests creating a new project:
  All projects must be placed in the following directory pattern:
  `/root/projects/{user-telegram-id}/{project-name}`

## Telegram Bot Changes & Quality Assurance
- ALWAYS after any code modification, feature addition, or fix in `/root/telegram-agy-bot`:
  1. Review and verify all bot commands, handlers, callback buttons, and message formatting.
  2. If needed, update the bot structure, keyboard layouts, command lists, and help texts to match the changes.
  3. Compile and check syntax (`python -m py_compile ...`).
  4. NEVER run `systemctl restart agy-telegram-bot` synchronously in bash commands during a turn (it kills the active turn immediately). Instead, ALWAYS include the `[[RESTART_BOT]]` tag in your final response so the bot restarts itself gracefully after fully delivering the response to the user.

## Server Domain, Subdomains & Reverse Proxy (Caddy)
- The wildcard domain `*.msa.artacloud.ir` (e.g. `app.msa.artacloud.ir`, `api.msa.artacloud.ir`, `{project-name}.msa.artacloud.ir`) points directly to this server (`213.142.132.205`).
- ALWAYS use **Caddy** (`/etc/caddy/Caddyfile` or system caddy) as the reverse proxy web server for all web projects, APIs, webhooks, and subdomains.
- Caddy automatically manages free HTTPS / SSL certificates via Let's Encrypt / ZeroSSL for any `*.msa.artacloud.ir` subdomains. Whenever exposing a service, configure Caddy and reload it (`systemctl reload caddy` or `caddy reload --config /etc/caddy/Caddyfile`).

## Flash Auto Reasoning & Global QA with Highest Model
- In **Flash Auto Mode**, whenever work/changes/edits are finished:
  1. The final prepared response and code changes MUST be thoroughly verified and audited by the highest available model/reasoning level (e.g., High Effort / Pro / Thinking) for bug detection and sanity checks.
  2. **If no issues/bugs are detected:** Proceed without additional modifications and send the clean final response to the user.
  3. **If any bugs, inaccuracies, syntax/logic errors, or flaws are identified:** The agent MUST automatically perform deep debugging and fixing using the highest available model, re-verify the resolution, and then deliver the complete, corrected response to the user.

## Mandatory High Effort for Troubleshooting & Diagnostics
- ALWAYS and for all projects, initial bug analysis, troubleshooting, diagnosis, root-cause analysis, and system investigations MUST be performed with the highest level of reasoning effort (High Effort / High Thinking).

## Preferred Programming Language & Tech Stack (PHP)
- ALWAYS use **PHP** (e.g. PHP 8.x, modern PHP, Laravel/Symfony/Slim or standalone PHP scripts/APIs) as the primary/default programming language and technology stack for all projects and backend services whenever feasible and applicable, unless the user explicitly requests another language or the nature of the task strictly requires a different technology.