orquestra-mcp 1.7.9 → 1.9.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "orquestra-mcp",
-  "version": "1.7.9",
-  "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.9.0",
+  "description": "Servidor MCP de Orquestra -- 71 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) {
@@ -43,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: 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: 6, section: 'Ideas', check: 'search', createOrUpdate: 'create_idea / update_idea / convert_idea_to_task', matchBy: 'title' },
+    { step: 7, section: 'Notas', check: 'list_notes', createOrUpdate: 'create_note / update_note', matchBy: 'title' },
+    { 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' },
   ],
 }
@@ -170,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(
@@ -306,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(),
@@ -315,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()
@@ -372,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
@@ -439,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',
@@ -460,6 +575,176 @@ export function createServer() {
       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)
+      }
     }
   )
 
@@ -481,6 +766,7 @@ export function createServer() {
       })).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.'),
     }
   )
 
@@ -496,6 +782,7 @@ export function createServer() {
       })).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.'),
     }
   )
 
@@ -509,6 +796,10 @@ export function createServer() {
     }
   )
 
+  registerRead('list_notes', '/v1/notes',
+    'Lista TODAS las notas de un proyecto de Orquestra, con todos sus campos -- a diferencia de get_project_context/search (resumen recortado), útil para auditar o encontrar el id exacto antes de update_note.',
+    {}, (args, projectId) => ({ projectId }))
+
   registerCreate(
     'create_note',
     '/v1/notes',
@@ -524,6 +815,26 @@ export function createServer() {
       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.'),
+    }
+  )
+
+  registerUpdate('update_note', '/v1/notes',
+    'Edita una nota existente. Todos los campos son opcionales -- solo se cambian los que mandes.',
+    {
+      title: z.string().optional(),
+      body: z.string().optional(),
+      pinned: z.boolean().optional(),
+      moduleId: z.string().optional(),
+      taskId: z.string().optional(),
+      type: z.enum(NOTE_TYPES).optional(),
+      alternativesConsidered: z.string().optional(),
+      wouldRevertIf: z.string().optional(),
+      visibility: z.enum(NOTE_VISIBILITY).optional(),
+      relatedNoteId: z.string().optional(),
+      adrDocId: z.string().optional().describe('Liga esta nota a un doc ADR ya creado. No lo mandes junto con publishAsAdr.'),
+      publishAsAdr: z.boolean().optional().describe('Genera el doc ADR recién ahora (útil si la nota se marcó "decision" después de creada) y liga adrDocId -- falla si la nota ya tiene uno.'),
     }
   )
 
@@ -735,12 +1046,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.',
@@ -796,32 +1132,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(),
@@ -831,6 +1171,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(),
@@ -840,6 +1181,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(),
   })
@@ -871,6 +1213,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.', {
@@ -886,6 +1229,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.', {
@@ -929,6 +1273,7 @@ export function createServer() {
         description: z.string().optional(),
         phase: z.string().optional().describe('idea | mvp | v1 | v2 | beta | produccion (default: idea)'),
         projectType: z.enum(['code', 'content', 'hybrid']).optional().describe('Default: hybrid'),
+        scale: z.enum(['landing', 'app', 'platform']).optional().describe('Default implícito: app. Eje ORTOGONAL a projectType -- "landing" es una página estática sin backend/auth/db propios (evita que las sugerencias de setup propongan infra que no aplica).'),
         url: z.string().optional(),
         distributions: z.array(z.enum(PLATFORM_TYPES)).optional().describe('Plataformas a crear, ej: ["web","ios"]'),
         categories: z.array(z.string()).optional().describe('Nombres de categorías a crear (default: ["General"])'),
@@ -947,13 +1292,14 @@ export function createServer() {
   server.registerTool(
     'update_project',
     {
-      description: 'Edita el proyecto configurado (name, description, phase, projectType, url). Útil para sincronizar la fase real de un proyecto que ya estaba avanzado antes de conectarlo a Orquestra -- get_project_context puede verse "vacío" (sin módulos/tareas) sin que eso signifique que el proyecto recién empieza.',
+      description: 'Edita el proyecto configurado (name, description, phase, projectType, scale, url). Útil para sincronizar la fase real de un proyecto que ya estaba avanzado antes de conectarlo a Orquestra -- get_project_context puede verse "vacío" (sin módulos/tareas) sin que eso signifique que el proyecto recién empieza.',
       inputSchema: {
         projectId: z.string().optional().describe(PROJECT_ID_DESC),
         name: z.string().optional(),
         description: z.string().optional(),
         phase: z.string().optional().describe('idea | mvp | v1 | v2 | beta | produccion'),
         projectType: z.enum(['code', 'content', 'hybrid']).optional(),
+        scale: z.enum(['landing', 'app', 'platform']).optional().describe('Eje ORTOGONAL a projectType, no lo reemplaza -- "landing" es una página estática sin backend/auth/db propios (ej. un portafolio o sitio de marketing): marcalo así si el proyecto es claramente eso, para que las sugerencias de setup dejen de proponer backend/auth/database. Default implícito "app" si no se manda -- sin este campo, el comportamiento es igual que antes.'),
         url: z.string().optional(),
       },
     },
@@ -975,10 +1321,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]
@@ -991,9 +1336,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,