orquestra-mcp 1.49.0 → 1.51.0

package/bin/orquestra-mcp.mjs

@@ -3,6 +3,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { createServer, createSetupNeededServer } from '../src/server.mjs'
 import { runSetup } from '../src/setup.mjs'
 import { runVaultSync } from '../src/vaultSync.mjs'
+import { startUpdateCheck } from '../src/updateCheck.mjs'
 
 const HELP_TEXT = `orquestra-mcp -- Servidor MCP de Orquestra (132 tools)
 
@@ -10,6 +11,9 @@ Uso:
   npx orquestra-mcp            Inicia el servidor MCP por stdio -- lo usa tu cliente
                                 MCP (Claude Code, Claude Desktop, etc.), no se corre a mano
   npx orquestra-mcp setup      Login por navegador + conecta esta carpeta a un proyecto
+  npx orquestra-mcp setup --agent codex
+                                Lo mismo para una herramienta puntual (claude-code, codex,
+                                cursor, gemini-cli...): cada una firma con su propio agente
   npx orquestra-mcp vault sync <carpeta> [--apply]
                                 Sincroniza la base de conocimiento del workspace con una
                                 carpeta de tu vault de Obsidian (la 1ra vez solo muestra el plan)
@@ -17,7 +21,8 @@ Uso:
 
 Config (la deja lista "setup"): ~/.orquestra/mcp-config.json
 Alternativa manual (variables de entorno): ORQUESTRA_API_TOKEN, ORQUESTRA_WORKSPACE_ID,
-ORQUESTRA_DEFAULT_PROJECT_ID
+ORQUESTRA_DEFAULT_PROJECT_ID. ORQUESTRA_AGENT elige el token de una herramienta
+(ej. codex) cuando la carpeta tiene varias conectadas.
 
 Docs completas: https://orquestra.me/mcp
 `
@@ -31,7 +36,8 @@ async function main() {
   }
 
   if (cmd === 'setup') {
-    await runSetup()
+    const agentIdx = process.argv.indexOf('--agent')
+    await runSetup({ agent: agentIdx > 0 ? process.argv[agentIdx + 1] : process.env.ORQUESTRA_AGENT })
     return
   }
 
@@ -45,6 +51,9 @@ async function main() {
     return
   }
 
