ajustes en docs generales

docs/09-mcp-tools-reference.md

@@ -97,7 +97,11 @@ Ver `06-hooks-and-cmsapi.md` para uso. Crear/editar el `.php` del hook se hace c
 | Tool | Acción | Notas |
 |------|--------|-------|
 | `generate_image` | Genera imagen con IA y la guarda en `cms/uploads/generated/` | Devuelve `dockerUrl` y `uploadUrl`/`fullUrl`. **En Forge prefiere `uploadUrl`/`fullUrl`** sobre `dockerUrl` para `upload_record_image` |
-| `upload_record_image` | Sube imagen a un campo de un registro | Necesita `tableName`, `recordId` (num), `fieldName` real (de relations o `uploadFields`) |
+| `upload_record_image` | Sube imagen a un campo `upload` de un registro | Necesita `tableName`, `recordId` (num), `fieldName` real (de `uploadFields` o `get_table_schema`). Sincroniza a producción si el proyecto está en modo prod |
+| `list_record_uploads` | Lista los uploads existentes de un campo de un registro | Devuelve cada upload con su `uploadId` (necesario para `replace`/`delete`/`reorder`) |
+| `replace_record_image` | Reemplaza un upload existente por uno nuevo | Necesita `uploadId` (de `list_record_uploads`). Borra el viejo + sube el nuevo, ambos con sync a producción |
+| `delete_record_upload` | Borra un upload concreto del campo | Necesita `uploadId`. Sincroniza el borrado a producción |
+| `reorder_record_uploads` | Cambia el orden de los uploads de un campo | Lista de `uploadIds` en el orden deseado |
 | `upload_image_to_assets` | Sube imagen a `/images/` del template (assets globales) | Acepta base64, data URI, URL. Permite resize/quality/format |
 
 ### Navegación
@@ -118,7 +122,8 @@ Ver `06-hooks-and-cmsapi.md` para uso. Crear/editar el `.php` del hook se hace c
 | Tool | Acción |
 |------|--------|
 | `list_git_log` | Lista los últimos commits para que el usuario elija un id de rollback |
-| (rollback) | Tool de rescate; pide confirmación al usuario |
+| `recover_previous_git` | Rollback rápido al commit anterior. Tool de rescate — pide confirmación al usuario antes de ejecutar |
+| `recover_git` | Rollback a un commit específico (por id, obtenido vía `list_git_log`). Pide confirmación al usuario |
 
 ### Autenticación
 
@@ -231,6 +236,27 @@ read_doc({ name: "05-tables-and-fields" })     // doc completo
 read_doc({ name: "06-hooks-and-cmsapi", section: "Hook middleware" })   // sección por heading H2
 ```
 
+### 11. Gestionar uploads existentes de un registro
+
+Cuando el usuario pide "cambia la imagen de la vacante 12", "borra la foto X de la galería", "reordena las imágenes" — **NO uses `upload_record_image` para reemplazar**: eso añade un upload nuevo encima sin tocar el viejo y deja basura. Usa el flow de gestión:
+
+```
+list_record_uploads({ tableName, recordId, fieldName })
+   → array de uploads, cada uno con su uploadId
+```
+
+Según lo que pida el usuario:
+
+- **Reemplazar** una imagen concreta: `replace_record_image({ tableName, recordId, fieldName, uploadId, imageUrl, alt? })` — borra el viejo + sube el nuevo, ambos con sync a producción.
+- **Borrar** una imagen: `delete_record_upload({ uploadId, table? })` — sync de borrado a producción.
+- **Reordenar**: `reorder_record_uploads({ tableName, recordId, fieldName, uploadIds: [...] })` con la lista en el orden deseado.
+
+Para AÑADIR un upload nuevo (sin reemplazar nada existente), usa `upload_record_image` directamente.
+
+Notas:
+- En modo producción todas estas tools sincronizan automáticamente con el servidor real (no solo modifican local).
+- Si solo tienes el `recordId` y necesitas saber qué `fieldName` tiene uploads, llama antes a `get_table_schema({ minimal: true })` y filtra los campos `type: "upload"`.
+
 ## Reglas globales para todas las tools
 
 1. **`tableName` siempre SIN prefijo `cms_`** (excepto en `queryDB` Twig y en el `middleWare` de `set_hook_middleware`).