# web_mycode — instrucciones para agentes

**Antes de escribir o modificar código**, lee y aplica
[`docs/arquitectura-mvvm-solid-clean.md`](docs/arquitectura-mvvm-solid-clean.md) (sección *Guía para agentes*).

## Reglas obligatorias (resumen)

| Métrica | Límite |
|---------|--------|
| Líneas por archivo PHP / Blade / chunk JS admin | **≤ 150** (objetivo) |
| Límite duro | **> 250** → dividir antes de terminar |
| `panel.blade.php` | Solo shell (~≤ 80 líneas), sin CSS ni `<script>` inline |
| Controladores nuevos | `app/Presentation/Http/Controllers/{Web\|Bridge\|Admin}/` |
| Lógica de negocio / API | `Application/` + `Infrastructure/`, no en Blade ni controllers gordos |

### Dónde colocar código nuevo

| Tarea | Ubicación |
|-------|-----------|
| Ruta web / JSON bridge | `routes/web.php` o `routes/api.php` → controller en `Presentation/Http/Controllers/` |
| Caso de uso / orquestación | `app/Application/{Context}/` (handler, resolver, renderer) |
| Entidades, permisos, reglas puras | `app/Domain/` (sin `Illuminate\*`) |
| HTTP a api.mycode.cl, repos | `app/Infrastructure/Http/` |
| Datos para Blade | `app/Presentation/ViewModels/` + factory |
| Panel admin (JS) | `resources/js/admin/` (chunks ≤ 150 líneas) → recompilar `public/js/admin/app.js` con `npm run production` |
| Estilos panel admin | `public/css/admin-panel.css` |

### Seguridad del panel admin (obligatorio)

- Login solo por `POST /admin/session/login` (sesión Laravel + CSRF), **nunca** por `localStorage` ni `POST /api/bridge/admin/login`.
- Token JWT de admin solo en **sesión servidor**; el bridge lee el token de la sesión, no del header enviado por el cliente.
- Rutas `/admin/*` (excepto `/admin/login` y session login/status) requieren middleware `admin.web`.

### Prohibido (rompe arquitectura)

- Crear o reactivar clases en `app/Http/Controllers/` (excepto `ContactController` legacy).
- Añadir CSS o JavaScript inline en `resources/views/admin/panel.blade.php`.
- Poner lógica de negocio en Blade o en strings HTML generados sin pasar por ViewModel/handler.
- Extender `adminProxy()` con cadenas de `if` por ruta; usar `AdminProxyPayloadResolver` o handler dedicado.
- Importar `Illuminate\*` desde `app/Domain/`.
- Archivos monolíticos que superen 150 líneas sin dividir.
- Shims `@deprecated` que solo extienden otra clase (eliminar y apuntar rutas a `Presentation`).
- Guardar `admin_token` en `localStorage` o usar `POST /api/bridge/admin/login` para login.

### Validación antes de dar por terminada una tarea

Ejecutar en la raíz del repo:

```bash
php artisan architecture:audit --strict
php artisan test
```

Si falla el audit, corregir antes de responder al usuario.

### Referencias

- Arquitectura completa: [`docs/arquitectura-mvvm-solid-clean.md`](docs/arquitectura-mvvm-solid-clean.md)
- Permisos admin / API: [`docs/admin-superadmin.md`](docs/admin-superadmin.md)

---

<!-- code-review-graph MCP tools -->
## MCP Tools: code-review-graph

**IMPORTANT: This project has a knowledge graph. ALWAYS use the
code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore
the codebase.** The graph is faster, cheaper (fewer tokens), and gives
you structural context (callers, dependents, test coverage) that file
scanning cannot.

### When to use graph tools FIRST

- **Exploring code**: `semantic_search_nodes` or `query_graph` instead of Grep
- **Understanding impact**: `get_impact_radius` instead of manually tracing imports
- **Code review**: `detect_changes` + `get_review_context` instead of reading entire files
- **Finding relationships**: `query_graph` with callers_of/callees_of/imports_of/tests_for
- **Architecture questions**: `get_architecture_overview` + `list_communities`

Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need.

### Key Tools

| Tool | Use when |
|------|----------|
| `detect_changes` | Reviewing code changes — gives risk-scored analysis |
| `get_review_context` | Need source snippets for review — token-efficient |
| `get_impact_radius` | Understanding blast radius of a change |
| `get_affected_flows` | Finding which execution paths are impacted |
| `query_graph` | Tracing callers, callees, imports, tests, dependencies |
| `semantic_search_nodes` | Finding functions/classes by name or keyword |
| `get_architecture_overview` | Understanding high-level codebase structure |
| `refactor_tool` | Planning renames, finding dead code |

### Workflow

1. The graph auto-updates on file changes (via hooks).
2. Use `detect_changes` for code review.
3. Use `get_affected_flows` to understand impact.
4. Use `query_graph` pattern="tests_for" to check coverage.