+  // Sin await: el aviso de versión nueva no debe atrasar el arranque.
+  startUpdateCheck()
+
   let server
   try {
     server = createServer()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orquestra-mcp",
-  "version": "1.49.0",
+  "version": "1.51.0",
   "description": "Servidor MCP de Orquestra -- 135 tools para leer y escribir tareas, ideas, changelog, infraestructura, contenido, QA y más desde un agente de IA",
   "type": "module",
   "bin": {

package/src/api.mjs

@@ -1,4 +1,4 @@
-import { readConfigFile, resolveProjectForCwd, CONFIG_PATH } from './configFile.mjs'
+import { readConfigFile, resolveProjectForCwd, entryForAgent, agentKey, CONFIG_PATH } from './configFile.mjs'
 import { request } from './http.mjs'
 
 const DEFAULT_API_BASE = 'https://api.orquestra.me'
@@ -8,7 +8,19 @@ export function loadConfig() {
   // Todo sale de la MISMA carpeta mapeada (ver resolveProjectForCwd) --
   // apiToken/workspaceId/projectId siempre son de una sola cuenta, nunca
   // el token de una carpeta con el proyecto de otra.
-  const folderConfig = resolveProjectForCwd(fileConfig?.projects, process.cwd())
+  const folderEntry = resolveProjectForCwd(fileConfig?.projects, process.cwd())
+  // ORQUESTRA_AGENT (ORQ-415) elige el token de esa herramienta en la
+  // carpeta. Si no está conectada falla explícito: caer al token default
+  // haría que sus cambios queden firmados por otra herramienta.
+  const agent = agentKey(process.env.ORQUESTRA_AGENT)
+  const folderConfig = agent ? entryForAgent(folderEntry, agent) : folderEntry
+  if (agent && folderEntry && !folderConfig && !process.env.ORQUESTRA_API_TOKEN) {
+    throw new Error(
+      `La herramienta "${process.env.ORQUESTRA_AGENT}" (ORQUESTRA_AGENT) no está conectada en esta carpeta (${process.cwd()}), ` +
+      `solo otras. Para que sus cambios queden a su nombre y no al de otra herramienta, abre una terminal aquí, ` +
+      `corre "npx orquestra-mcp@latest setup" y elige esa herramienta; después reconecta el MCP.`
+    )
+  }
 
   const apiBase = process.env.ORQUESTRA_API_BASE || folderConfig?.apiBase || DEFAULT_API_BASE
   const apiToken = process.env.ORQUESTRA_API_TOKEN || folderConfig?.apiToken

package/src/configFile.mjs

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
-import { homedir } from 'os'
+import { homedir, hostname } from 'os'
+import { randomBytes } from 'crypto'
 import { join, dirname, win32, posix } from 'path'
 
 export const CONFIG_PATH = join(homedir(), '.orquestra', 'mcp-config.json')
@@ -45,19 +46,104 @@ export function writeConfigFile(data) {
   writeFileSync(CONFIG_PATH, JSON.stringify(data, null, 2), { mode: 0o600 })
 }
 
+// Identidad por herramienta (ORQ-415): cada herramienta (Claude Code, Codex,
+// Cursor...) tiene su propio token -- su propio agente en Orquestra -- aunque
+// trabajen en la misma carpeta. La entrada de la carpeta guarda la conexión
+// "default" arriba (la que se usa sin ORQUESTRA_AGENT) con `agent` = su
+// herramienta, y todas en `agents[clave]`. Una entrada de antes de ORQ-415 no
+// trae `agent`: su token es el de "Claude Code", el default histórico.
+// Mismo slug que agentSlug() de bootstrap.mjs en orquestra-infra.
+export function agentKey(label) {
+  return String(label || '')
+    .normalize('NFD').replace(/[̀-ͯ]/g, '')
+    .toLowerCase().trim()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+const LEGACY_AGENT = 'claude-code'
+const defaultAgentOf = entry => entry?.agent || (entry?.apiToken ? LEGACY_AGENT : null)
+const connectionOf = ({ apiBase, apiToken, workspaceId, projectId }) => ({ apiBase, apiToken, workspaceId, projectId })
+
+// La conexión de UNA herramienta dentro de la entrada de una carpeta, o null
+// si esa herramienta nunca se conectó ahí (nunca cae al token de otra: eso
+// es justo lo que hacía firmar a Codex como Claude Code).
+export function entryForAgent(entry, key) {
+  if (!entry || !key) return entry
+  if (entry.agents?.[key]) return entry.agents[key]
+  return defaultAgentOf(entry) === key ? connectionOf(entry) : null
+}
+
 // Guarda/actualiza la cuenta+proyecto de UNA carpeta sin pisar las demás --
 // setup se puede correr varias veces, una por cada carpeta contenedora de
 // repos (ver resolveProjectForCwd), y cada corrida solo debe tocar su
 // propia entrada -- incluida la cuenta (apiToken/workspaceId), para poder
 // tener una carpeta en una cuenta de Orquestra y otra carpeta en otra
-// cuenta distinta al mismo tiempo.
-export function upsertProjectMapping({ apiBase, apiToken, workspaceId, folderPath, projectId }) {
+// cuenta distinta al mismo tiempo. Con `agent` solo toca la conexión de esa
+// herramienta: la default de la carpeta cambia únicamente si era la misma
+// herramienta (o la carpeta no tenía ninguna).
+export function upsertProjectMapping({ apiBase, apiToken, workspaceId, folderPath, projectId, agent }) {
   const existing = readConfigFile() || { projects: {} }
   const projects = { ...(existing.projects || {}) }
-  projects[folderPath] = { apiBase, apiToken, workspaceId, projectId }
+  const conn = { apiBase, apiToken, workspaceId, projectId }
+  if (!agent) {
+    projects[folderPath] = conn
+  } else {
+    const prev = projects[folderPath]
+    const agents = { ...(prev?.agents || {}), [agent]: conn }
+    const keepDefault = prev && defaultAgentOf(prev) && defaultAgentOf(prev) !== agent
+    projects[folderPath] = keepDefault
+      ? { ...connectionOf(prev), agent: defaultAgentOf(prev), agents }
+      : { ...conn, agent, agents }
+  }
   writeConfigFile({ projects })
 }
 
+// El setup de una herramienta ya conocida en esta máquina revoca su token
+// anterior (bootstrap en orquestra-infra): hay que ponerle el nuevo a TODAS
+// las carpetas donde esa herramienta usa el mismo workspace, no solo a la del
+// setup, o las demás quedarían con un token muerto. Devuelve las carpetas.
+export function replaceAgentToken({ workspaceId, agent, apiToken }) {
+  const existing = readConfigFile()
+  if (!existing?.projects) return []
+  const updated = []
+  for (const [folderPath, entry] of Object.entries(existing.projects)) {
+    let touched = false
+    if (defaultAgentOf(entry) === agent && entry.workspaceId === workspaceId) { entry.apiToken = apiToken; touched = true }
+    const own = entry.agents?.[agent]
+    if (own && own.workspaceId === workspaceId) { own.apiToken = apiToken; touched = true }
+    if (touched) updated.push(folderPath)
+  }
+  if (updated.length) writeConfigFile(existing)
+  return updated
+}
+
+// Herramientas ya conectadas en esta máquina (en cualquier carpeta).
+export function connectedAgents() {
+  const keys = new Set()
+  for (const entry of Object.values(readConfigFile()?.projects || {})) {
+    if (defaultAgentOf(entry)) keys.add(defaultAgentOf(entry))
+    for (const key of Object.keys(entry.agents || {})) keys.add(key)
+  }
+  return keys
+}
+
+// Identidad de la máquina (ORQ-415): un id aleatorio, no el serial ni la MAC
+// -- solo distingue esta instalación ("Codex · MacBook-Pro" vs "Codex ·
+// Mac-mini"). Se crea una vez y se reusa en cada setup.
+export const MACHINE_PATH = join(homedir(), '.orquestra', 'machine.json')
+
+export function readOrCreateMachine() {
+  try {
+    const saved = JSON.parse(readFileSync(MACHINE_PATH, 'utf8'))
+    if (/^[a-f0-9]{16,64}$/.test(saved.id)) return { id: saved.id, name: saved.name || hostname().replace(/\.local$/, '') }
+  } catch {}
+  const machine = { id: randomBytes(8).toString('hex'), name: hostname().replace(/\.local$/, '') }
+  mkdirSync(dirname(MACHINE_PATH), { recursive: true })
+  writeFileSync(MACHINE_PATH, JSON.stringify(machine, null, 2), { mode: 0o600 })
+  return machine
+}
+
 // Busca, subiendo desde cwd hacia la raíz, la carpeta mapeada más específica
 // -- mismo criterio que .editorconfig/.gitconfig: el ancestro más cercano
 // gana, así que un repo individual con su propio mapeo (y su propia cuenta)

package/src/server.mjs

@@ -5,6 +5,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { z } from 'zod'
 import { loadConfig, apiGet, apiPost, apiPatch, apiPatchPath, apiDelete, apiDeletePath, putToPresignedUrl, ApiError } from './api.mjs'
 import { cancelContext } from './http.mjs'
+import { updateNotice } from './updateCheck.mjs'
 import { STAGES, PLAYBOOKS } from './stages.mjs'
 import { FOUNDATIONS } from './foundations.mjs'
 import { PLATFORM_PLAYBOOKS, TRACKING_TOOLS } from './platformPlaybooks.mjs'
@@ -25,6 +26,8 @@ function textResult(data) {
 }
 
 const PROJECT_ID_DESC = 'ID del proyecto dentro del workspace configurado. Si hay un proyecto default configurado (via "setup" o ORQUESTRA_DEFAULT_PROJECT_ID), este argumento se ignora -- el server queda fijo a ese proyecto y no puede leer/escribir otro.'
+// ORQ-411: los textos largos de idea, riesgo y módulo también cuentan para [[...]] y "Mencionado en".
+const WIKILINK_DESC = 'Admite [[Título]], [[Título|texto]] o [[ORQ-123]] para enlazar otra nota, doc, tarea, reunión, idea, riesgo, módulo, contenido o distribución del proyecto.'
 
 const TASK_TYPES = ['feature', 'bug', 'improvement', 'tech', 'docs', 'idea', 'design', 'security', 'meeting', 'call', 'followup', 'business']
 // Actividades (ORQ-295): reunión/llamada/seguimiento. 'business' sigue siendo tarea (entregable). Mismas listas que
@@ -102,7 +105,7 @@ const SETUP_GUIDE = {
 // preguntar en vez de adivinar.
 const SERVER_INSTRUCTIONS = `Este server conecta con Orquestra, la app de gestión de proyectos del usuario -- úsalo para mantener su proyecto sincronizado con el trabajo real, sin que tenga que pedírtelo cada vez.
 
-Al empezar una sesión de trabajo en este proyecto, llama una vez a get_project_context para saber en qué fase está, qué tareas hay abiertas/vencidas/bloqueadas y qué se hizo recientemente. Úsalo como contexto de fondo, no lo repitas en cada mensaje.
+Al empezar una sesión de trabajo en este proyecto, llama una vez a get_project_context para saber en qué fase está, qué tareas hay abiertas/vencidas/bloqueadas y qué se hizo recientemente. Úsalo como contexto de fondo, no lo repitas en cada mensaje. Si trae orquestraMcpUpdate, avísale al usuario UNA sola vez en la sesión que hay una versión nueva de este MCP y cómo actualizar (usa su campo message), sin interrumpir lo que estaba pidiendo.
 
 Si get_project_context devuelve un proyecto vacío (sin módulos ni tareas), es la primera vez que se usa este MCP aquí -- pero "vacío en Orquestra" NO significa "recién empezado en la realidad". Antes de ofrecer nada, pregúntale al usuario: ¿este proyecto es una idea nueva, o ya existe y solo lo estás conectando por primera vez? Según la respuesta:
 - Si es una idea nueva: llama a get_setup_guide y ofrece un playbook de etapa "pre" (get_stage_playbook + apply_stage_playbook) -- ahí sí basta con eso, el proyecto de verdad no tiene nada más que sincronizar todavía.
@@ -173,7 +176,10 @@ export function createSetupNeededServer(reason) {
   server.registerTool('diagnostico_conexion', {
     description: 'Explica por qué Orquestra no está conectado en esta carpeta y cómo arreglarlo.',
     inputSchema: {},
-  }, async () => ({ content: [{ type: 'text', text: `orquestra-mcp ${PKG_VERSION}: ${reason}` }] }))
+  }, async () => {
+    const update = updateNotice(PKG_VERSION)
+    return { content: [{ type: 'text', text: `orquestra-mcp ${PKG_VERSION}: ${reason}${update ? `\n\n${update.message}` : ''}` }] }
+  })
   return server
 }
 
@@ -203,14 +209,14 @@ export function createServer() {
     return projectId
   }
 
-  function registerRead(name, path, description, extraSchema, buildParams) {
+  function registerRead(name, path, description, extraSchema, buildParams, decorate = data => data) {
     server.registerTool(
       name,
       { description, inputSchema: { projectId: z.string().optional().describe(PROJECT_ID_DESC), ...extraSchema } },
       async (args) => {
         try {
           const data = await apiGet(config, path, buildParams(args, resolveProjectId(args.projectId)))
-          return textResult(data)
+          return textResult(decorate(data))
         } catch (err) {
           return errorResult(err)
         }
@@ -262,7 +268,11 @@ export function createServer() {
     '/v1/context',
     'Resumen compacto del estado de un proyecto de Orquestra: fase, plataformas, tareas abiertas/vencidas/bloqueadas, módulos, ideas y changelog reciente.',
     {},
-    (args, projectId) => ({ projectId })
+    (args, projectId) => ({ projectId }),
+    data => {
+      const update = updateNotice(PKG_VERSION)
+      return update ? { ...data, orquestraMcpUpdate: update } : data
+    }
   )
 
   registerRead(
@@ -293,10 +303,10 @@ export function createServer() {
   registerRead(
     'search',
     '/v1/search',
-    'Busca por texto en tareas, actividades (reuniones/llamadas), notas, ideas y docs de un proyecto de Orquestra. También por folio ("ORQ-123") o por clave de módulo ("AUTH-3") -- la exacta sale primero -- y sin importar acentos. Primero lo que coincide en el folio o el título, después en el cuerpo; tope de 30 resultados: si buscas ideas o docs en un proyecto con muchas tareas, pasa `types` para que no queden tapadas.',
+    'Busca por texto en tareas, actividades (reuniones/llamadas), notas, ideas, docs, riesgos, módulos, contenido y distribuciones de un proyecto de Orquestra -- en los mismos campos que pueden tener [[wikilinks]] (descripción, mitigación, criterios de cierre, puntos, verificaciones...). También por folio ("ORQ-123") o por clave de módulo ("AUTH-3") -- la exacta sale primero -- y sin importar acentos. Primero lo que coincide en el folio o el título, después en el cuerpo; tope de 30 resultados: si buscas ideas o docs en un proyecto con muchas tareas, pasa `types` para que no queden tapadas.',
     {
       q: z.string().describe('Texto a buscar'),
-      types: z.array(z.enum(['task', 'activity', 'note', 'idea', 'doc', 'knowledge'])).optional().describe('Limitar a estos tipos (opcional). Sin esto busca en todos. knowledge = solo la base vinculada a este proyecto.'),
+      types: z.array(z.enum(['task', 'activity', 'note', 'idea', 'doc', 'knowledge', 'risk', 'module', 'content', 'distribution'])).optional().describe('Limitar a estos tipos (opcional). Sin esto busca en todos. knowledge = solo la base vinculada a este proyecto.'),
     },
     (args, projectId) => ({ projectId, q: args.q, types: args.types?.join(',') })
   )
@@ -1008,10 +1018,10 @@ export function createServer() {
   registerRead(
     'get_backlinks',
     '/v1/backlinks',
-    'Backlinks ("Mencionado en"): qué notas, docs, tareas e ideas enlazan con [[...]] a la entidad pedida. Útil antes de editar o cerrar algo para ver qué depende de eso.',
+    'Backlinks ("Mencionado en"): qué notas, docs, tareas, reuniones, ideas, riesgos y módulos enlazan con [[...]] a la entidad pedida (también cuentan los puntos a revisar de una reunión y las instrucciones de las verificaciones). Útil antes de editar o cerrar algo para ver qué depende de eso.',
     {
-      type: z.enum(['note', 'doc', 'task', 'idea']),
-      id: z.string().describe('id de la nota/doc/tarea/idea'),
+      type: z.enum(['note', 'doc', 'task', 'activity', 'idea', 'risk', 'module', 'content', 'distribution']).describe('"activity" para reunión/llamada/seguimiento'),
+      id: z.string().describe('id del ítem'),
     },
     (args, projectId) => ({ projectId, type: args.type, id: args.id })
   )
@@ -1993,7 +2003,7 @@ export function createServer() {
     {
       relatedTo: RELATED_TO,
       title: z.string().describe('Título de la idea'),
-      description: z.string().optional(),
+      description: z.string().optional().describe(WIKILINK_DESC),
       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'),
@@ -2014,7 +2024,7 @@ export function createServer() {
 
   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(),
+    description: z.string().optional().describe(WIKILINK_DESC),
     priority: z.enum(TASK_PRIORITIES).optional(),
     categoryId: z.string().optional(),
     dueDate: z.string().optional().describe('YYYY-MM-DD'),
@@ -2236,14 +2246,19 @@ export function createServer() {
     '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 }))
 
+  // ORQ-414: puntos de la idea, mismo shape que agendaItems de las actividades.
+  const NOTE_ITEMS = z.array(z.union([z.string(), z.object({ id: z.string().optional(), text: z.string() })])).optional()
+    .describe('Puntos de la idea, debajo de la descripción (body). Lista simple, NO checklist (sin palomitas). Reemplaza la lista COMPLETA: para agregar uno, lee la actual con list_notes y manda todos (con sus id para conservarlos).')
+
   registerCreate(
     'create_note',
     '/v1/notes',
-    'Crea una nota en un proyecto de Orquestra. En el texto, [[Título]] o [[Título|texto]] enlaza otra nota, doc, tarea o idea del proyecto (o [[ORQ-123]] por folio) -- úsalo para conectar el conocimiento en vez de pegar ids.',
+    'Crea una nota en un proyecto de Orquestra. En el texto, [[Título]] o [[Título|texto]] enlaza otra nota, doc, tarea, reunión, idea, riesgo, módulo, contenido o distribución del proyecto (o [[ORQ-123]] por folio) -- úsalo para conectar el conocimiento en vez de pegar ids.',
     {
       relatedTo: RELATED_TO,
       title: z.string().describe('Título de la nota'),
-      body: z.string().optional(),
+      body: z.string().optional().describe('Descripción de la nota.'),
+      noteItems: NOTE_ITEMS,
       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)'),
@@ -2265,6 +2280,7 @@ export function createServer() {
     {
       title: z.string().optional(),
       body: z.string().optional(),
+      noteItems: NOTE_ITEMS,
       pinned: z.boolean().optional(),
       moduleId: z.string().optional(),
       taskId: z.string().optional(),
@@ -2315,7 +2331,7 @@ export function createServer() {
   registerCreate(
     'create_doc',
     '/v1/docs',
-    'Crea un documento en un proyecto de Orquestra. En el texto, [[Título]] o [[Título|texto]] enlaza otra nota, doc, tarea o idea del proyecto (o [[ORQ-123]] por folio) -- úsalo para conectar el conocimiento en vez de pegar ids.',
+    'Crea un documento en un proyecto de Orquestra. En el texto, [[Título]] o [[Título|texto]] enlaza otra nota, doc, tarea, reunión, idea, riesgo, módulo, contenido o distribución del proyecto (o [[ORQ-123]] por folio) -- úsalo para conectar el conocimiento en vez de pegar ids.',
     {
       relatedTo: RELATED_TO,
       type: z.enum(DOC_TYPES).optional().describe('Tipo de documento -- obligatorio salvo que mandes templateId (la plantilla trae su tipo)'),
@@ -2352,7 +2368,7 @@ export function createServer() {
     'Edita un documento existente. Solo se cambian los campos que mandes; content REEMPLAZA el texto entero (lee primero con get_doc y manda el documento completo, no solo el cambio). La versión anterior queda en el historial del doc ("Versiones"). Si cambias el título, los [[Título viejo]] de todo el proyecto se reescriben solos.',
     {
       title: z.string().optional(),
-      content: z.string().optional().describe('Markdown completo del doc. [[Título]] enlaza otra nota, doc, tarea o idea.'),
+      content: z.string().optional().describe('Markdown completo del doc. [[Título]] enlaza otra nota, doc, tarea, reunión, idea, riesgo, módulo, contenido o distribución.'),
       type: z.enum(DOC_TYPES).optional(),
       adrStatus: z.enum(ADR_STATUSES).optional().describe('Solo para type=\'adr\'.'),
       adrContext: z.string().optional().describe('Solo para type=\'adr\'.'),
@@ -2372,7 +2388,7 @@ export function createServer() {
   const MODULE_KEY = z.string().optional().describe('Clave del módulo (ej. "AUTH", "PAGOS"): 2-10 letras/números, empieza con letra, única en el proyecto. Numera sus tareas (AUTH-1, AUTH-2...) en moduleCode, además del folio ORQ-N. Solo si el usuario la pidió o el proyecto ya usa claves -- no la inventes.')
   registerCreate('create_module', '/v1/modules', 'Crea un módulo en un proyecto de Orquestra.', {
     name: z.string().describe('Nombre del módulo'),
-    description: z.string().optional(),
+    description: z.string().optional().describe(WIKILINK_DESC),
     statusId: z.string().optional(),
     categoryId: z.string().optional(),
     scope: SCOPE_SCHEMA.describe('Alcance por distribución, ej: [{distId, layer, done}]'),
@@ -2381,12 +2397,12 @@ export function createServer() {
     shippedVersion: z.string().optional().describe('Versión del changelog en la que se envió, ej: "1.4.0"'),
     ownerUid: z.string().optional().describe('uid del miembro responsable del avance del módulo'),
     dependsOnModuleIds: z.array(z.string()).optional().describe('IDs de módulos de los que este depende (dependencia planeada, manual)'),
-    closureCriteria: z.string().optional().describe('Texto libre: cuándo se considera verdaderamente cerrado'),
+    closureCriteria: z.string().optional().describe(`Texto libre: cuándo se considera verdaderamente cerrado. ${WIKILINK_DESC}`),
     key: MODULE_KEY,
   })
   registerUpdate('update_module', '/v1/modules', 'Edita un módulo existente (incluido su scope multiplataforma).', {
     name: z.string().optional(),
-    description: z.string().optional(),
+    description: z.string().optional().describe(WIKILINK_DESC),
     statusId: z.string().optional(),
     categoryId: z.string().optional(),
     scope: SCOPE_SCHEMA,
@@ -2395,7 +2411,7 @@ export function createServer() {
     shippedVersion: z.string().optional().describe('Versión del changelog en la que se envió, ej: "1.4.0"'),
     ownerUid: z.string().optional().describe('uid del miembro responsable del avance del módulo'),
     dependsOnModuleIds: z.array(z.string()).optional().describe('IDs de módulos de los que este depende (dependencia planeada, manual)'),
-    closureCriteria: z.string().optional().describe('Texto libre: cuándo se considera verdaderamente cerrado'),
+    closureCriteria: z.string().optional().describe(`Texto libre: cuándo se considera verdaderamente cerrado. ${WIKILINK_DESC}`),
     key: MODULE_KEY.describe(`${MODULE_KEY.description} Poner o cambiar la clave numera las tareas del módulo que todavía no tienen una (por orden de creación; la respuesta trae assignedCodes). "" la quita: las tareas conservan la suya.`),
   })
 
@@ -2678,10 +2694,10 @@ export function createServer() {
   registerCreate('create_risk', '/v1/risks', 'Registra un riesgo/bloqueo a nivel de proyecto -- algo que puede hacer fallar o atrasar el proyecto en general, no el bloqueo puntual de una tarea (para eso usa relatedTaskId en update_task).', {
     relatedTo: RELATED_TO,
     title: z.string(),
-    description: z.string().optional(),
+    description: z.string().optional().describe(WIKILINK_DESC),
     probability: z.enum(RISK_LEVELS).optional().describe('Default: medium'),
     impact: z.enum(RISK_LEVELS).optional().describe('Default: medium'),
-    mitigation: z.string().optional().describe('Plan o texto libre de qué se hace para reducir este riesgo'),
+    mitigation: z.string().optional().describe(`Plan o texto libre de qué se hace para reducir este riesgo. ${WIKILINK_DESC}`),
     status: z.enum(RISK_STATUSES).optional().describe('Default: open. "closed" en vez de borrar -- nunca se borra un riesgo.'),
     ownerUid: z.string().optional().describe('Dueño del riesgo -- le avisa solo a esa persona al asignarla (ver list de miembros del workspace)'),
     moduleId: z.string().optional().describe('Módulo relacionado, si aplica (ver list_modules)'),
@@ -2689,10 +2705,10 @@ export function createServer() {
 
   registerUpdate('update_risk', '/v1/risks', 'Edita un riesgo existente -- típicamente para actualizar su mitigación o cerrarlo (status: "closed") cuando deja de aplicar.', {
     title: z.string().optional(),
-    description: z.string().optional(),
+    description: z.string().optional().describe(WIKILINK_DESC),
     probability: z.enum(RISK_LEVELS).optional(),
     impact: z.enum(RISK_LEVELS).optional(),
-    mitigation: z.string().optional(),
+    mitigation: z.string().optional().describe(WIKILINK_DESC),
     status: z.enum(RISK_STATUSES).optional(),
     ownerUid: z.string().optional(),
     moduleId: z.string().optional(),

package/src/setup.mjs

@@ -4,7 +4,7 @@ import { exec } from 'child_process'
 import { createInterface } from 'readline'
 import { homedir } from 'os'
 import { resolve } from 'path'
-import { upsertProjectMapping, CONFIG_PATH } from './configFile.mjs'
+import { upsertProjectMapping, replaceAgentToken, connectedAgents, readOrCreateMachine, agentKey, CONFIG_PATH } from './configFile.mjs'
 
 const DEFAULT_API_BASE = 'https://api.orquestra.me'
 const DEFAULT_WEB_URL = 'https://app.orquestra.me'
@@ -15,12 +15,16 @@ function openBrowser(url) {
   exec(`${cmd} "${url}"`, () => {})
 }
 
+// Herramientas conocidas (ORQ-415): cada una queda como su propio agente en
+// Orquestra ("Codex · MacBook-Pro") y con su propio token en la carpeta.
+const TOOLS = ['Claude Code', 'Codex', 'Cursor', 'Gemini CLI', 'Claude Desktop']
+
 function prompt(question) {
   const rl = createInterface({ input: process.stdin, output: process.stdout })
   return new Promise(resolve => rl.question(question, answer => { rl.close(); resolve(answer) }))
 }
 
-export async function runSetup() {
+export async function runSetup({ agent: presetAgent } = {}) {
   const apiBase = process.env.ORQUESTRA_API_BASE || DEFAULT_API_BASE
   const webUrl = process.env.ORQUESTRA_WEB_URL || DEFAULT_WEB_URL
   const state = randomBytes(16).toString('hex')
@@ -75,8 +79,9 @@ export async function runSetup() {
   const idToken = await idTokenPromise
   console.log('Login recibido, configurando...')
 
-  const agentLabelAnswer = await prompt('¿Cómo se llama este agente/herramienta? [Claude Code]: ')
-  const agentLabel = agentLabelAnswer.trim() || 'Claude Code'
+  const machine = readOrCreateMachine()
+  const agentLabel = await chooseTool(presetAgent, machine)
+  const agent = agentKey(agentLabel)
 
   // askIfMissing: si no hay workspace la API no crea nada solo -- avisa
   // (needsWorkspace) y aquí se le pide el nombre al usuario.
@@ -84,7 +89,7 @@ export async function runSetup() {
     const res = await fetch(`${apiBase}/v1/bootstrap`, {
       method: 'POST',
       headers: { Authorization: `Bearer ${idToken}`, 'Content-Type': 'application/json' },
-      body: JSON.stringify({ agentLabel, askIfMissing: true, ...extra }),
+      body: JSON.stringify({ agentLabel, machineId: machine.id, machineName: machine.name, askIfMissing: true, ...extra }),
     })
     const body = await res.json()
     if (!res.ok) throw new Error(body?.error || `HTTP ${res.status}`)
@@ -123,6 +128,14 @@ export async function runSetup() {
   }
 
   const { workspaceId, token, projects } = body
+  // La API anterior a ORQ-415 no manda `agent`.
+  // El token anterior ya quedó revocado en el servidor: se reemplaza en todas
+  // las carpetas de esta herramienta AHORA, antes de las preguntas, para que
+  // cancelar el setup a la mitad no deje carpetas con un token muerto.
+  const renewedFolders = body.agent?.known ? replaceAgentToken({ workspaceId, agent, apiToken: token }) : []
+  if (body.agent?.known) console.log(`\nYa te conocía: "${body.agent.name}". Renové su token (el anterior quedó revocado).`)
+  else if (body.agent?.adopted) console.log(`\nTu agente "${agentLabel}" de antes quedó ligado a esta máquina como "${body.agent.name}".`)
+  else if (body.agent) console.log(`\nNuevo agente en tu equipo de Orquestra: "${body.agent.name}".`)
   // La API de producción anterior a ORQ-388 no manda workspaceName.
   const wsLabel = body.workspaceName ? ` del workspace "${body.workspaceName}"` : ''
   let defaultProjectId
@@ -173,20 +186,64 @@ export async function runSetup() {
     : folderAnswer.trim()
   const folderPath = expanded ? resolve(expanded) : process.cwd()
 
-  upsertProjectMapping({ apiBase, apiToken: token, workspaceId, folderPath, projectId: defaultProjectId })
-  console.log(`\nListo. "${folderPath}" (y sus subcarpetas) ya apunta a este proyecto -- guardado en ${CONFIG_PATH}.`)
-  // En Windows Claude Code necesita `cmd /c` para lanzar npx, y el config de
-  // Claude Desktop vive en %APPDATA%. `@latest` evita que npx reuse una
-  // versión vieja de su caché.
-  const isWindows = process.platform === 'win32'
-  console.log('\nSiguiente paso -- conéctalo a tu agente de IA:\n')
-  console.log('  Claude Code:')
-  console.log(`    claude mcp add orquestra -- ${isWindows ? 'cmd /c ' : ''}npx -y orquestra-mcp@latest`)
-  if (isWindows) console.log('    (si "claude" no se reconoce: npm install -g @anthropic-ai/claude-code y abre otra terminal)')
-  console.log('    Después reinicia Claude Code o reconéctalo con /mcp.\n')
-  console.log(`  Claude Desktop -- agrega esto a ${isWindows ? '%APPDATA%\\Claude\\' : '~/Library/Application Support/Claude/'}claude_desktop_config.json:`)
-  console.log('    { "mcpServers": { "orquestra": { "command": "npx", "args": ["-y", "orquestra-mcp@latest"] } } }\n')
-  console.log('  ¿Usas Cursor, ChatGPT/Codex o Gemini CLI? La config de cada uno está en:')
-  console.log('    https://www.orquestra.me/mcp#instalacion\n')
+  upsertProjectMapping({ apiBase, apiToken: token, workspaceId, folderPath, projectId: defaultProjectId, agent })
+  const others = renewedFolders.filter(f => f !== folderPath)
+  console.log(`\nListo. "${folderPath}" (y sus subcarpetas) ya apunta a este proyecto con ${agentLabel} -- guardado en ${CONFIG_PATH}.`)
+  if (others.length) console.log(`También actualicé el token de ${agentLabel} en: ${others.join(', ')}.`)
+  console.log('\nSiguiente paso -- conéctalo a tu herramienta (si ya estaba conectada, solo reconecta el MCP):\n')
+  console.log(connectionHelp(agent, agentLabel))
+  console.log('\n¿Otra herramienta en esta misma carpeta? Corre de nuevo "npx orquestra-mcp@latest setup" y elígela:')
+  console.log('cada una firma con su propio agente.')
   console.log('Docs completas y todas las tools disponibles: https://www.orquestra.me/mcp')
 }
+
+// Sin preguntar "¿cómo se llama?" cada vez: se elige de la lista (o viene con
+// --agent) y se marca lo que ya está conectado en esta máquina.
+async function chooseTool(preset, machine) {
+  if (preset?.trim()) return TOOLS.find(t => agentKey(t) === agentKey(preset)) || preset.trim()
+  const connected = connectedAgents()
+  const already = TOOLS.filter(t => connected.has(agentKey(t)))
+  console.log(`\nEsta máquina: ${machine.name}${already.length ? ` (ya conectadas: ${already.join(', ')})` : ''}`)
+  console.log('¿Para qué herramienta es esta conexión?')
+  TOOLS.forEach((t, i) => console.log(`  ${i + 1}. ${t}${connected.has(agentKey(t)) ? ' (ya conectada: renueva su token)' : ''}`))
+  console.log(`  ${TOOLS.length + 1}. Otra`)
+  for (;;) {
+    const answer = (await prompt('Número [Enter para Claude Code]: ')).trim()
+    const idx = answer === '' ? 1 : parseInt(answer, 10)
+    if (idx >= 1 && idx <= TOOLS.length) return TOOLS[idx - 1]
+    if (idx === TOOLS.length + 1) {
+      const name = (await prompt('Nombre de la herramienta: ')).trim()
+      if (name) return name
+    }
+    console.log('Selección inválida.')
+  }
+}
+
+// La config de cada herramienta lleva ORQUESTRA_AGENT para que use SU token
+// (sin eso usaría el default de la carpeta y firmaría como otra).
+// En Windows Claude Code necesita `cmd /c` para lanzar npx, y el config de
+// Claude Desktop vive en %APPDATA%. `@latest` evita que npx reuse una
+// versión vieja de su caché.
+function connectionHelp(agent, agentLabel) {
+  const isWindows = process.platform === 'win32'
+  const json = file => `  ${agentLabel} -- agrega esto a ${file}:\n` +
+    `    { "mcpServers": { "orquestra": { "command": "npx", "args": ["-y", "orquestra-mcp@latest"], "env": { "ORQUESTRA_AGENT": "${agent}" } } } }`
+  if (agent === 'claude-code') {
+    return '  Claude Code:\n' +
+      `    claude mcp add orquestra -e ORQUESTRA_AGENT=${agent} -- ${isWindows ? 'cmd /c ' : ''}npx -y orquestra-mcp@latest\n` +
+      (isWindows ? '    (si "claude" no se reconoce: npm install -g @anthropic-ai/claude-code y abre otra terminal)\n' : '') +
+      '    (si ya estaba agregado: claude mcp remove orquestra y vuelve a agregarlo)\n' +
+      '    Después reinicia Claude Code o reconéctalo con /mcp.'
+  }
+  if (agent === 'codex') {
+    return '  Codex -- en ~/.codex/config.toml:\n' +
+      '    [mcp_servers.orquestra]\n' +
+      '    command = "npx"\n' +
+      '    args = ["-y", "orquestra-mcp@latest"]\n' +
+      `    env = { ORQUESTRA_AGENT = "${agent}" }`
+  }
+  if (agent === 'cursor') return json('~/.cursor/mcp.json')
+  if (agent === 'gemini-cli') return json('~/.gemini/settings.json')
+  if (agent === 'claude-desktop') return json(`${isWindows ? '%APPDATA%\\Claude\\' : '~/Library/Application Support/Claude/'}claude_desktop_config.json`)
+  return json('la config de MCP de tu herramienta') + '\n  Guía por herramienta: https://www.orquestra.me/mcp#instalacion'
+}

package/src/updateCheck.mjs

@@ -0,0 +1,56 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+// Aviso de versión nueva (ORQ-415): al arrancar, el server pregunta a npm cuál
+// es la última versión publicada (caché de 12 h en ~/.orquestra, así casi
+// ningún arranque sale a la red) y get_project_context la devuelve en
+// `orquestraMcpUpdate` para que el agente le diga al usuario cómo actualizar.
+// Nunca bloquea el arranque ni falla: sin red simplemente no hay aviso.
+const CACHE_PATH = join(homedir(), '.orquestra', 'update-check.json')
+const CACHE_TTL_MS = 12 * 60 * 60 * 1000
+const REGISTRY_URL = 'https://registry.npmjs.org/orquestra-mcp/latest'
+
+let latestKnown = null
+
+export function isNewer(latest, current) {
+  const parts = v => String(v).split('-')[0].split('.').map(n => parseInt(n, 10) || 0)
+  const [a, b] = [parts(latest), parts(current)]
+  for (let i = 0; i < 3; i++) {
+    if ((a[i] || 0) !== (b[i] || 0)) return (a[i] || 0) > (b[i] || 0)
+  }
+  return false
+}
+
+export async function startUpdateCheck({ fetchImpl = fetch, now = Date.now() } = {}) {
+  if (process.env.ORQUESTRA_NO_UPDATE_CHECK) return null
+  try {
+    const cached = JSON.parse(readFileSync(CACHE_PATH, 'utf8'))
+    if (cached.latest && now - cached.checkedAt < CACHE_TTL_MS) return (latestKnown = cached.latest)
+  } catch {}
+  try {
+    const res = await fetchImpl(REGISTRY_URL, { signal: AbortSignal.timeout(3000) })
+    if (!res.ok) return null
+    const { version } = await res.json()
+    if (!version) return null
+    latestKnown = version
+    mkdirSync(dirname(CACHE_PATH), { recursive: true })
+    writeFileSync(CACHE_PATH, JSON.stringify({ latest: version, checkedAt: now }))
+    return version
+  } catch {
+    return null
+  }
+}
+
+export function updateNotice(current) {
+  if (!latestKnown || !isNewer(latestKnown, current)) return null
+  return {
+    current,
+    latest: latestKnown,
+    message:
+      `Hay una versión nueva de orquestra-mcp (${latestKnown}; esta sesión usa ${current}). ` +
+      `Para actualizar, reinicia tu herramienta o reconecta el MCP (en Claude Code: /mcp → orquestra → Reconnect). ` +
+      `Si sigue la versión vieja, en la config del MCP cambia "orquestra-mcp" por "orquestra-mcp@latest" ` +
+      `(sin @latest, npx reusa la versión que tiene en caché). Novedades: https://www.orquestra.me/mcp`,
+  }
+}