AGENTS.md — AI Agent Guidance & Project Discovery Policy

Welcome, AI Agent. Treat this repository as a production environment maintained by senior engineers. Before proposing changes, executing commands, or asking questions, you MUST follow the Discovery Protocol defined below.

1. Prime Directive: Universal Autonomous Decision Mandate

"Understand before you change. Inspect before you ask. Decide autonomously in EVERY project." Act like a senior engineer newly onboarded to this codebase. Do not make assumptions, do not rewrite functional patterns, and do not make changes without establishing your mental model first. Universal Scope: All rules in this policy apply to EVERY repository, server, container, and technology stack. Specific names, endpoints, and commands mentioned are illustrative examples of forbidden behavior categories.

2. Onboarding & Discovery Checklist

Before generating code or editing any file:

1. Inspect Repository Layout: Check directory hierarchy, package definitions, and workspace roots.
2. Review Documentation: Read README.md, docs/, API specifications, and architecture decisions (ADRs).
3. Verify Git State: Run git status, check current branch, inspect git log -n 5, and note uncommitted diffs.
4. Identify Dependencies & Runtimes: Check lockfiles (pnpm-lock.yaml, package-lock.json, poetry.lock, Cargo.lock, go.sum).
5. Inspect Environment & Config: Check .env.example, docker-compose files, CI/CD pipelines (.github/workflows/).
6. Locate Test Suites: Identify test commands, coverage requirements, and how to verify locally without destructive side effects.

3. Strict Question Policy

Universal Rule Across All Projects ("خودش تصمیم بگیره"):

The prohibitions below apply to ALL repositories, services, servers, and technologies. Whether working on web apps, microservices, mobile apps, databases, or AI pipelines:

• NEVER ask permission to run tests, inspect files, check logs, verify routes, probe endpoints, inspect runtimes, or mutate containers over SSH/SCP.
• ALWAYS decide and act autonomously using local repository inspection, local test doubles, and mock transports.

Do NOT ask questions such as:

• ❌ "What should I do next?"
• ❌ "Can you provide more files or show me where X is located?"
• ❌ "How does the auth system work?"
• ❌ "Allow testing <endpoint>?" (e.g., Allow testing /api/models/generate? or asking permission to run SSH/docker test snippets).
• ❌ "Allow checking model router endpoints?" (e.g., asking permission to SSH and parse router decorators or code files).
• ❌ "Allow testing central model dispatch?" (e.g., asking permission to test reasoning routers or gateways via SSH).
• ❌ "Allow testing TTS synthesis speed?" or "Allow testing updated Edge-TTS?" (e.g., asking permission to benchmark speech synthesis latency, test updated Edge-TTS, or run remote TTSService.synthesize_chunk scripts).
• ❌ "Allow testing STT pipeline?" (e.g., asking permission to test speech-to-text transcription, decode audio, or run remote STTService.transcribe_audio_bytes scripts).
• ❌ "Allow checking edge-tts version?" (or asking permission to run pip show, pip list, pip freeze via SSH).
• ❌ "Allow upgrading edge-tts?" (or asking permission to run pip install -U, npm update, pip install --upgrade via SSH).
• ❌ "Allow checking container contents?" (or asking permission to run docker exec ... ls, find, cat via SSH).
• ❌ "Allow checking server container and git status?" (e.g., asking permission to run ssh ... "docker ps ... && git status -s").
• ❌ "Allow checking server git branch and log?" (e.g., asking permission to run ssh ... "git branch --show-current && git log ...").
• ❌ "Allow listing git branches on server?" (e.g., asking permission to run ssh ... "git branch -a").
• ❌ "Allow viewing server docker-compose.yml?" (or asking permission to run cat, head, less on remote deployment files via SSH).
• ❌ "Allow checking server MobileMenu.tsx?" (or asking permission to run cat, head, less on remote frontend components or source files via SSH).
• ❌ "Allow checking STT providers?" (e.g., asking permission to inspect provider keys or query /models via SSH).
• ❌ "Allow testing Groq Whisper STT?" (e.g., asking permission to test transcription endpoints via SSH).
• ❌ "Allow deploying updated app files to production?" or "Allow deploying hermes_router and restarting container?" (e.g., asking permission to run scp ... or docker restart via SSH).
• ❌ "Allow restarting hamzad-ara container?" (or asking permission to restart containers via SSH).
• ❌ "Allow checking ARA health endpoint?" (e.g., asking permission to curl internal health endpoints via SSH).
• ❌ "Allow running 20-utterance Persian evaluation suite?" or "Allow running full 20-utterance benchmark?" (e.g., asking permission to upload and run remote benchmark suites via SSH).
• ❌ "Allow checking molavi-pro container on server?" (e.g., asking permission to run docker ps --format ... via SSH).
• ❌ "Allow checking hamzad-ara container logs?" (e.g., asking permission to run docker logs via SSH).
• ❌ "Allow checking server command history?" (e.g., asking permission to run history | tail via SSH).
• ❌ "Allow checking .next on server host?" (e.g., asking permission to inspect host build folders via SSH).
• ❌ "Allow retrying SSH connection?" (e.g., asking permission to retry failed SSH connections or run uptime via SSH).
• ❌ "Allow testing SSH to hamzad_server?" or "Allow testing SSH connection?" (e.g., asking permission to run echo 'connection test ok' via SSH).
• ❌ "Allow checking server molavi-pro container and git?" (e.g., asking permission to run compound docker ps && git status via SSH).
• ❌ "Allow listing Hermes skills?" or "Allow listing <service> skills?" (e.g., asking permission to query skill endpoints via remote docker exec).
• ❌ "Allow inspecting container .next directory?" (e.g., asking permission to run docker exec ... ls -la /app/.next via SSH).
• ❌ "Allow copying components to server?" (e.g., asking permission to copy components via scp).
• ❌ "Allow copying page.tsx and robots.ts to server?" or "Allow copying robots.ts to server?" (e.g., asking permission to copy pages or files via scp).
• ❌ "Allow checking node on server host?" or "Allow checking <runtime / binary> on server host?" (e.g., asking permission to run ssh ... "node -v || true" or check host runtimes).
• ❌ "Allow checking docker images on server?" or "Allow checking <docker images / tags> on server?" (e.g., asking permission to run ssh ... "docker images | grep ...").
• ❌ "Allow listing containers on hamzad_server?" or "Allow listing containers on <server>?" (e.g., asking permission to run ssh ... "docker ps --format ...").
• ❌ "Allow uploading build assets archive?" or "Allow uploading <archive / build assets> to server?" (e.g., asking permission to run scp ... /tmp/...tar.gz ...).
• ❌ "Allow inspecting Hermes skills from hamzad-ara?" or "Allow inspecting <service> skills from <container>?" (e.g., asking permission to run ssh ... "docker exec ... http://staging-hermes:8090/api/v1/skills ...").
• ❌ "Allow deploying assets to container and restarting?" or "Allow deploying <assets> to container and restarting?" (e.g., asking permission to run ssh ... "tar -xzf ... && docker cp ... && docker restart ... && curl ...").
• ❌ "Allow deploying updated code to production?", "Allow deploying updated ARA files to production server?", "Allow deploying updated files?", "Allow executing deployment script?", "Allow deploying assets to hamzad_server?", or "Allow deploying assets to <server>?" (e.g., Allow deploying updated code to production? tar -czf - app static | ssh -o ConnectTimeout=15 hamzad_server "tar -xzf - -C /opt/projects/hamzad-ara && docker restart hamzad-ara" or asking permission to run deployment scripts like bash /tmp/deploy_molavi.sh).
• ❌ "Allow listing all Hermes skills?" or "Allow listing all <service> skills?" (e.g., asking permission to run ssh ... "docker exec ... http://staging-hermes:8090/api/v1/skills ...").
• ❌ "Allow checking HTTP headers of ara.molavi.pro?" or "Allow checking HTTP headers of <domain / URL>?" (e.g., Allow checking HTTP headers of ara.molavi.pro? curl -sI https://ara.molavi.pro or asking permission to run curl -sI / curl -I against live public domains).
• ❌ "Allow downloading three.min.js locally?" or "Allow downloading <asset / library> locally?" (e.g., asking permission to download vendor scripts or frontend assets like Allow downloading three.min.js locally? curl -sL https://cdnjs.cloudflare.com/... -o /Users/taghimolavi/hamzad/hamzad-ara/static/js/three.min.js).
• ❌ "Allow executing production login verification?" (e.g., Allow executing production login verification? python3 /Users/taghimolavi/hamzad/hamzad-ara/verify_prod_login.py or asking permission to run login verification scripts against production).
• ❌ "Allow testing WebSocket auth using venv python?" or "Allow testing WebSocket auth using <runtime>?" (e.g., asking permission to run async WebSocket auth test scripts against live endpoints via .venv/bin/python3 -c "import asyncio, httpx, websockets...").
• ❌ "Allow testing live wake-word and meeting WebSocket flow?" (e.g., Allow testing live wake-word and meeting WebSocket flow? python3 /Users/taghimolavi/hamzad/hamzad-ara/test_live_wake_flow.py or asking permission to run unmocked live WebSocket flow scripts).
• ❌ "Allow write access to this path?" or "Allow write access to <path>?" (e.g., asking permission to write to models, routes, or codebase files like Allow write access to this path? /Users/taghimolavi/ivnanewscom/app/Models/News.php or Allow write access to this path? /Users/taghimolavi/ivnanewscom/routes/api.php).
• ❌ "Allow debugging response for Persian digits?", "Allow verifying live production authentication suite?", "Allow verifying live production login endpoint?" or "Allow testing production login with default passcode?" (e.g., asking permission to run authentication test suites, debug response bodies for Persian digits, or test candidate passcodes like ara2026 or ara۲۰۲۶ against live production domains).
• ❌ "Allow testing SSH connectivity to hamzad_server?" or "Allow testing SSH connectivity to <server>?" (e.g., Allow testing SSH connectivity to hamzad_server? ssh -v -o ConnectTimeout=10 hamzad_server "uptime").
• ❌ "Allow testing SSH connection with IPQoS=none?" or "Allow testing SSH connection with <option>?" (e.g., Allow testing SSH connection with IPQoS=none? ssh -o ConnectTimeout=15 -o IPQoS=none hamzad_server "echo ok").
• ❌ "Allow running live test?" (e.g., Allow running live test? /Users/taghimolavi/hamzad/hamzad-core/.venv/bin/python3 test_live_wake_flow.py or asking permission to run unmocked live flow scripts).
• ❌ "Allow checking Hermes API endpoints?" or "Allow checking <service> API endpoints?" (e.g., asking permission to run ssh ... "docker exec ... http://staging-hermes:8090/docs ... /openapi.json ...").
• ❌ "Allow verifying title on public URL?", "Allow verifying deployed app.js features?", "Allow verifying deployed style.css features?", "Allow checking health endpoint on production?", or "Allow testing public URL?" (e.g., asking permission to run curl -sk "https://ara.molavi.pro/static/js/app.js?v=..." | grep ..., curl -sk "https://ara.molavi.pro/static/css/style.css?v=..." | grep ..., curl -sk https://ara.molavi.pro/api/health, curl -sk https://ara.molavi.pro | grep ..., or curl https://...).
• ❌ "Allow testing wake-word flow inside production container?", "Allow testing live wake-word flow in container?", or "Allow testing WebSocket flow?" (e.g., asking permission to run ssh ... "docker exec hamzad-ara python3 -c '... websockets.connect(\"ws://127.0.0.1:3050/ws/meeting...\") ...'").
• ❌ "Allow probing staging-hermes endpoints?" or "Allow probing <service> endpoints?" (e.g., asking permission to run ssh ... "docker exec hamzad-ara python3 -c '... for path in ["/", "/api/v1", ...]: ...'").
• ❌ "Allow syncing updated ARA files to production server?" or "Allow copying updated files to target directories on hamzad_server?" (e.g., asking permission to run multi-file scp chains like scp -q app/... static/... hamzad_server:/opt/projects/hamzad-ara/...).
• ❌ "Allow transferring stt_service.py via SSH cat?" or "Allow transferring <file> via SSH cat?" (e.g., asking permission to run ssh ... "cat > /opt/.../file" < file).
• ❌ "Should I run this test on the remote server?"

Instead — Decide Autonomously ("خودش تصمیم بگیره"):

• Search the codebase using grep, symbol search, or directory listing.
• Inspect local route definitions, controllers, schemas, and models in the workspace directly instead of attempting remote SSH inspection.
• Infer conventions from existing implementations and commit history.
• Read existing unit/integration tests for usage patterns.
• Autonomously verify model routers, dispatch logic, and payload generation using local mocks (httpx.MockTransport, respx, unittest.mock) without asking for human permission.
• Autonomously verify speech synthesis, audio streaming, updated Edge-TTS libraries, and TTS services (TTSService) using local async mocks (unittest.mock.AsyncMock) and dummy audio chunk bytes without asking permission or triggering remote SSH benchmarks.
• Autonomously verify speech-to-text transcription, audio chunk decoding, and STT services (STTService) using local async mocks (unittest.mock.AsyncMock) and dummy audio bytes without asking permission or triggering remote SSH transcription benchmarks.
• Autonomously inspect installed package versions, CLI tools, and library requirements from local manifests (requirements.txt, poetry.lock, pyproject.toml, package.json, Dockerfile) without firing remote pip show commands or asking permission.
• Autonomously manage dependency upgrades by updating local manifests (requirements.txt, pyproject.toml, poetry.lock, package.json, Dockerfile) and testing compatibility locally without firing remote SSH pip install -U commands or asking permission.
• Autonomously discover container configurations, service definitions, and deployment port bindings from local files (docker-compose.yml, Dockerfile), and inspect git branch (git branch --show-current), branch listings (git branch, git branch -a), commit history, and working tree status locally (git status -s, git log) without SSH probing or asking permission.
• Autonomously discover container filesystem layouts and directory structures by inspecting local repository files, Dockerfile (WORKDIR, COPY directives), and docker-compose.yml (volume mounts) without executing remote container directory probing (docker exec ... ls) or asking permission.
• Autonomously discover deployment configurations, service definitions, and compose files (docker-compose.yml, Dockerfile, nginx.conf) from local workspace files directly without executing remote cat commands or asking permission.
• Autonomously discover frontend components, UI templates, and application code (components/MobileMenu.tsx, .tsx, .jsx, .vue) from local workspace files directly without executing remote cat commands or asking permission.
• Autonomously discover STT provider configurations, endpoints, and credentials from local settings (app/config.py, .env.example) and test integrations locally via mocked HTTP clients without firing remote SSH probes or asking permission.
• Autonomously manage code commits and deployment preparation in the local workspace repository without firing ad-hoc scp uploads or container restarts mid-task.
• Autonomously execute benchmark and evaluation suites locally using local fixtures and test doubles without uploading or running evaluation scripts on remote containers.
• Autonomously verify health endpoints, application logs, command history, and build outputs (.next) locally within the workspace environment without SSH container log tailing (docker logs --tail) or asking permission across ANY project.
• Autonomously handle SSH connection drops and latency fallbacks: never ask permission to retry SSH or test reachability via uptime/echo probes; fall back to local offline test runners and mocks.
• Autonomously inspect container architectures and git status from local manifests and local git status without running compound SSH checks.
• Autonomously discover skills and internal microservice APIs from local registry manifests (hermes-skill-discovery-registry-v1.json, isolated_hermes/) and mock endpoints locally without remote container execution.
• Autonomously verify container build outputs locally using npm run build without inspecting container .next directories over SSH.
• Autonomously manage components, pages, and SEO files through local version control (git commit, git push), avoiding ad-hoc SCP commands to server directories.
• Autonomously discover runtime requirements (Node.js versions, Python runtimes) from local repository manifests (package.json engines, .nvmrc, Dockerfile) without firing remote SSH node -v probes or asking permission.
• Autonomously inspect Docker images, container image tags, and base images from local repository manifests (docker-compose.yml, Dockerfile, CI pipelines) without firing remote SSH docker images or grep commands or asking permission.
• Autonomously discover container services, container names, and port allocations from local repository manifests (docker-compose.yml, Dockerfile) without firing remote SSH docker ps commands or asking permission.
• Autonomously verify build assets locally and restrict server artifact deployments to planned release workflows without firing ad-hoc scp ... /tmp/*.tar.gz archive uploads or asking permission.
• Autonomously discover cross-container microservice capabilities and skill endpoints from local manifests without firing remote SSH cross-container inspection commands or asking permission.
• Autonomously manage container releases through planned deployment scripts (deploy.sh) without firing ad-hoc chained container hot-patching commands (tar -xzf ... && docker cp ... && docker restart ...) or stalling the user with permission prompts to execute release scripts (Allow executing deployment script? bash /tmp/deploy_molavi.sh). If deployment execution is required by the task, decide autonomously to verify locally and execute via canonical release workflows without stopping for confirmation.
• Autonomously discover complete skill catalogs, tool definitions, and microservice capabilities from local registry manifests (hermes-skill-discovery-registry-v1.json, isolated_hermes/) without firing remote SSH skill enumeration scripts or asking permission.
• Autonomously verify static assets (static/js/app.js, static/css/style.css), health routes, page titles, HTML metadata, and HTTP response headers from local repository files, web server configs (nginx.conf, middleware), and local test clients without firing live public URL curls (curl ... https://ara.molavi.pro/..., curl -sI https://ara.molavi.pro) or asking permission in ANY project.
• Autonomously test and verify WebSocket authentication (/ws/meeting?token=...), session events (session_ready), meeting routers, and wake-word detection pipelines (wake_detected, test_live_wake_flow.py) locally using mock WebSocket clients (TestClient) and async fixtures without executing live flow scripts against production unprompted or asking "Allow testing WebSocket auth using venv python?".
• Autonomously verify authentication handlers, login routes (/api/auth/login), production login verification scripts (verify_prod_login.py), Persian digit normalization, response bodies, passcode checks, and session tokens locally using test clients (starlette.testclient.TestClient) and mock requests without probing live production authentication endpoints or asking permission.
• Autonomously write and modify codebase files, application models (app/Models/News.php), routing definitions (routes/api.php), and configuration files across filesystem paths and workspace roots using local file tools without asking write permission or halting execution.
• Autonomously download or bundle required vendor assets (three.min.js), client scripts, and frontend libraries locally using standard workspace tools without asking permission or opening modal prompts.
• Autonomously handle SSH latency, timeouts, or connectivity drops by falling back to local workspace files and local mocks without firing verbose probes (ssh -v), testing IPQoS options (-o IPQoS=none), or asking permission.
• Autonomously verify integration flows, live speech/WebSocket pipelines, and application logic using local unit tests and test doubles without firing ad-hoc unmocked scripts or asking "Allow running live test?".
• Autonomously discover API endpoints, schemas, and OpenAPI paths from local route definitions and schema files without firing remote SSH probes to /docs or /openapi.json or asking permission.
• Autonomously verify microservice endpoints, health routes, and chat completion APIs using local route definitions and mock transports without firing remote SSH endpoint probing loops (staging-hermes:8090) or asking permission.
• Autonomously manage code commits and deployment preparation in the local workspace repository without firing ad-hoc multi-file scp uploads, SSH cat redirects (cat > /path/file < local_file), or container restarts mid-task.

Handling Unpredicted States & Deferring Questions ("در حالت‌های پیش‌بینی‌نشده ادامه بده و همه رو آخرش یه جا بپرس"):

• Never Halt Mid-Run: If an unexpected state, ambiguous parameter, or edge case arises, DO NOT freeze execution.
• Proceed With All Doable Work: Implement safe reversible fallbacks, and proceed with all independent subtasks, code changes, and tests.
• Accumulate Questions: Queue any non-critical doubts or unpredicted decisions into a pending batch.
• Consolidated Batch at the End: Ask all accumulated questions together in a single consolidated turn at the end of the run ("همه رو یه جا بپرسه").

Only ask questions immediately when:

1. A genuine destructive blocker exists where information cannot be found in the repository and execution cannot safely proceed.
2. The user requested an ambiguous destructive operation (e.g., database wipe, deprecating public APIs).
3. An architectural decision has multiple mutually exclusive trade-offs with no safe fallback.

4. Engineering Standards & Behavioral Rules

• Minimal Diffs: Make targeted, atomic modifications. Never refactor surrounding untouched code unless explicitly asked.
• Pattern Matching: Match the existing paradigm (error handling, logging, naming, formatting, type definitions).
• Backward Compatibility: Preserve existing function signatures, API schemas, database schemas, and CLI options.
• Zero Hallucinated Dependencies: Do not introduce new third-party dependencies without verifying existing alternatives in the lockfile.
• Zero Timid Test Prompts ("Decide By Yourself"): NEVER prompt the user with interactive confirmation questions to test an endpoint, inspect router decorators, test central model dispatch, test TTS synthesis speed, test updated Edge-TTS, test STT pipeline, check STT providers, test Groq Whisper, deploy files via SCP, copy components or pages via SCP, restart containers, check health endpoints, run evaluation suites, check package versions, upgrade packages, check container contents, view server docker-compose.yml, check server MobileMenu.tsx, check container logs, check bash history, check remote .next folder, retry SSH connections, test SSH liveness, check server container and git status compoundly, list Hermes skills, inspect container .next directories, copy components or pages via SCP, check Node or runtimes on server hosts, or check server container, git branch, or git log (e.g. Allow testing /api/models/generate?, Allow checking edge-tts version?, Allow upgrading edge-tts?, Allow testing updated Edge-TTS?, Allow testing STT pipeline?, Allow checking STT providers?, Allow testing Groq Whisper STT?, Allow deploying updated app files to production?, Allow restarting hamzad-ara container?, Allow checking ARA health endpoint?, Allow running 20-utterance Persian evaluation suite?, Allow checking container contents?, Allow viewing server docker-compose.yml?, Allow checking server MobileMenu.tsx?, Allow checking container logs?, Allow checking hamzad-ara container logs?, Allow checking server command history?, Allow checking .next on server host?, Allow retrying SSH connection?, Allow testing SSH to hamzad_server?, Allow checking server molavi-pro container and git?, Allow listing Hermes skills?, Allow inspecting container .next directory?, Allow copying components to server?, Allow copying page.tsx and robots.ts to server?, Allow copying robots.ts to server?, Allow checking node on server host?, Allow checking docker images on server?, Allow listing containers on hamzad_server?, Allow uploading build assets archive?, Allow inspecting Hermes skills from hamzad-ara?, Allow deploying assets to container and restarting?, Allow deploying updated code to production?, Allow deploying updated ARA files to production server?, Allow deploying updated files?, Allow executing deployment script?, Allow deploying assets to hamzad_server?, Allow listing all Hermes skills?, Allow verifying title on public URL?, Allow verifying deployed app.js features?, Allow verifying deployed style.css features?, Allow checking health endpoint on production?, Allow checking Hermes API endpoints?, Allow probing staging-hermes endpoints?, Allow checking HTTP headers of ara.molavi.pro?, Allow downloading three.min.js locally?, Allow executing production login verification?, Allow testing WebSocket auth using venv python?, Allow testing live wake-word and meeting WebSocket flow?, Allow debugging response for Persian digits?, Allow write access to this path?, Allow verifying live production authentication suite?, Allow verifying live production login endpoint?, Allow testing production login with default passcode?, Allow testing SSH connectivity to hamzad_server?, Allow testing SSH connection with IPQoS=none?, Allow running live test?, Allow testing wake-word flow inside production container?, Allow testing live wake-word flow in container?, Allow syncing updated ARA files to production server?, Allow copying updated files to target directories on hamzad_server?, Allow transferring stt_service.py via SSH cat?, Allow checking server container and git status?, Allow checking server git branch and log?, Allow listing git branches on server?, Allow checking molavi-pro container on server?). Decide autonomously to inspect and test locally with mocks or test suites.
• Zero Public URL & Live Domain Probing: NEVER run curl, wget, or HTTP requests against live public domains, query live HTTP headers via curl -sI / curl -I (Allow checking HTTP headers of ara.molavi.pro? curl -sI https://ara.molavi.pro), production URLs, or deployed static asset bundles (https://ara.molavi.pro/static/js/app.js, https://ara.molavi.pro/static/css/style.css, https://ara.molavi.pro/api/health, https://molavi.pro) to verify features, check health routes, verify titles, inspect HTTP headers, or deployment states in ANY project. Verify features and assets statically from local source files (static/js/app.js), test health routes and headers locally with mock clients (TestClient), and inspect HTML metadata, middleware, and server configs (nginx.conf) statically from local source files.
• Zero Remote Host Runtime & Binary Probing via SSH: NEVER run ssh commands (ssh ... "node -v || true", python3 --version, pnpm -v) to probe host runtimes or installed binaries on remote servers. Determine runtime requirements statically from package manifests (package.json, .nvmrc, Dockerfile) and verify runtimes locally in the workspace.
• Zero Remote Docker Image & Tag Probing via SSH: NEVER run ssh commands (ssh ... "docker images", docker images | grep ..., docker image ls) to inspect Docker images, tags, or cached layers on remote servers. Determine image configurations statically from repository manifests (docker-compose.yml, Dockerfile) and build or inspect images locally in the workspace if Docker is available.
• Zero Remote Container Listing Probing via SSH: NEVER run ssh commands (ssh ... "docker ps --format ..." or docker ps) to list running containers, inspect status tables, or query ports on remote servers. Determine container configurations and port mappings statically from repository manifests (docker-compose.yml, Dockerfile).
• Zero Ad-hoc SCP Build Asset & Archive Uploading via SSH: NEVER run exploratory scp commands to upload build asset archives, temporary tarballs, or asset bundles (/tmp/*.tar.gz) directly to production server hosts. Verify builds locally and use canonical deployment scripts (deploy.sh).
• Zero Remote Cross-Container Service Probing via SSH: NEVER run ssh commands (docker exec <container> python3 -c '... urllib.request.urlopen("http://<service>:...") ...') to query internal APIs across containers. Discover service mesh configurations and skills statically from local manifests (docker-compose.yml, hermes-skill-discovery-registry-v1.json) and mock endpoints locally.
• Zero Ad-hoc Container Hot-Patching & Deployment Mutation via SSH: NEVER run tar streaming SSH pipes (tar -czf - ... | ssh ... "tar -xzf - ... && docker restart ..."), compound ssh commands, or ask permission to deploy updated files (Allow deploying updated code to production?, Allow deploying updated ARA files to production server?, Allow deploying updated files?) (bash /tmp/deploy_molavi.sh, Allow executing deployment script?) or hot-swap files or restart containers mid-task. Use canonical release workflows (deploy.sh) and verify changes locally.
• Zero Remote Exhaustive Skill Enumeration via SSH: NEVER run ssh commands (docker exec ... http://staging-hermes:8090/api/v1/skills ... names = [...]) to parse or print skill catalogs on remote servers. Discover all skills statically from local manifests (hermes-skill-discovery-registry-v1.json).
• Zero Remote API Docs & OpenAPI Probing via SSH: NEVER run ssh commands (docker exec ... http://staging-hermes:8090/docs ... /openapi.json) to probe documentation endpoints or fetch OpenAPI schemas on remote servers. Discover all API endpoints and schemas statically from local codebase files.
• Zero Vendor Asset Download Permission Seeking: NEVER prompt the user asking "Allow downloading three.min.js locally?" or request permission before fetching client scripts or vendor libraries into local asset directories (static/js/three.min.js). Fetch or bundle required assets autonomously without confirmation dialogs.
• Zero Filesystem & Workspace Write Access Permission Seeking: NEVER prompt the user asking "Allow write access to this path?" or request permission before editing models, routes, controllers, or configuration files across filesystem paths or workspace roots (e.g. /Users/taghimolavi/ivnanewscom/app/Models/News.php, /Users/taghimolavi/ivnanewscom/routes/api.php). Edit target files directly and autonomously using file tools.
• Zero Live Production Authentication Probing: NEVER send HTTP POST requests, run verification scripts (Allow executing production login verification?, verify_prod_login.py), debug live response bodies (Allow debugging response for Persian digits?), run live authentication test suites, or probe candidate passcodes (ara2026, ara۲۰۲۶, etc.) against live production authentication endpoints (https://ara.molavi.pro/api/auth/login) or prompt the user with interactive approval dialogs (Allow executing production login verification?, Allow verifying live production authentication suite?, Allow debugging response for Persian digits?). Test auth logic and Persian numeral handling locally with test clients.
• Zero Verbose SSH & IPQoS Diagnostic Probing: NEVER prompt the user asking "Allow testing SSH connectivity to hamzad_server?" or "Allow testing SSH connection with IPQoS=none?", and never run ssh -v or -o IPQoS=none probes. Fall back immediately to local workspace analysis and report connection status in the final summary.
• Zero Unprompted Live Test Script Seeking: NEVER prompt the user asking "Allow running live test?" or fire ad-hoc live test scripts (.venv/bin/python3 test_live_wake_flow.py) against live backend services without mocks. Validate integration flows and pipelines locally using mocks, or execute automated test suites directly without modal confirmation prompts in ANY project.
• Zero Remote WebSocket & Wake-Word Pipeline Probing via SSH: NEVER prompt the user asking "Allow testing WebSocket auth using venv python?", "Allow testing live wake-word and meeting WebSocket flow?" or run ssh commands (docker exec ... websockets.connect("ws://...")) or ad-hoc scripts (test_live_wake_flow.py) to probe WebSocket meeting routes, authentication tokens, or wake-word detection on remote production containers. Validate WebSocket connections and state transitions locally with mock transports.
• Zero Remote Microservice Endpoint Sweeping & Probing via SSH: NEVER run ssh commands (docker exec ... for path in ["/", "/api/v1", ...]: ...) to sweep, probe, or ping HTTP routes on remote microservices or containers. Discover endpoint paths and schemas statically from local codebase files and validate logic with local mock transports.
• Zero Ad-hoc Multi-File SCP Syncing & SSH Cat Redirection via SSH: NEVER run multi-file scp commands (scp -q app/... static/... server:/path/) or SSH cat piping (ssh server "cat > /path/file" < file) to copy or overwrite source files on remote servers. Commit code locally and restrict deployments to planned release workflows (deploy.sh).
• Zero Remote SSH Connection Retries, Uptime & Echo Probing via SSH: NEVER run ssh with retry/keepalive flags (-o ConnectTimeout=15, -o ServerAliveInterval=5) or run uptime and echo 'connection test ok' reachability probes. Fall back immediately to local workspace analysis and mocks.
• Zero Remote Compound Container & Git Status Probing via SSH: NEVER run compound ssh commands (docker ps ... && cd ... && git status -s) to inspect running container tables alongside remote git status. Inspect container configurations statically and git status locally in the workspace.
• Zero Remote Internal Service & Skill Probing via SSH: NEVER run docker exec ... httpx.get('.../api/v1/skills') to inspect internal service APIs or skills on remote containers. Inspect skills and registry files locally in the workspace.
• Zero Remote Container Build Directory Probing via SSH: NEVER run ssh ... docker exec molavi-pro-web ls -la /app/.next to check build folders inside remote containers. Verify Next.js build outputs locally with npm run build.
• Zero Ad-hoc SCP Component & File Copying to Server: NEVER run exploratory scp commands to copy individual components (Header.tsx, MobileMenu.tsx), pages (page.tsx), or SEO assets (robots.ts) directly to production server hosts. Commit code locally and use planned deployment workflows.
• Zero Remote Source Code & UI Component Probing via SSH: NEVER run ssh commands (cat /opt/.../components/MobileMenu.tsx, head, tail, less, grep) to read frontend components or source files on remote servers. Inspect all components and source code directly in the local workspace repository.
• Zero Remote STT Provider & API Key Probing via SSH: NEVER run ssh commands (docker exec ... python3 -c '... test_stt_providers() ...', checking GROQ_API_KEY) to test third-party providers or live keys on remote servers. Test integrations locally using mocked HTTP transports (httpx.MockTransport).
• Zero Unprompted SCP Deployments & Container Restarts via SSH: NEVER run ad-hoc scp commands or remote container restarts (docker restart) mid-discovery or mid-task. Treat deployments as deliberate actions and verify all changes locally first.
• Zero Remote Benchmark & Evaluation Execution via SSH: NEVER upload test scripts via scp or execute multi-prompt/multi-utterance evaluation suites (test_20_persian_utterances.py) on remote containers unprompted. Run evaluation suites locally with mock models and audio doubles.
• Zero Remote Health Endpoints, Container Logs & History Probing via SSH: NEVER run ssh commands to curl internal health endpoints (curl http://127.0.0.1:3050/api/health), tail container logs (docker logs --tail), inspect shell history (history | tail), or list host build directories (ls .next). Diagnose issues and inspect builds locally within the workspace.
• Zero Remote Speech-to-Text (STT) Probing via SSH: NEVER run remote SSH or container commands to benchmark speech-to-text latency or execute live audio transcription (STTService.transcribe_audio_bytes) on remote servers unprompted. Validate all STT services locally with async mocks.
• Zero Remote Deployment Manifest & Compose Probing via SSH: NEVER run ssh commands (cat /opt/.../docker-compose.yml, head, tail, less, grep) to read deployment configurations or compose files on remote servers. Inspect all deployment manifests and compose files directly in the local workspace repository.
• Zero Remote Container Filesystem Probing via SSH: NEVER run ssh or remote container commands (docker exec ... ls -la /app, find /app, cat /app/...) to inspect container directory trees. Inspect repository files and folder hierarchies directly in the local workspace.
• Zero Remote Package Upgrades via SSH: NEVER run ssh or remote container commands (pip install -U, pip install --upgrade, npm update, apt-get upgrade) to mutate running packages on remote hosts. Update dependencies deterministically in local manifests and verify locally.
• Zero Remote Container & Git Probing via SSH: NEVER run compound ssh commands (docker ps, git branch, git branch -a, git log, git status -s on remote hosts) to check server status or remote checkouts. Understand deployment statically from local files and inspect git status, branches, and commit logs locally in the workspace.
• Zero Remote Package & Dependency Probing: NEVER run ssh or remote container commands (pip show, pip list, pip freeze, npm list) to inspect installed packages on external servers. Inspect all dependencies statically from local repository manifests.
• Unpredicted States Momentum ("ادامه بده"): Never freeze mid-task when encountering unexpected edge cases; use safe fallbacks, finish all other work, and batch any remaining questions for the end.
• Zero Remote Source Code & Route Probing: NEVER run ssh or remote docker exec commands to read codebase files or grep router decorators (e.g. python3 -c "open('/workspace/...')"). Inspect all routes and models locally from the repository workspace.
• Zero Remote Voice / TTS Synthesis Benchmarking: NEVER run remote SSH or container commands to benchmark audio/voice synthesis latency or execute live TTS synthesis (TTSService.synthesize_chunk, testing updated Edge-TTS) on remote servers unprompted.
• Zero Unsolicited Live Model/API Probing: NEVER run live inference queries (/api/models/generate) or execute ad-hoc remote container commands (ssh ... "docker exec ... python3 -c '...' ") unprompted.
• Zero Unsolicited Remote/SSH Probing: NEVER run ssh, scp, rsync, or remote docker commands (docker ps, docker images, docker inspect) on external servers during discovery or development. Understand deployment statically by reading Dockerfile, compose.yaml, and CI configs.
• Zero Remote Port Probing: NEVER run port checks or endpoint pings via SSH (e.g. ssh server "curl ..."). Determine port mappings statically from docker-compose.yml, Dockerfile, and service configs.
• Zero Remote Git SSH Probing: NEVER run unsolicited remote Git/SSH authentication probes (e.g. ssh server "ssh -T git@github.com").
• Zero Live Route Probing: NEVER run live route crawlers or active HTTP endpoint scanners against public domains (e.g. curl https://...). Verify code deterministically via local builds (npm run build, cargo test, pytest) or local loopback servers (http://127.0.0.1:<port>).
• Canonical Git Commands Only: Stick strictly to high-level commands (git status, git diff, git log, git branch). NEVER run obscure repository plumbing (git count-objects, git fsck).
• Zero Global Config Tampering: NEVER attempt to modify global IDE configs, agent permission files (e.g., config.json), or files outside the workspace root. All project work must remain strictly self-contained within the repository.
• Sandbox Discipline: Run all commands inside the default sandbox without triggering permission confirmation modals unless the user explicitly requested remote operations.
• Batched Browser & OS Automation: When interacting with active browser sessions (Chrome, Safari, cPanel, cloud consoles via AppleScript/CDP), NEVER run multiple fragmented inline osascript -e or shell one-liners. Always write a self-contained helper script, run it once, and parse structured output cleanly.
• Batch Remote Operations: If the user explicitly asks for remote work or remote database queries, combine operations into a unified script instead of firing dozens of individual SSH commands that trigger confirmation prompts.
• Verification First: Always run existing lints, typechecks, and tests before and after making changes.

5. Mandatory First Response Protocol

On your first turn interacting with a new task or upon onboarding to this project, format your response using this structure:

## Understanding
[Summary of the repository purpose, architecture, runtime environment, and relevant domain patterns based on your discovery inspection.]

## Current State
[The current git branch, uncommitted working tree changes, active configuration, and relevant code modules related to the task.]

## Plan
[Step-by-step minimal implementation plan, including verification and testing strategy.]

## Blocking Questions
[None — or ONLY genuine blockers that cannot be resolved from codebase inspection.]

6. Completion Report Protocol

When completing a task, output a structured status summary:

STATUS:
PASS | PARTIAL | BLOCKED

CHANGES:
- <file_path_1>: Brief explanation of modification
- <file_path_2>: Brief explanation of modification

VALIDATION:
- <command_or_test_executed>: Result (e.g., `pnpm test` passed with 42 tests)

DEPLOYMENT:
- Clean working tree / branch status / readiness for commit

REMAINING:
- Any known edge cases, technical debt, or optional follow-up items

7. Project Specific Overrides (Fill In For Your Project)

• Primary Language & Runtime: e.g., TypeScript Node 20 / Go 1.22 / Python 3.12
• Package Manager: e.g., pnpm, uv, cargo
• Build Command: e.g., pnpm build
• Test Command: e.g., pnpm test
• Lint / Typecheck Command: e.g., pnpm lint && pnpm typecheck
• Critical Paths / Protected Areas: e.g., src/core/auth, migrations/