orquestra-mcp 1.7.2 → 1.8.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "orquestra-mcp",
-  "version": "1.7.2",
-  "description": "Servidor MCP de Orquestra -- 51 tools para leer y escribir tareas, ideas, changelog, infraestructura, contenido, QA y más desde un agente de IA",
+  "version": "1.8.0",
+  "description": "Servidor MCP de Orquestra -- 69 tools para leer y escribir tareas, ideas, changelog, infraestructura, contenido, QA y más desde un agente de IA",
   "type": "module",
   "bin": {
     "orquestra-mcp": "./bin/orquestra-mcp.mjs"

package/src/api.mjs

@@ -89,3 +89,16 @@ export async function apiPatch(config, path, { projectId, id, ...body }) {
   })
   return parseResponse(res)
 }
+
+// Único método DELETE del cliente (21 ago 2026, para delete_checklist_item
+// -- ver CLAUDE.md, "único delete_* real de la API/MCP"). Mismo shape que
+// apiPatch (arma la URL como `${path}/${id}`), sin body -- ningún delete de
+// esta API necesita mandar datos, solo identificar el recurso.
+export async function apiDelete(config, path, { projectId, id }) {
+  const url = buildUrl(config, `${path}/${id}`, { projectId })
+  const res = await fetch(url, {
+    method: 'DELETE',
+    headers: { Authorization: `Bearer ${config.apiToken}` },
+  })
+  return parseResponse(res)
+}

package/src/server.mjs

@@ -1,6 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { z } from 'zod'
-import { loadConfig, apiGet, apiPost, apiPatch, ApiError } from './api.mjs'
+import { loadConfig, apiGet, apiPost, apiPatch, apiDelete, ApiError } from './api.mjs'
 import { STAGES, PLAYBOOKS } from './stages.mjs'
 
 function errorResult(err) {
@@ -17,8 +17,19 @@ const PROJECT_ID_DESC = 'ID del proyecto dentro del workspace configurado. Si ha
 const TASK_TYPES = ['feature', 'bug', 'improvement', 'tech', 'docs', 'idea', 'design', 'security', 'meeting', 'call', 'followup', 'business']
 const TASK_PRIORITIES = ['high', 'medium', 'low']
 const CHANGELOG_SECTIONS = ['Added', 'Changed', 'Deprecated', 'Removed', 'Fixed', 'Security']
-const DOC_TYPES = ['readme', 'usecase', 'diagram', 'env', 'adr', 'runbook', 'api']
+// 'postmortem' faltaba acá (gap preexistente, encontrado 12 ago 2026) --
+// mismo fix del lado de write.mjs en orquestra-infra.
+const DOC_TYPES = ['readme', 'usecase', 'diagram', 'env', 'adr', 'runbook', 'postmortem', 'api']
 const ADR_STATUSES = ['propuesto', 'aceptado', 'deprecado', 'rechazado']
+const DOC_FOLDERS = ['arquitectura', 'api', 'operaciones', 'decisiones']
+const DOC_VISIBILITY = ['team', 'workspace', 'public']
+// 'hecha' agregado 12 ago 2026 -- ver misma nota en write.mjs de
+// orquestra-infra (convertToTask ya no borra la idea, la deja en 'hecha').
+const IDEA_STATUSES = ['nueva', 'en_estudio', 'planeada', 'hecha', 'en_espera', 'descartada']
+const IDEA_ORIGINS = ['cliente', 'soporte', 'equipo', 'ventas']
+const IDEA_IMPACT_EFFORT = ['alto', 'bajo']
+const NOTE_TYPES = ['decision', 'incidente', 'cliente', 'planificacion']
+const NOTE_VISIBILITY = ['team', 'private']
 const SERVICE_TYPES = ['backend', 'database', 'auth', 'storage', 'push', 'email', 'payments', 'analytics', 'realtime', 'search', 'maps', 'flags', 'admin', 'cdn', 'queue']
 const PLATFORM_TYPES = ['android', 'ios', 'web', 'desktop-mac', 'desktop-win', 'backend', 'extension', 'other']
 const INFRA_STATUSES = ['operational', 'degraded', 'down']
@@ -32,9 +43,9 @@ const SETUP_GUIDE = {
     { step: 3, section: 'Infraestructura', check: 'list_services / list_environments / list_distributions (o get_infra_status para los 3 juntos)', createOrUpdate: 'create_service|environment|distribution / update_*', matchBy: 'name (o type para servicios/distribuciones)' },
     { step: 4, section: 'Módulos', check: 'list_modules', createOrUpdate: 'create_module / update_module', matchBy: 'name', dependsOn: ['statusId (paso 1)', 'categoryId (paso 2)'] },
     { step: 5, section: 'Tareas', check: 'list_tasks', createOrUpdate: 'create_task / update_task', matchBy: 'title', dependsOn: ['statusId', 'categoryId', 'moduleId'] },
-    { step: 6, section: 'Ideas', check: 'search', createOrUpdate: 'create_idea (sin update_idea todavía)', matchBy: 'title' },
+    { step: 6, section: 'Ideas', check: 'search', createOrUpdate: 'create_idea / update_idea / convert_idea_to_task', matchBy: 'title' },
     { step: 7, section: 'Notas', check: 'search', createOrUpdate: 'create_note (sin update_note todavía)', matchBy: 'title' },
-    { step: 8, section: 'Changelog', check: 'get_dashboard_summary (recent.changelog) o search', createOrUpdate: 'create_changelog_entry (sin update todavía)', matchBy: 'text' },
+    { step: 8, section: 'Changelog', check: 'list_changelog', createOrUpdate: 'create_changelog_entry / update_changelog_entry', matchBy: 'text' },
     { step: 9, section: 'Docs', check: 'search', createOrUpdate: 'create_doc (sin update_doc todavía)', matchBy: 'title' },
   ],
 }
@@ -56,12 +67,14 @@ Si get_project_context devuelve un proyecto vacío (sin módulos ni tareas), es
 
 Durante el trabajo normal de código, sin que el usuario te lo pida explícitamente y SIN ESPERAR a que lo mencione (si tienes esta tool disponible en la sesión, se usa por default en todo trabajo real, no solo cuando alguien dice "usa Orquestra"):
 - Si te pide una funcionalidad o arreglo real (no una pregunta rápida ni exploración de código sin cambios), revisa con list_tasks/search si ya existe una tarea relacionada; si no, créala con create_task ANTES de empezar a trabajar, en el estatus inicial del proyecto (ver list_statuses). Si no hay un proyecto default configurado para esta carpeta, no te rindas ahí -- usa get_workspace_summary para encontrar el proyecto correcto y pásalo explícito como projectId en cada llamada.
