# AGENTS.md

Guía para agentes de IA y colaboradores que trabajen en este repositorio.

## Proyecto

Utilidad para Windows que mueve el puntero del ratón solo tras un periodo de inactividad del
usuario y se detiene al detectar uso real. Ver `README.md`.

- `Mover.ps1`: implementación principal (PowerShell + C# embebido con `Add-Type`).
- `main.py`: implementación original en Python (`pyautogui`), mantenida como referencia.

## Normas

- Idioma: comentarios, documentación y mensajes en **castellano**.
- Toda función nueva debe llevar documentación (`<# .SYNOPSIS #>` en PowerShell,
  `/// <summary>` en C#, docstrings en Python). Actualizar la documentación al modificarlas.
- No modificar ficheros sin autorización previa del usuario.
- Registrar los cambios en `CHANGELOG.md` y las tareas pendientes en `TODO.md`.

## Particularidades técnicas

- **Codificación:** `Mover.ps1` debe mantenerse en **UTF-8 con BOM**; sin BOM, Windows
  PowerShell 5.1 lo lee como ANSI y corrompe las tildes. Tras editar, comprobar los primeros
  bytes (`239,187,191`).
- **Detección de actividad:** los movimientos propios actualizan `GetLastInputInfo`. Por eso se
  guarda `dwTime` tras cada movimiento y cualquier cambio posterior se interpreta como uso real.
  No romper este mecanismo.
- **Instancias:** el script cierra al arrancar otras instancias que ejecuten `Mover.ps1` con
  `-File`. Durante las pruebas no dejar instancias huérfanas.
- **Movimiento:** se usa `SendInput` con `MOUSEEVENTF_ABSOLUTE | MOUSEEVENTF_VIRTUALDESK` para
  evitar la aceleración del puntero y soportar varios monitores.
- `Add-Type` puede tardar ~20 s en un proceso nuevo; no confundir con un bloqueo.

## Validación

```powershell
# Sintaxis
$err=$null; [System.Management.Automation.Language.Parser]::ParseFile('Mover.ps1',[ref]$null,[ref]$err) | Out-Null; $err.Count
# Prueba funcional rápida
powershell -ExecutionPolicy Bypass -File .\Mover.ps1 -TiempoInactividad 10
# Python
python -m py_compile main.py
```