web-utils/AGENTS.md

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/.