-- Mientras trabajas, mueve la tarea por los estatus reales según avanzas (no la dejes en el inicial hasta el final). Al terminar, muévela a su estatus final con update_task y registra una entrada de changelog con create_changelog_entry -- así el usuario nunca tiene que documentar esto a mano.
+- Mientras trabajas, mueve la tarea por los estatus reales según avanzas (no la dejes en el inicial hasta el final). Al terminar, muévela a su estatus final con update_task y registra una entrada de changelog con create_changelog_entry -- así el usuario nunca tiene que documentar esto a mano. Si sabes en qué repo real estás trabajando (podés correr "git remote get-url origin" o ya lo sabes por la carpeta), pásalo SIEMPRE como "repo" ("owner/name") -- encontrado real (17 ago 2026): ni el hook local ni el GitHub Action ni la reconciliación de orquestra-infra lo estaban mandando pese a que el campo existe hace rato, así que ninguna entrada automática sabía de qué repo/plataforma venía. Si además la distribución de ese repo ya está identificada (ver list_distributions), pásala en "distributions" -- sin esto el changelog no puede filtrar/agrupar por plataforma.
 - Todo cambio de statusId vía update_task valida la transición (nextIds) y queda en el historial de la tarea -- pero ese historial no dice nada por sí solo. Manda SIEMPRE el parámetro "comment" cuando cambies statusId, explicando qué hiciste o por qué -- sin esto, el usuario ve que la tarea cambió pero no sabe por qué ni qué se hizo de verdad (encontrado real: quedaba invisible, a diferencia de cuando un humano mueve la tarjeta a mano en el kanban).
 - Antes de crear un módulo/estatus/categoría/servicio/entorno/distribución, revisa con el list_* correspondiente que no exista ya uno con ese nombre.
 - Si una nota que vas a crear (create_note) es claramente sobre un módulo o una tarea específica -- por ejemplo durante un setup guiado donde acabas de crear ambos -- mándale moduleId/taskId para ligarla, en vez de dejarla suelta. No inventes la relación si no es clara.
+- create_changelog_entry SIEMPRE deja la entrada en Unreleased (nunca mandes version salvo que el usuario te haya dado un número real) -- cortar una versión es release_changelog_version, una acción DELIBERADA que solo se llama si el usuario la pide explícitamente ("cortá la versión", "hacé el release de X") o confirma un número/fecha real que vos propusiste. No la dispares solo porque terminaste una tarea o un lote de trabajo grande.
 - Si tienes acceso al repo real de una distribución (ej. puedes correr "git remote get-url origin" en ese código), llena repoUrl en create_distribution/update_distribution sin preguntar -- es solo informativo, no requiere credenciales. Esto es distinto de conectar el repo con PAT para el changelog automático (Workspace → Conexiones en orquestra-web): eso sí es un paso deliberado del usuario, con una credencial real -- nunca lo hagas tú solo ni sugieras que ya está conectado por haber llenado repoUrl.
 - Al crear o editar una tarea (o un módulo), llena TODO campo para el que tengas un dato real, no solo title/moduleId/dueDate/comment: type (no lo dejes en el default "feature" si en realidad es un bug/mejora/doc/etc.), tags, stack (tecnologías que genuinamente tocaste), scope (paridad multiplataforma, si aplica), y los campos de código (branch/prNumber/prUrl/prStatus/commitCount/resolvedCommitSha/resolvedCommitMessage/resolvedCommitUrl/resolvedCommitAt) cuando de verdad sepas esos valores (el branch en el que estás trabajando, el PR que abriste, el commit que resolvió la tarea). No dejes un campo en blanco solo porque no es obligatorio -- pero esto no es licencia para inventar: si no tenés el dato real (ej. no hay branch/PR porque el proyecto commitea directo a main), dejalo vacío en vez de rellenarlo con algo plausible pero falso -- mismo criterio que ya se pedía para resolvedCommitSha.
+- Si una tarea tiene más de una actividad o paso concreto, no los amontones como texto corrido en description -- usa el checklist (add_checklist_item, un ítem por actividad, opcionalmente con responsable) para que cada paso se pueda marcar independientemente. description queda para el contexto/propósito general de la tarea (el qué y el por qué), no como lista de pasos. Si estás editando una tarea existente cuya description ya creció así, migra esos puntos a checklist en vez de seguir agregando ahí.
 - No todas las tareas necesitan una corrida de QA -- clasifica antes de disparar una: cambios que afectan comportamiento real (features, bugs, UI, lógica de negocio, endpoints/API) sí la necesitan; cambios que no alteran comportamiento (docs, comentarios, refactors sin cambio funcional, config/tooling interno, notas/reuniones/ideas) no. Si decides que sí, revisa primero con list_qa_agents que exista un agente para el stack que tocaste (si no hay ninguno, créalo con create_qa_agent -- necesita una máquina ya emparejada, ver Workspace → QA) y llama a create_qa_run en la rama real de ese trabajo (manda taskId si el trabajo era de una tarea puntual -- si el agente tiene la revisión con IA activada, la acota a eso en vez de "revisa todo el proyecto"), dejando la tarea en "En revisión" -- NUNCA la muevas a "Listo" ni digas que "QA lo revisó" sin haber confirmado con get_qa_run un estatus terminal "passed" de verdad (las corridas son asíncronas, tardan minutos en otra máquina). Si tarda, dile al usuario que quedó en cola (con el runId) y que confirmas cuando termine -- no lo des por hecho nunca.
 
 Si el usuario pide "sincronizar"/"revisar que todo esté al día"/"verificar el proyecto" (o algo equivalente -- una auditoría manual, no el trabajo normal de arriba), hacé una "revisión de sincronización" completa, de cero, no un vistazo rápido:
