# AGENTS.md - Context & Directives for AI Agents

This file defines the operating context for Sisyphus, OpenCode, and Gemini agents working on **Web Utils 2026**.

## 1. Core Philosophy: Client-Side First
**CRITICAL RULE:** Do NOT implement server-side logic for tasks that can be done in the browser.
- **Client-Side (Frontend):** Generators (UUID, Password), Formatters (JSON, XML), Encoders (Base64), Unit Converters.
- **Server-Side (Backend):** Image processing, Video manipulation, Heavy file conversion, scraping (if CORS blocked).

## 2. Architecture Constraints

### Backend (FastAPI)
- **Stateless:** NEVER store persistent user data.
- **File Handling:** ALWAYS use `app.core.cleanup` utils. Files must go to `backend/temp_uploads` and be cleaned up.
- **Registry:** New tools must be registered in `app.core.registry` to be visible to the frontend.

### Frontend (Vue 3)
- **State:** Use Vue Composition API (`<script setup lang="ts">`).
- **Styling:** Use Tailwind CSS utility classes. Avoid custom CSS files unless necessary.
- **API:** Use `axios` for backend communication.

## 3. Project Structure Awareness
- `backend/app/main.py`: Application entry point.
- `backend/app/tools/`: Where server-side tool logic resides.
- `frontend/src/views/`: Main pages.
- `frontend/src/components/`: Shared components.

## 4. Coding Standards

### Python (Backend)
- Use type hints for everything (Pydantic models).
- Follow PEP 8.
- Use `async def` for route handlers.

### TypeScript (Frontend)
- Strict mode enabled.
- No `any` types unless absolutely necessary (and commented).
- Use `<script setup>` syntax.

## 5. Deployment Context
- The project is designed to be containerizable.
- Frontend is served statically in production, but runs on Vite dev server during development.

## 6. Common Tasks & patterns
- **Adding a new Tool:**
    1. Determine if Frontend-only or Backend-required.
    2. If Backend: Create router in `backend/app/tools/`, register in `main.py` and `registry.py`.
    3. Frontend: Create view in `views/`, add route in `router/`.