@@ -157,9 +170,26 @@ export function createServer() {
   registerRead(
     'list_tasks',
     '/v1/tasks',
-    'Lista las tareas de un proyecto de Orquestra, opcionalmente filtradas por estatus.',
-    { statusId: z.string().optional().describe('ID de estatus para filtrar (opcional)') },
-    (args, projectId) => ({ projectId, statusId: args.statusId })
+    'Lista las tareas de un proyecto de Orquestra, opcionalmente filtradas por estatus/módulo/tipo/prioridad/responsable/tag. Los filtros se combinan con AND -- pásalos en vez de traer todo el proyecto y filtrar tú mismo del lado del cliente. Por default excluye tareas cerradas (isFinal/isCancel/isArchive) -- un proyecto con historial acumula cientos, traerlas todas revienta el contexto sin que nadie las haya pedido. Si mandas statusId puntual, eso ya es una elección explícita y no se le suma este filtro (podés pedir "solo Listo"). Para historial/auditoría real, usa includeClosed=true.',
+    {
+      statusId: z.string().optional().describe('ID de estatus para filtrar (opcional) -- pedir un estatus puntual (incluso uno cerrado) siempre se respeta tal cual, sin el filtro default de abiertas'),
+      moduleId: z.string().optional().describe('ID de módulo para filtrar (opcional)'),
+      type: z.enum(TASK_TYPES).optional().describe('Tipo de tarea para filtrar (opcional)'),
+      priority: z.enum(TASK_PRIORITIES).optional().describe('Prioridad para filtrar (opcional)'),
+      assignedTo: z.string().optional().describe('uid del responsable para filtrar (opcional)'),
+      tag: z.string().optional().describe('Un tag exacto para filtrar -- solo uno, no una lista (opcional)'),
+      includeClosed: z.boolean().optional().describe('Default false -- sin esto, tareas en un estatus isFinal/isCancel/isArchive quedan afuera. Ponelo en true solo si de verdad necesitás el historial cerrado (auditoría, "¿cuándo se hizo X?").'),
+    },
+    (args, projectId) => ({
+      projectId,
+      statusId: args.statusId,
+      moduleId: args.moduleId,
+      type: args.type,
+      priority: args.priority,
+      assignedTo: args.assignedTo,
+      tag: args.tag,
+      includeClosed: args.includeClosed,
+    })
   )
 
   registerRead(
@@ -293,7 +323,7 @@ export function createServer() {
   registerCreate(
     'create_task',
     '/v1/tasks',
-    'Crea una tarea en un proyecto de Orquestra. moduleId es OBLIGATORIO -- revisa list_modules primero; si ninguno aplica, creá uno con create_module antes de crear la tarea (nunca la dejes sin agrupar).',
+    'Crea una tarea en un proyecto de Orquestra. moduleId y dueDate son OBLIGATORIOS -- revisa list_modules primero (si ninguno aplica, creá uno con create_module antes de crear la tarea, nunca la dejes sin agrupar); dueDate se calcula con criterio real (prioridad/tamaño del trabajo), nunca un valor arbitrario.',
     {
       title: z.string().describe('Título de la tarea'),
       description: z.string().optional(),
@@ -302,7 +332,7 @@ export function createServer() {
       statusId: z.string().optional().describe('Default: el primer estatus del proyecto'),
       categoryId: z.string().optional(),
       moduleId: z.string().describe('OBLIGATORIO -- módulo al que pertenece esta tarea, para poder agruparla/revisarla después. Si no existe uno relacionado, llamá primero a list_modules (para no duplicar) y create_module.'),
-      dueDate: z.string().optional().describe('YYYY-MM-DD'),
+      dueDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Formato esperado: YYYY-MM-DD').describe('OBLIGATORIO -- fecha estimada de término (YYYY-MM-DD), calculada con criterio real según prioridad/tamaño del trabajo (mismo criterio que la "revisión de sincronización" de get_sync_report), nunca un valor arbitrario.'),
       assignedTo: z.string().optional().describe('uid del miembro asignado'),
       tags: z.array(z.string()).optional(),
       scope: z.array(z.object({ distId: z.string(), layer: z.string().optional(), done: z.boolean() })).optional()
@@ -359,6 +389,52 @@ export function createServer() {
     }
   )
 
+  // Fusionar tareas (20 ago 2026) -- registradas directo con
+  // server.registerTool (no registerCreate/registerUpdate) porque son
+  // POST a `${path}/${id}/merge|unmerge`, no un CRUD estándar. Fusión
+  // SIEMPRE blanda -- ver mergeTask/unmergeTask en write.mjs (orquestra-infra)
+  // y mergeTask/unmergeTask en useAppStore.js (orquestra-web) para la
+  // contraparte real: nunca copia ni borra checklist/comentarios, solo
+  // enlaza mergedIntoId y saca la tarea fusionada de las vistas activas.
+  server.registerTool(
+    'merge_task',
+    {
+      description: 'Fusiona una tarea duplicada dentro de otra ("blanda": nunca copia ni borra checklist/comentarios de ninguna de las dos -- solo enlaza taskId a targetId y saca a taskId de las vistas activas, mismo criterio que una tarea cerrada). Reversible con unmerge_task. targetId es la que sobrevive -- si no estás seguro de cuál de las dos conviene mantener, usa list_tasks/get_project_context para comparar antes (ej. más checklist/comentarios/historial suele ser la "buena").',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        taskId: z.string().describe('Tarea que se fusiona -- queda enlazada y oculta de las vistas activas'),
+        targetId: z.string().describe('Tarea destino que sobrevive'),
+      },
+    },
+    async ({ projectId, taskId, targetId }) => {
+      try {
+        const data = await apiPost(config, `/v1/tasks/${taskId}/merge`, { projectId: resolveProjectId(projectId), targetId })
+        return textResult(data)
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  server.registerTool(
+    'unmerge_task',
+    {
+      description: 'Deshace una fusión hecha con merge_task -- limpia mergedIntoId/mergedAt/mergedBy de taskId, que vuelve a aparecer en las vistas activas.',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        taskId: z.string().describe('Tarea fusionada a "des-fusionar"'),
+      },
+    },
+    async ({ projectId, taskId }) => {
+      try {
+        const data = await apiPost(config, `/v1/tasks/${taskId}/unmerge`, { projectId: resolveProjectId(projectId) })
+        return textResult(data)
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
   // Checklist de una tarea -- registradas directo con server.registerTool
   // (no con registerCreate/registerUpdate) porque su ruta necesita DOS ids
   // dinámicos (taskId + itemId del checklist), y esos helpers solo arman
@@ -426,6 +502,58 @@ export function createServer() {
     }
   )
 
+  // Único delete_* real de la API/MCP (21 ago 2026, decisión consciente de
+  // José de romper "Escritura = creación + edición, nunca borrado" -- ver
+  // gotcha abajo en CLAUDE.md) -- acotado a un sub-ítem de checklist, nunca
+  // a una entidad de nivel top. Existe porque convert_checklist_item_to_task
+  // (justo abajo) necesita replicar el mismo comportamiento que
+  // convertChecklistItemToTask en useAppStore.js: crea la tarea Y borra el
+  // ítem origen, sin dejar ningún vínculo entre ambos (a diferencia de
+  // convert_idea_to_task, que sí liga con taskId).
+  server.registerTool(
+    'delete_checklist_item',
+    {
+      description: 'Borra un ítem del checklist de una tarea de Orquestra. Único borrado real que expone este MCP -- usalo solo cuando de verdad no tiene sentido dejar rastro (ej. como parte de convert_checklist_item_to_task); para "ya no aplica" en general, preferí marcarlo done en vez de borrarlo si querés conservar el historial.',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        taskId: z.string().describe('ID de la tarea'),
+        itemId: z.string().describe('ID del ítem del checklist a borrar'),
+      },
+    },
+    async ({ projectId, taskId, itemId }) => {
+      try {
+        const data = await apiDelete(config, `/v1/tasks/${taskId}/checklist`, { projectId: resolveProjectId(projectId), id: itemId })
+        return textResult(data)
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  server.registerTool(
+    'convert_checklist_item_to_task',
+    {
+      description: 'Convierte un ítem del checklist de una tarea en una tarea nueva independiente -- crea la tarea (hereda moduleId/categoryId/scope de la tarea padre, y assignedTo del ítem si tenía responsable) y BORRA el ítem origen del checklist, sin dejar ningún vínculo entre ambos (a diferencia de convert_idea_to_task, que sí liga con taskId -- mismo comportamiento que convertChecklistItemToTask en la web). Igual que create_task, moduleId real es obligatorio (de la tarea padre o de este llamado) y dueDate también -- la web lo deja vacío pero este canal no.',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        taskId: z.string().describe('Tarea dueña del ítem'),
+        itemId: z.string().describe('Ítem del checklist a convertir (ver list_checklist_items)'),
+        moduleId: z.string().optional().describe('Solo si la tarea padre no tiene moduleId propio.'),
+        dueDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Formato esperado: YYYY-MM-DD').describe('Obligatorio -- la tarea padre no tiene una fecha que heredar para este ítem, calculala con criterio real.'),
+      },
+    },
+    async ({ projectId, taskId, itemId, moduleId, dueDate }) => {
+      try {
+        const data = await apiPost(config, `/v1/tasks/${taskId}/checklist/${itemId}/convert-to-task`, {
+          projectId: resolveProjectId(projectId), moduleId, dueDate,
+        })
+        return textResult(data)
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
   registerCreate(
     'create_idea',
     '/v1/ideas',
@@ -433,12 +561,197 @@ export function createServer() {
     {
       title: z.string().describe('Título de la idea'),
       description: z.string().optional(),
-      priority: z.enum(TASK_PRIORITIES).optional().describe('Default: medium'),
+      priority: z.enum(TASK_PRIORITIES).optional().describe('Default: medium -- se puede derivar de impact+effort si los mandas (alto+bajo→high, alto+alto o bajo+bajo→medium, bajo+alto→low).'),
       categoryId: z.string().optional(),
       dueDate: z.string().optional().describe('YYYY-MM-DD'),
+      moduleId: z.string().optional(),
+      status: z.enum(IDEA_STATUSES).optional().describe('Default: nueva. "hecha" es a dónde llega una idea convertida en tarea (ver convertToTask en la web) -- no la mandes vos al crear, no tiene sentido crear una idea ya "hecha".'),
+      origin: z.enum(IDEA_ORIGINS).optional(),
+      requestedBy: z.array(z.object({
+        name: z.string().describe('Nombre del cliente, en texto libre (no hay entidad "cliente" en Orquestra)'),
+        quote: z.string().optional().describe('Cita textual de por qué lo pidió, si la tenés'),
+      })).optional().describe('Quién pidió esta idea -- cada uno suma +1 a voteCount. `requestedAt` se estampa solo, server-side, no lo mandes.'),
+      impact: z.enum(IDEA_IMPACT_EFFORT).optional(),
+      effort: z.enum(IDEA_IMPACT_EFFORT).optional(),
+      risk: z.enum(IDEA_IMPACT_EFFORT).optional().describe('Riesgo de esta idea (alto/bajo) -- agregado 12 ago 2026, alimenta la recomendación del detalle de idea junto con impact/effort.'),
+      voteCount: z.number().optional().describe('Default: 1 + requestedBy.length'),
+      linkedTaskIds: z.array(z.string()).optional().describe('Tareas YA EXISTENTES relacionadas con esta idea (no creadas a partir de ella) -- ver list_tasks. Distinto de taskId (la tarea "principal"/de conversión, que solo se setea vía convert_idea_to_task): acá pueden ser varias. Reemplaza el array completo si ya tenía algo, no hace merge.'),
+    }
+  )
+
+  registerUpdate('update_idea', '/v1/ideas', 'Edita una idea existente. Todos los campos son opcionales -- solo se cambian los que mandes.', {
+    title: z.string().optional(),
+    description: z.string().optional(),
+    priority: z.enum(TASK_PRIORITIES).optional(),
+    categoryId: z.string().optional(),
+    dueDate: z.string().optional().describe('YYYY-MM-DD'),
+    moduleId: z.string().optional(),
+    status: z.enum(IDEA_STATUSES).optional().describe('Para marcarla "hecha" a mano preferí convert_idea_to_task (hace las dos cosas -- crea la tarea Y marca la idea -- de una sola vez y queda enlazada con taskId). Usá esto solo si querés cambiar el status sin convertirla (ej. "descartada").'),
+    origin: z.enum(IDEA_ORIGINS).optional(),
+    requestedBy: z.array(z.object({
+      name: z.string().describe('Nombre del cliente, en texto libre (no hay entidad "cliente" en Orquestra)'),
+      quote: z.string().optional().describe('Cita textual de por qué lo pidió, si la tenés'),
+    })).optional().describe('Reemplaza la lista completa (no agrega un elemento suelto) -- `requestedAt` se estampa solo, server-side, no lo mandes.'),
+    impact: z.enum(IDEA_IMPACT_EFFORT).optional(),
+    effort: z.enum(IDEA_IMPACT_EFFORT).optional(),
+    risk: z.enum(IDEA_IMPACT_EFFORT).optional(),
+    voteCount: z.number().optional(),
+    linkedTaskIds: z.array(z.string()).optional().describe('Tareas YA EXISTENTES relacionadas con esta idea (no creadas a partir de ella) -- ver list_tasks. Distinto de taskId (la tarea "principal"/de conversión, que solo se setea vía convert_idea_to_task): acá pueden ser varias. Reemplaza el array completo, no hace merge -- si querés agregar una sin perder las que ya tenía, primero mirá la idea con search/get_project_context.'),
+  })
+
+  // Convertir idea → tarea (21 ago 2026, gap encontrado: no había forma de
+  // hacer por MCP lo que la web ya hace en handleConvertTask de
+  // IdeaDetail.jsx). Compuesta -- POST /v1/ideas/{id}/convert-to-task en
+  // orquestra-infra crea la tarea (reusando createTask tal cual, mismas
+  // reglas que create_task) Y marca la idea 'hecha' con taskId enlazado,
+  // las dos cosas en un solo paso server-side. La idea NUNCA se borra --
+  // queda trazable, mismo criterio que la web. No se puede convertir una
+  // idea que ya tiene taskId (falla con un error claro).
+  //
+  // moduleId/dueDate son opcionales acá PERO create_task (por debajo)
+  // sigue exigiendo los dos reales -- si la idea no los tiene seteados,
+  // hay que mandarlos en esta llamada con el mismo criterio real de
+  // create_task (nunca fabricados). Si la idea sí los tiene, no hace falta
+  // repetirlos.
+  server.registerTool(
+    'convert_idea_to_task',
+    {
+      description: 'Convierte una idea en una tarea real -- crea la tarea (mismas reglas que create_task: moduleId y dueDate son obligatorios, de la idea o de este llamado) y marca la idea "hecha" con un taskId enlazado, sin borrarla. No se puede convertir una idea que ya fue convertida antes.',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        ideaId: z.string().describe('Idea a convertir -- usá search para encontrar su id (las ideas no tienen su propio list_ideas todavía)'),
+        moduleId: z.string().optional().describe('Solo si la idea no tiene moduleId propio -- si no existe uno relacionado, revisá list_modules/create_module primero.'),
+        dueDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Formato esperado: YYYY-MM-DD').optional().describe('Solo si la idea no tiene dueDate propio -- calculado con criterio real, no un valor arbitrario.'),
+      },
+    },
+    async ({ projectId, ideaId, moduleId, dueDate }) => {
+      try {
+        const data = await apiPost(config, `/v1/ideas/${ideaId}/convert-to-task`, {
+          projectId: resolveProjectId(projectId), moduleId, dueDate,
+        })
+        return textResult(data)
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  // Comentarios de ideas (21 ago 2026, a pedido de José) -- el modelo y la
+  // UI YA existían del lado web (ideas/{id}/comments, mismo shape que
+  // comentarios de tareas), pero nunca tuvieron ruta HTTP -- un agente MCP
+  // no podía leer ni sumar contexto/objeciones a una idea. Registradas
+  // directo con server.registerTool (no registerRead/registerCreate)
+  // porque la ruta cuelga de `ideaId`, no de un `id` genérico al final.
+  server.registerTool(
+    'list_idea_comments',
+    {
+      description: 'Lista los comentarios de una idea de Orquestra, en orden cronológico.',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        ideaId: z.string().describe('Idea -- usá search para encontrar su id'),
+      },
+    },
+    async ({ projectId, ideaId }) => {
+      try {
+        const data = await apiGet(config, `/v1/ideas/${ideaId}/comments`, { projectId: resolveProjectId(projectId) })
+        return textResult(data)
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  server.registerTool(
+    'add_idea_comment',
+    {
+      description: 'Agrega un comentario a una idea de Orquestra -- para sumar contexto, una objeción, o el resultado de investigarla, sin tener que convertirla en tarea para dejar rastro.',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        ideaId: z.string().describe('Idea -- usá search para encontrar su id'),
+        text: z.string().describe('Texto del comentario'),
+        authorName: z.string().optional().describe('Default "IA" -- solo cambialo si el comentario es una cita textual de otra persona, no lo tuyo.'),
+      },
+    },
+    async ({ projectId, ideaId, text, authorName }) => {
+      try {
+        const data = await apiPost(config, `/v1/ideas/${ideaId}/comments`, { projectId: resolveProjectId(projectId), text, authorName })
+        return textResult(data)
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  // Sugerencias de IA (21 ago 2026, gap encontrado a pedido de José: el MCP
+  // no tenía NINGUNA tool relacionada con `suggestions` -- un agente ni
+  // podía leer qué había pendiente (reescrituras de changelog, tareas que
+  // avanzaron/cerraron por evidencia, hallazgos de QA, gaps de setup/
+  // contenido/publicidad, fusiones de tareas sugeridas, ángulos de
+  // contenido), mucho menos actuarlo. Contraparte server-side de
+  // useGlobalSuggestions.js + acceptSuggestion/dismissSuggestion en
+  // useAppStore.js -- accept_suggestion aplica el mismo efecto real que
+  // aceptar desde el drawer "Sugerencias de IA" de la web (reusa create_task/
+  // update_task/merge_task/etc. por debajo, ver acceptSuggestion en
+  // write.mjs de orquestra-infra), nunca escribe el cambio directo.
+  // `content_angle` (piezas de Contenido sugeridas por IA) SÍ aparece acá a
+  // diferencia del drawer de la web (que lo excluye porque ese kind vive en
+  // la UI de Content.jsx, no en el drawer) -- acá no hay dos superficies
+  // separadas para un mismo canal, así que se incluye.
+  registerRead(
+    'list_suggestions',
+    '/v1/suggestions',
+    'Lista las sugerencias de IA de un proyecto (reescrituras de changelog, tareas que avanzaron/cerraron por evidencia, hallazgos de QA, gaps de setup/contenido/publicidad, fusiones de tareas sugeridas, ángulos de contenido). Por default solo trae las "pending" -- usá status="all" para ver también las ya aceptadas/descartadas, o un status puntual.',
+    { status: z.string().optional().describe('Default "pending". "all" trae todas, o un status puntual ("accepted"/"dismissed").') },
+    (args, projectId) => ({ projectId, status: args.status })
+  )
+
+  server.registerTool(
+    'accept_suggestion',
+    {
+      description: 'Acepta una sugerencia de IA y aplica su efecto real según su "kind" (ver list_suggestions): mueve/cierra la tarea que corresponda, reescribe el changelog, crea el servicio/canal/contenido/tarea sugerido, o fusiona dos tareas duplicadas. Mismo efecto que aceptarla desde el drawer "Sugerencias de IA" de la web. No se puede aceptar una que ya no esté "pending".',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        suggestionId: z.string().describe('Ver list_suggestions'),
+        moduleId: z.string().optional().describe('Solo para kind="qa_finding" -- ese branch crea una tarea nueva, que exige moduleId real (mismas reglas que create_task). Ignorado en el resto de los kinds.'),
+        dueDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Formato esperado: YYYY-MM-DD').optional().describe('Solo para kind="qa_finding" -- mismo motivo que moduleId arriba.'),
+        overrides: z.record(z.any()).optional().describe('Solo para kind="content_angle" -- el form final de la pieza de contenido a crear (puede diferir de lo que propuso la IA). Mismos campos que create_content.'),
+      },
+    },
+    async ({ projectId, suggestionId, moduleId, dueDate, overrides }) => {
+      try {
+        const data = await apiPost(config, `/v1/suggestions/${suggestionId}/accept`, {
+          projectId: resolveProjectId(projectId), moduleId, dueDate, overrides,
+        })
+        return textResult(data)
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  server.registerTool(
+    'dismiss_suggestion',
+    {
+      description: 'Descarta una sugerencia de IA sin aplicar su efecto (queda en status "dismissed", no se borra).',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        suggestionId: z.string().describe('Ver list_suggestions'),
+      },
+    },
+    async ({ projectId, suggestionId }) => {
+      try {
+        const data = await apiPost(config, `/v1/suggestions/${suggestionId}/dismiss`, { projectId: resolveProjectId(projectId) })
+        return textResult(data)
+      } catch (err) {
+        return errorResult(err)
+      }
     }
   )
 
+  registerRead('list_changelog', '/v1/changelog',
+    'Lista TODAS las entradas de changelog de un proyecto, con todos sus campos (id, section, text, version, distributions, repo, taskId, createdAt, createdBy) -- a diferencia de get_dashboard_summary/get_project_context, que solo traen un resumen recortado (texto/título, sin repo ni distributions). Útil para auditar (ej. "¿qué entradas viejas no tienen repo?") antes de update_changelog_entry.',
+    {}, (args, projectId) => ({ projectId }))
+
   registerCreate(
     'create_changelog_entry',
     '/v1/changelog',
@@ -447,6 +760,39 @@ export function createServer() {
       section: z.enum(CHANGELOG_SECTIONS).describe('Sección del changelog'),
       text: z.string().describe('Descripción de la entrada'),
       version: z.string().optional(),
+      distributions: z.array(z.object({
+        distId: z.string(),
+        version: z.string().optional(),
+      })).optional().describe('Distribuciones a las que aplica esta entrada (ver list_distributions) -- vacío/omitido = aplica a todo el proyecto. Cada una puede tener su propia versión dentro de esta entrada.'),
+      repo: z.string().optional().describe('"owner/name" del repo de origen del commit/PR que generó esta entrada, si se sabe -- alimenta el chip de repo en la tarjeta de versión.'),
+      taskId: z.string().optional().describe('Tarea que esta entrada documenta o cierra, si se sabe (ver list_tasks) -- alimenta el chip de tarea, clicable al detalle, en la tarjeta de versión.'),
+      plannedReleaseDate: z.string().optional().describe('YYYY-MM-DD -- fecha objetivo de corte de esta versión (solo tiene sentido si la entrada queda en Unreleased). Puramente informativo, alimenta el calendario global -- no dispara release_changelog_version solo.'),
+    }
+  )
+
+  registerUpdate('update_changelog_entry', '/v1/changelog',
+    'Edita una entrada de changelog existente (section/text/version/distributions/repo/taskId) -- primera edición puntual por id que existe (antes solo había create + el bulk-update de release_changelog_version). Pensada sobre todo para backfill/corrección (ej. completar "repo" en entradas viejas que se crearon antes de que ese campo se mandara), no para reescribir historia -- si el usuario solo quiere corregir el texto de una entrada reciente por error de tipeo, esto también sirve.',
+    {
+      section: z.enum(CHANGELOG_SECTIONS).optional(),
+      text: z.string().optional(),
+      version: z.string().optional(),
+      distributions: z.array(z.object({
+        distId: z.string(),
+        version: z.string().optional(),
+      })).optional(),
+      repo: z.string().optional().describe('"owner/name" del repo de origen.'),
+      taskId: z.string().optional(),
+      plannedReleaseDate: z.string().optional().describe('YYYY-MM-DD -- ver create_changelog_entry.'),
+    }
+  )
+
+  registerCreate(
+    'release_changelog_version',
+    '/v1/changelog/release',
+    'Corta una versión del changelog: toma TODAS las entradas que están en Unreleased (o, si mandas distributionId, solo las de esa distribución) y les asigna un número de versión real, mismo efecto que el botón "+ Nueva versión" de la web -- también actualiza distribution.version de las distribuciones tocadas. NUNCA lo llames sin que el usuario lo haya pedido explícitamente (o confirmado un número/fecha de release real) -- cortar una versión es una decisión de producto, no un paso automático de "buena higiene" como sí lo es create_changelog_entry.',
+    {
+      version: z.string().optional().describe('Semver real, ej. "1.4.0". Si se omite, se sugiere solo (Removed/Security -> mayor, Added -> menor, resto -> parche) a partir de la versión conocida más alta -- decíselo al usuario ANTES de aplicar si vos elegiste el número, no lo apliques en silencio.'),
+      distributionId: z.string().optional().describe('Si se manda, solo libera las entradas de ESA distribución (ver list_distributions) -- las entradas globales/de otras distribuciones quedan en Unreleased. Sin esto, libera todo el proyecto.'),
     }
   )
 
@@ -460,6 +806,13 @@ export function createServer() {
       pinned: z.boolean().optional(),
       moduleId: z.string().optional().describe('Módulo relacionado, si la nota es sobre uno específico -- ligarla ayuda a encontrarla después (ver list_modules)'),
       taskId: z.string().optional().describe('Tarea relacionada, si la nota es sobre una específica (ver list_tasks)'),
+      type: z.enum(NOTE_TYPES).optional().describe('Default: planificacion (nota sin tipo especial). "decision" habilita alternativesConsidered/wouldRevertIf.'),
+      alternativesConsidered: z.string().optional().describe('Solo para type=\'decision\'. Qué más se evaluó y por qué no.'),
+      wouldRevertIf: z.string().optional().describe('Solo para type=\'decision\'. La condición que haría cambiar de opinión -- sin esto la decisión se vuelve dogma.'),
+      visibility: z.enum(NOTE_VISIBILITY).optional().describe('Default: team. "private" restringe la lectura a quien la creó (enforcement real en firestore.rules, no solo la UI).'),
+      relatedNoteId: z.string().optional().describe('Otra nota relacionada, si es clara la relación (ver search) -- agregado 12 ago 2026. No inventes el vínculo si no es evidente.'),
+      adrDocId: z.string().optional().describe('Liga esta nota a un doc ADR ya creado con create_doc (type="adr"). No lo mandes junto con publishAsAdr -- ese genera su propio doc.'),
+      publishAsAdr: z.boolean().optional().describe('Solo para type=\'decision\'. Genera automáticamente el doc ADR correspondiente (numerado "ADR-XXX: {title}", con la plantilla Contexto/Alternativas consideradas/Decisión/Consecuencias a partir de body/alternativesConsidered/wouldRevertIf) y liga esta nota a él -- mismo flujo que el toggle "Publicar como ADR" de NewNoteModal.jsx en la web, en un solo paso.'),
     }
   )
 
@@ -474,6 +827,11 @@ export function createServer() {
       adrStatus: z.enum(ADR_STATUSES).optional().describe('Solo para type=\'adr\'. "aceptado" es lo único que alimenta Material (Contenido) como fuente de ángulos -- ver adrContext.'),
       adrContext: z.string().optional().describe('Solo para type=\'adr\'. Qué problema/situación llevó a la decisión, en texto estructurado (no el markdown libre de content).'),
       adrConsequences: z.string().optional().describe('Solo para type=\'adr\'. Qué cambia de ahora en adelante.'),
+      moduleId: z.string().optional().describe('Módulo al que pertenece (ver list_modules) -- vincularlo es lo que permite detectar "puede estar desactualizado" cuando el módulo acumula actividad después de la última edición.'),
+      folder: z.enum(DOC_FOLDERS).optional().describe('Carpeta donde se archiva en la UI -- independiente de `type` (ej. un ADR se puede archivar en cualquier carpeta).'),
+      visibility: z.enum(DOC_VISIBILITY).optional().describe('"team" (default) | "workspace" | "public". "public" expone el doc sin sesión en una URL propia.'),
+      reviewOwnerUid: z.string().optional().describe('uid de quién recibe el aviso cuando el doc queda desactualizado.'),
+      reviewIntervalDays: z.number().optional().describe('Cada cuántos días revisar por calendario (30/90/180) -- sin esto, solo se detecta vencimiento por actividad del módulo vinculado, nunca por fecha.'),
     }
   )
 
@@ -532,10 +890,14 @@ export function createServer() {
   registerCreate('create_category', '/v1/categories', 'Crea una categoría (agrupación/audiencia) en un proyecto.', {
     name: z.string().describe('Nombre de la categoría'),
     color: z.string().optional().describe('Color hex'),
+    description: z.string().optional().describe('Para qué sirve esta categoría, en pocas palabras -- agregado 12 ago 2026.'),
+    order: z.number().optional().describe('Orden manual de aparición (más chico = más arriba) -- agregado 12 ago 2026.'),
   })
   registerUpdate('update_category', '/v1/categories', 'Edita una categoría existente.', {
     name: z.string().optional(),
     color: z.string().optional(),
+    description: z.string().optional(),
+    order: z.number().optional(),
   })
 
   // Campos específicos por tipo de servicio -- unión deduplicada de las
@@ -662,12 +1024,37 @@ export function createServer() {
     knowledgeSource: z.string().optional().describe('Doc libre tipo CLAUDE.md para el agente de QA de esta distribución.'),
   })
 
-  // ═══ Contenido (Fase 1 del rediseño, 11 ago 2026) ═══════════════════════════
-  // Un canal = una cuenta real (o a conectar) donde se publica. Una
-  // publicación (content) = un canal (channelId), no varios -- para
-  // publicar en N canales a la vez, crea N piezas de contenido con
-  // create_content, una por channelId.
+  // ═══ Contenido (Fase 1 del rediseño, 11 ago 2026; modelo multi-canal
+  // Fase 3, 20 ago 2026) ═══════════════════════════════════════════════════
+  // Un canal = una cuenta real (o a conectar) donde se publica. Una pieza
+  // de contenido puede ser de UN canal (channelId a nivel doc, shape
+  // legacy) o MULTI-CANAL (channels[], un elemento por canal con su propio
+  // caption/status/fecha/desempeño -- ver pieceVariants en contentPlan.js,
+  // orquestra-web). Para una pieza en varios canales a la vez, mandá
+  // channels[] en vez de channelId -- ya no hace falta llamar create_content
+  // una vez por canal (aunque channelId de 1 solo canal sigue andando igual
+  // para el caso simple).
   const CONTENT_STATUSES = ['idea', 'draft', 'review', 'approved', 'published']
+  const CONTENT_VARIANT_SCHEMA = z.object({
+    channelId: z.string().describe('Canal de esta variante -- ver list_channels'),
+    format: z.string().optional(),
+    status: z.enum(CONTENT_STATUSES).optional().describe('Default: idea'),
+    caption: z.string().optional(),
+    hashtags: z.array(z.string()).optional(),
+    scheduledAt: z.number().optional().describe('Timestamp en ms de cuándo se programa publicar'),
+    approvalRequired: z.boolean().optional(),
+    approverUid: z.string().optional(),
+    campaignId: z.string().optional().describe('Campaña de pauta a la que pertenece ESTE canal -- ver list_campaigns'),
+    organicRate: z.number().optional(),
+    leads: z.number().optional(),
+    reach: z.number().optional(),
+    clicksToSite: z.number().optional(),
+    saves: z.number().optional(),
+    avgReadMinutes: z.number().optional(),
+    imagePrompt: z.string().optional().describe('Descripción visual en inglés para generar la portada (no genera la imagen, solo guarda el texto)'),
+    language: z.string().optional(),
+    translationOf: z.string().optional(),
+  })
 
   registerRead('list_channels', '/v1/channels',
     'Lista los canales (cuentas de redes/blog/newsletter, reales o a conectar) de un proyecto. Úsala antes de create_channel para no duplicar, y antes de create_content para saber qué channelId usar.',
@@ -723,32 +1110,36 @@ export function createServer() {
     'Lista las publicaciones de contenido (posts programados/publicados) de un proyecto.',
     {}, (args, projectId) => ({ projectId }))
 
-  registerCreate('create_content', '/v1/content', 'Crea una publicación de contenido en un canal (ver list_channels/create_channel). Para publicar la misma pieza en varios canales, llama a esto una vez por cada channelId.', {
-    channelId: z.string().describe('Canal donde se publica -- ver list_channels'),
-    title: z.string().describe('Referencia interna, no es lo que se publica'),
-    format: z.string().optional().describe('Ej. "Post", "Reel", "Hilo" -- texto libre según el canal'),
-    status: z.enum(CONTENT_STATUSES).optional().describe('Default: idea'),
-    caption: z.string().optional().describe('Texto real de la publicación'),
+  registerCreate('create_content', '/v1/content', 'Crea una pieza de contenido. Dos formas: (1) channelId suelto -- 1 canal, shape simple, seguí usándolo si solo publicás en un lado. (2) channels[] -- una pieza multi-canal con una variante por canal (cada una con su propio caption/status/fecha/desempeño), reemplaza tener que llamar esto varias veces para la "misma" publicación en distintos canales.', {
+    channelId: z.string().optional().describe('Canal donde se publica -- ver list_channels. Usalo para una pieza de 1 solo canal; si vas a publicar en varios, mandá channels[] en vez de esto.'),
+    channels: z.array(CONTENT_VARIANT_SCHEMA).optional().describe('Pieza multi-canal -- una entrada por canal. No mandes channelId si usás esto.'),
+    title: z.string().describe('Referencia interna, no es lo que se publica -- compartida entre todos los canales si es multi-canal'),
+    format: z.string().optional().describe('Ej. "Post", "Reel", "Hilo" -- texto libre según el canal (solo con channelId suelto -- en channels[] va por variante)'),
+    status: z.enum(CONTENT_STATUSES).optional().describe('Default: idea (solo con channelId suelto -- en channels[] va por variante)'),
+    caption: z.string().optional().describe('Texto real de la publicación (solo con channelId suelto)'),
     hashtags: z.array(z.string()).optional(),
-    scheduledAt: z.number().optional().describe('Timestamp en ms de cuándo se programa publicar'),
+    scheduledAt: z.number().optional().describe('Timestamp en ms de cuándo se programa publicar (solo con channelId suelto)'),
     approvalRequired: z.boolean().optional(),
     approverUid: z.string().optional().describe('uid de quien debe aprobar antes de publicar'),
-    changelogVersion: z.string().optional().describe('Versión del changelog que esta publicación anuncia ("Atada a") -- ver list_tasks/create_changelog_entry'),
-    moduleId: z.string().optional(),
-    ideaId: z.string().optional().describe('Si esta pieza viene de una idea existente'),
-    campaignId: z.string().optional().describe('Campaña de pauta a la que pertenece -- ver list_campaigns'),
-    organicRate: z.number().optional().describe('% de interacción, medido a mano por el usuario en la plataforma real -- solo tiene sentido con status published'),
-    leads: z.number().optional().describe('"Registros" atribuidos a esta pieza orgánica -- entrada manual'),
-    reach: z.number().optional().describe('Alcance absoluto -- entrada manual, Fase 4 de Resultados'),
-    clicksToSite: z.number().optional().describe('Clics al sitio/docs -- entrada manual'),
-    saves: z.number().optional().describe('Guardados -- entrada manual, típico de X/Instagram'),
-    avgReadMinutes: z.number().optional().describe('Minutos de lectura media -- entrada manual, típico de blog'),
+    changelogVersion: z.string().optional().describe('Versión del changelog que esta pieza anuncia ("Atada a") -- ver list_tasks/create_changelog_entry. Siempre a nivel pieza, compartida entre canales.'),
+    seriesName: z.string().optional().describe('Texto libre que agrupa piezas relacionadas, ej. "Lanzamiento agosto" (Fase 4, 20 ago 2026) -- siempre a nivel pieza. Usá list_content primero para ver nombres de serie ya usados y no crear variantes del mismo nombre por typo.'),
+    moduleId: z.string().optional().describe('Siempre a nivel pieza'),
+    ideaId: z.string().optional().describe('Si esta pieza viene de una idea existente -- siempre a nivel pieza'),
+    campaignId: z.string().optional().describe('Campaña de pauta a la que pertenece -- ver list_campaigns (solo con channelId suelto)'),
+    organicRate: z.number().optional().describe('% de interacción, medido a mano por el usuario en la plataforma real -- solo tiene sentido con status published (solo con channelId suelto)'),
+    leads: z.number().optional().describe('"Registros" atribuidos a esta pieza orgánica -- entrada manual (solo con channelId suelto)'),
+    reach: z.number().optional().describe('Alcance absoluto -- entrada manual, Fase 4 de Resultados (solo con channelId suelto)'),
+    clicksToSite: z.number().optional().describe('Clics al sitio/docs -- entrada manual (solo con channelId suelto)'),
+    saves: z.number().optional().describe('Guardados -- entrada manual, típico de X/Instagram (solo con channelId suelto)'),
+    avgReadMinutes: z.number().optional().describe('Minutos de lectura media -- entrada manual, típico de blog (solo con channelId suelto)'),
+    imagePrompt: z.string().optional().describe('Descripción visual en inglés para generar la portada -- no genera la imagen, solo guarda el texto (solo con channelId suelto)'),
     language: z.string().optional().describe('\'en\' si esta pieza es la traducción de otra. Sin valor = idioma original.'),
     translationOf: z.string().optional().describe('Si esta pieza es una traducción, id del content original'),
   })
 
-  registerUpdate('update_content', '/v1/content', 'Edita una publicación de contenido existente. Al pasar status a "approved" o "published" el server estampa quién/cuándo solo -- no lo mandes tú.', {
+  registerUpdate('update_content', '/v1/content', 'Edita una pieza de contenido existente. Al pasar status a "approved" o "published" el server estampa quién/cuándo solo -- no lo mandes tú (mismo estampado por variante si mandás channels[]). Para patchear un solo canal de una pieza multi-canal, mandá el array `channels` COMPLETO con esa variante modificada -- Firestore no puede editar un campo adentro de un elemento de array, así que reemplaza el array entero.', {
     channelId: z.string().optional(),
+    channels: z.array(CONTENT_VARIANT_SCHEMA).optional().describe('Reemplaza el array de variantes completo -- mandá TODAS las variantes (las que cambian y las que no), no solo la que estás editando.'),
     title: z.string().optional(),
     format: z.string().optional(),
     status: z.enum(CONTENT_STATUSES).optional(),
@@ -758,6 +1149,7 @@ export function createServer() {
     approvalRequired: z.boolean().optional(),
     approverUid: z.string().optional(),
     changelogVersion: z.string().optional(),
+    seriesName: z.string().optional(),
     moduleId: z.string().optional(),
     ideaId: z.string().optional(),
     campaignId: z.string().optional(),
@@ -767,6 +1159,7 @@ export function createServer() {
     clicksToSite: z.number().optional(),
     saves: z.number().optional(),
     avgReadMinutes: z.number().optional(),
+    imagePrompt: z.string().optional(),
     language: z.string().optional(),
     translationOf: z.string().optional(),
   })
@@ -798,6 +1191,7 @@ export function createServer() {
     closeStatusId: z.string().optional().describe('Estatus donde se mueven los bugs de este agente al cerrarse solos -- default: primer estatus final'),
     testUserEmail: z.string().optional().describe('Cuenta de prueba DEDICADA (no una credencial real) que la revisión con IA puede usar para iniciar sesión y revisar pantallas autenticadas'),
     testUserPassword: z.string().optional().describe('Password de testUserEmail'),
+    plannedRunAt: z.string().optional().describe('YYYY-MM-DD -- recordatorio manual de "próxima corrida planeada". QA no tiene scheduling real (todo trigger es manual/push): esto NO dispara ninguna corrida sola, solo alimenta el calendario global.'),
   })
 
   registerUpdate('update_qa_agent', '/v1/qaAgents', 'Edita un agente de QA existente.', {
@@ -813,6 +1207,7 @@ export function createServer() {
     closeStatusId: z.string().optional(),
     testUserEmail: z.string().optional().describe('Cuenta de prueba DEDICADA (no una credencial real) para que la revisión con IA inicie sesión'),
     testUserPassword: z.string().optional(),
+    plannedRunAt: z.string().optional().describe('YYYY-MM-DD -- ver create_qa_agent.'),
   })
 
   registerCreate('create_qa_run', '/v1/qa/runs', 'Dispara una corrida de QA (lint/tests/build/E2E según el stack) en la rama indicada. Necesita al menos un agente de QA activo para el stack (o falla explícito -- ver list_qa_agents/create_qa_agent). La corrida queda "queued" -- nunca asumas que pasó, confirma con get_qa_run.', {
@@ -902,10 +1297,9 @@ export function createServer() {
         projectId: z.string().optional().describe(PROJECT_ID_DESC),
         stageId: z.enum(STAGE_IDS).describe('pre | build | post -- ver get_stage_playbook para el contenido'),
         moduleName: z.string().optional().describe('Nombre del módulo -- default: el de la plantilla'),
-        includeDates: z.boolean().optional().describe('Si asigna dueDate a cada tarea usando los offsetDays de la plantilla (default: false)'),
       },
     },
-    async ({ projectId, stageId, moduleName, includeDates }) => {
+    async ({ projectId, stageId, moduleName }) => {
       try {
         const pid = resolveProjectId(projectId)
         const playbook = PLAYBOOKS[stageId]
@@ -918,9 +1312,10 @@ export function createServer() {
 
         const taskIds = []
         for (const t of playbook.tasks) {
-          const dueDate = includeDates
-            ? new Date(Date.now() + t.offsetDays * 86400000).toISOString().slice(0, 10)
-            : undefined
+          // dueDate es obligatorio en create_task (ver más abajo) -- ya no
+          // es opcional (antes flag `includeDates`, default false, rompía
+          // en seco apenas dueDate se volvió requerido server-side).
+          const dueDate = new Date(Date.now() + t.offsetDays * 86400000).toISOString().slice(0, 10)
           const created = await apiPost(config, '/v1/tasks', {
             projectId: pid,
             title: t.title,