orquestra-mcp 1.33.0 → 1.37.0

package/bin/orquestra-mcp.mjs

@@ -2,6 +2,7 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { createServer } from '../src/server.mjs'
 import { runSetup } from '../src/setup.mjs'
+import { runVaultSync } from '../src/vaultSync.mjs'
 
 const HELP_TEXT = `orquestra-mcp -- Servidor MCP de Orquestra (35 tools)
 
@@ -9,6 +10,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 + configura tu proyecto default
+  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)
   npx orquestra-mcp --help     Muestra esta ayuda
 
 Config (la deja lista "setup"): ~/.orquestra/mcp-config.json
@@ -31,6 +35,16 @@ async function main() {
     return
   }
 
+  if (cmd === 'vault' && process.argv[3] === 'sync') {
+    try {
+      await runVaultSync(process.argv.slice(4))
+    } catch (err) {
+      console.error(`[orquestra-mcp] ${err.message}`)
+      process.exit(1)
+    }
+    return
+  }
+
   let server
   try {
     server = createServer()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orquestra-mcp",
-  "version": "1.33.0",
+  "version": "1.37.0",
   "description": "Servidor MCP de Orquestra -- 115 tools para leer y escribir tareas, ideas, changelog, infraestructura, contenido, QA y más desde un agente de IA",
   "type": "module",
   "bin": {
@@ -27,5 +27,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
     "zod": "^4.6.5"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
   }
 }

package/src/server.mjs

@@ -102,6 +102,7 @@ Durante el trabajo normal de código, sin que el usuario te lo pida explícitame
 - Orquestra es el ÚNICO lugar donde se planea y se lleva el avance del trabajo: el plan de pasos va como checklist de la tarea (add_checklist_item) y se marca con update_checklist_item conforme terminas cada uno. No lleves una lista de pendientes paralela en el chat, en archivos temporales ni en la herramienta de tareas de tu propio cliente -- se pierde al cerrar la sesión y el usuario no la ve. Si retomas trabajo en una sesión nueva, parte de la tarea y sus ítems pendientes (list_tasks + list_checklist_items), no de cero. Excepción: un cambio de un solo paso (renombrar algo, responder una pregunta) no necesita tarea.
 - 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).
+- Conocimiento que sirve más allá de un proyecto (guías, procesos, decisiones transversales) va en la base del workspace: revisa list_knowledge antes de documentarlo de nuevo, créalo con create_knowledge o súbelo con promote_to_knowledge; lo de un solo proyecto sigue en notas/docs.
 - Reuniones, llamadas y seguimientos NO son tareas: son actividades (no se entregan, se programan y se registran). Usa log_activity para agendarlas o registrarlas, update_activity para marcarlas hechas con su resultado (outcome) y siguiente paso (nextStep), y list_activities para ver la agenda/bitácora -- nunca create_task con esos tipos. Si del siguiente paso sale trabajo real, eso sí es una tarea (create_task normal, con módulo y fecha).
 - 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.
@@ -248,7 +249,7 @@ export function createServer() {
     'Busca por texto en tareas, actividades (reuniones/llamadas), notas, ideas y docs de un proyecto de Orquestra. Tope de 30 resultados con las tareas primero: 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'])).optional().describe('Limitar a estos tipos (opcional). Sin esto busca en todos.'),
+      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.'),
     },
     (args, projectId) => ({ projectId, q: args.q, types: args.types?.join(',') })
   )
@@ -767,6 +768,103 @@ export function createServer() {
     }
   )
 
+  // Base de conocimiento del workspace (ORQ-298) -- ver lib/knowledge.mjs en orquestra-infra.
+  registerRead(
+    'list_knowledge',
+    '/v1/knowledge',
+    'Lista la base de conocimiento del WORKSPACE (guías, procesos, decisiones que no son de un solo proyecto). Cuerpo recortado a 300 caracteres salvo full=true. linkedTo=projectId trae solo lo vinculado a ese proyecto. Revísala antes de documentar algo que quizá ya existe.',
+    {
+      q: z.string().optional().describe('Texto a buscar en título/cuerpo'),
+      tag: z.string().optional(),
+      linkedTo: z.string().optional().describe('projectId: solo entradas vinculadas a ese proyecto'),
+      full: z.boolean().optional().describe('true = cuerpo completo'),
+    },
+    (args, projectId) => ({ projectId, q: args.q, tag: args.tag, linkedTo: args.linkedTo, full: args.full ? 'true' : undefined })
+  )
+
+  server.registerTool(
+    'get_knowledge',
+    {
+      description: 'Lee una entrada completa de la base de conocimiento del workspace.',
+      inputSchema: { projectId: z.string().optional().describe(PROJECT_ID_DESC), id: z.string() },
+    },
+    async ({ projectId, id }) => {
+      try { return textResult(await apiGet(config, `/v1/knowledge/${id}`, { projectId: resolveProjectId(projectId) })) } catch (err) { return errorResult(err) }
+    }
+  )
+
+  registerCreate(
+    'create_knowledge',
+    '/v1/knowledge',
+    'Crea una entrada en la base de conocimiento del WORKSPACE (no de un proyecto). Úsala para lo reutilizable entre proyectos; lo específico de un proyecto va en create_note/create_doc. [[Título]] enlaza otra entrada de la base.',
+    {
+      title: z.string(),
+      body: z.string().optional().describe('Markdown'),
+      tags: z.array(z.string()).optional(),
+      visibility: z.enum(['workspace', 'private']).optional().describe('Default workspace. private = solo la ve quien la creó.'),
+      linkToProject: z.boolean().optional().describe('true = vincularla de una vez al proyecto actual'),
+    }
+  )
+
+  registerUpdate('update_knowledge', '/v1/knowledge',
+    'Edita una entrada de la base de conocimiento del workspace (solo los campos que mandes).',
+    {
+      title: z.string().optional(),
+      body: z.string().optional(),
+      tags: z.array(z.string()).optional().describe('Reemplaza la lista completa'),
+      visibility: z.enum(['workspace', 'private']).optional(),
+    }
+  )
+
+  server.registerTool(
+    'link_knowledge_to_project',
+    {
+      description: 'Lleva una entrada de la base a un proyecto. mode "link" (default) = referencia viva: aparece en el proyecto y entra al contexto del asistente; "unlink" la quita; "copy" crea una nota o doc independiente en el proyecto (snapshot, ya no se actualiza).',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        id: z.string().describe('id de la entrada (ver list_knowledge)'),
+        mode: z.enum(['link', 'unlink', 'copy']).optional(),
+        as: z.enum(['note', 'doc']).optional().describe('Solo para copy. Default note.'),
+        docType: z.enum(DOC_TYPES).optional().describe('Solo para copy como doc. Default readme.'),
+      },
+    },
+    async ({ projectId, id, ...body }) => {
+      try { return textResult(await apiPost(config, `/v1/knowledge/${id}/link`, { projectId: resolveProjectId(projectId), ...body })) } catch (err) { return errorResult(err) }
+    }
+  )
+
+  registerCreate(
+    'promote_to_knowledge',
+    '/v1/knowledge/promote',
+    'Promueve una nota o doc del proyecto a la base de conocimiento del workspace (cuando sirve más allá de este proyecto). El original no se borra: queda con knowledgeId y la entrada queda vinculada a este proyecto. Solo se puede promover una vez.',
+    {
+      type: z.enum(['note', 'doc']),
+      id: z.string(),
+      tags: z.array(z.string()).optional(),
+    }
+  )
+
+  // Plantillas (ORQ-297): base (código) + propias del workspace.
+  registerRead(
+    'list_templates',
+    '/v1/templates',
+    'Plantillas de notas y docs: las base de Orquestra (minuta de reunión, retro, propuesta a cliente, checklist de lanzamiento, ADR, runbook; ids "builtin:*") y las propias del workspace. Úsalas con templateId en create_note/create_doc en vez de inventar la estructura.',
+    { kind: z.enum(['note', 'doc']).optional() },
+    (args, projectId) => ({ projectId, kind: args.kind })
+  )
+
+  // Wikilinks (ORQ-296): backlinks calculados del texto en el server (lib/wikilinks.mjs).
+  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.',
+    {
+      type: z.enum(['note', 'doc', 'task', 'idea']),
+      id: z.string().describe('id de la nota/doc/tarea/idea'),
+    },
+    (args, projectId) => ({ projectId, type: args.type, id: args.id })
+  )
+
   registerRead(
     'list_activities',
     '/v1/activities',
@@ -1789,7 +1887,7 @@ export function createServer() {
   registerCreate(
     'create_note',
     '/v1/notes',
-    'Crea una nota en un proyecto de Orquestra.',
+    '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.',
     {
       title: z.string().describe('Título de la nota'),
       body: z.string().optional(),
@@ -1802,12 +1900,15 @@ export function createServer() {
       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.'),
+      templateId: z.string().optional().describe('Plantilla (ver list_templates): rellena el texto si no mandas uno, y el tipo si no lo mandas. Las variables {{fecha}}/{{proyecto}}/{{autor}}/{{titulo}} se resuelven solas.'),
+      templateVars: z.object({ fecha: z.string().optional(), proyecto: z.string().optional(), autor: z.string().optional(), titulo: z.string().optional() }).optional()
+        .describe('Sobrescribe variables de la plantilla -- útil para {{fecha}} en la hora local del usuario.'),
       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.',
+    'Edita una nota existente. Todos los campos son opcionales -- solo se cambian los que mandes. Si cambias el título, los [[Título viejo]] de todo el proyecto se reescriben solos.',
     {
       title: z.string().optional(),
       body: z.string().optional(),
@@ -1861,11 +1962,14 @@ export function createServer() {
   registerCreate(
     'create_doc',
     '/v1/docs',
-    'Crea un documento en un proyecto de Orquestra.',
+    '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.',
     {
-      type: z.enum(DOC_TYPES).describe('Tipo de documento'),
+      type: z.enum(DOC_TYPES).optional().describe('Tipo de documento -- obligatorio salvo que mandes templateId (la plantilla trae su tipo)'),
       title: z.string().describe('Título del documento'),
       content: z.string().optional(),
+      templateId: z.string().optional().describe('Plantilla (ver list_templates): rellena el texto si no mandas uno, y el tipo si no lo mandas. Las variables {{fecha}}/{{proyecto}}/{{autor}}/{{titulo}} se resuelven solas.'),
+      templateVars: z.object({ fecha: z.string().optional(), proyecto: z.string().optional(), autor: z.string().optional(), titulo: z.string().optional() }).optional()
+        .describe('Sobrescribe variables de la plantilla -- útil para {{fecha}} en la hora local del usuario.'),
       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.'),

package/src/vaultSync.mjs

@@ -0,0 +1,249 @@
+// Sincronización con un vault de Obsidian (ORQ-299): `orquestra-mcp vault sync <carpeta>`.
+//
+// Sincroniza la BASE DE CONOCIMIENTO DEL WORKSPACE (ORQ-298, /v1/knowledge) con
+// una carpeta del vault, en los dos sentidos. Obsidian queda como editor y
+// Orquestra como respaldo, búsqueda y contexto de IA. Cada entrada es un .md
+// cuyo NOMBRE es el título (así [[Título]] resuelve igual en Obsidian y en
+// Orquestra) con frontmatter:
+//   orquestraId, orquestraUpdatedAt, orquestraTitle (si el nombre tuvo que
+//   sanearse), tags. Cualquier otra clave del frontmatter se conserva.
+// `.orquestra-sync.json` en la carpeta guarda lo último sincronizado de cada
+// lado (updatedAt remoto + hash local) para saber quién cambió.
+// Conflicto (cambiaron los dos): gana el más reciente y el otro lado queda
+// como "<nombre>.conflict.md" junto al archivo. Nada se borra nunca: una
+// entrada borrada en el vault se vuelve a bajar, y un .md con orquestraId que
+// ya no existe en Orquestra solo se reporta.
+// Fuera de alcance v1: adjuntos/imágenes del vault (se reportan, no se suben).
+import { createHash } from 'node:crypto'
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { loadConfig, apiGet, apiPost, apiPatch } from './api.mjs'
+
+export const STATE_FILE = '.orquestra-sync.json'
+const CONFLICT_SUFFIX = '.conflict.md'
+
+// ── Formato ─────────────────────────────────────────────────────────────────
+
+export function sanitizeFileName(title) {
+  const clean = (title || 'Sin título').replace(/[\\/:*?"<>|#^[\]]/g, '-').replace(/\s+/g, ' ').trim().slice(0, 120)
+  return clean || 'Sin título'
+}
+
+const unquote = v => v.replace(/^["']|["']$/g, '')
+
+/** { meta: {orquestraId, orquestraUpdatedAt, orquestraTitle, tags}, extra: [líneas], body } */
+export function parseNote(text) {
+  const meta = { tags: [] }
+  const extra = []
+  let body = text
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/)
+  if (m) {
+    body = text.slice(m[0].length)
+    const lines = m[1].split(/\r?\n/)
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i]
+      const kv = line.match(/^([A-Za-z][\w-]*):\s*(.*)$/)
+      if (!kv) { extra.push(line); continue }
+      const [, key, raw] = kv
+      if (key === 'tags') {
+        if (raw.startsWith('[')) {
+          meta.tags = raw.replace(/^\[|\]$/g, '').split(',').map(t => unquote(t.trim())).filter(Boolean)
+        } else if (raw.trim()) {
+          meta.tags = raw.split(/[,\s]+/).map(t => unquote(t.trim())).filter(Boolean)
+        } else {
+          while (lines[i + 1]?.match(/^\s*-\s+/)) meta.tags.push(unquote(lines[++i].replace(/^\s*-\s+/, '').trim()))
+        }
+      } else if (key === 'orquestraId' || key === 'orquestraTitle') {
+        meta[key] = unquote(raw.trim())
+      } else if (key === 'orquestraUpdatedAt') {
+        meta.orquestraUpdatedAt = Number(raw.trim()) || 0
+      } else {
+        extra.push(line)
+      }
+    }
+  }
+  meta.tags = meta.tags.map(t => t.replace(/^#/, '').toLowerCase())
+  return { meta, extra, body }
+}
+
+export function serializeNote({ id, updatedAt, title, fileTitle, tags = [], body = '', extra = [] }) {
+  const lines = ['---']
+  if (id) lines.push(`orquestraId: ${id}`)
+  if (updatedAt) lines.push(`orquestraUpdatedAt: ${updatedAt}`)
+  if (title && title !== fileTitle) lines.push(`orquestraTitle: ${JSON.stringify(title)}`)
+  lines.push(`tags: [${tags.join(', ')}]`)
+  lines.push(...extra)
+  lines.push('---')
+  return `${lines.join('\n')}\n${body}`
+}
+
+/** Título real de un archivo: el de Orquestra si el nombre es solo su versión saneada, si no el nombre (lo renombraron). */
+export function titleOfFile(fileTitle, meta) {
+  return meta.orquestraTitle && sanitizeFileName(meta.orquestraTitle) === fileTitle ? meta.orquestraTitle : fileTitle
+}
+
+export function contentHash({ title, body, tags }) {
+  return createHash('sha1').update(`${title}\n${[...(tags || [])].sort().join(',')}\n${(body || '').replace(/\r\n/g, '\n').trimEnd()}`).digest('hex')
+}
+
+// ── Plan (puro, sin red ni disco) ───────────────────────────────────────────
+
+/**
+ * remote: [{id, title, body, tags, updatedAt}]
+ * local:  [{file, title, body, tags, id, mtimeMs, hash, extra}]
+ * state:  {entries: {[id]: {file, remoteUpdatedAt, localHash}}}
+ * → [{op, ...}] con op: pull | push | create | conflict | orphan
+ */
+export function planSync({ remote, local, state }) {
+  const entries = state?.entries || {}
+  const localById = new Map(local.filter(l => l.id).map(l => [l.id, l]))
+  const remoteIds = new Set(remote.map(r => r.id))
+  const plan = []
+
+  for (const r of remote) {
+    const l = localById.get(r.id)
+    const prev = entries[r.id]
+    if (!l) { plan.push({ op: 'pull', remote: r, reason: prev ? 'borrada en el vault, se restaura' : 'nueva en Orquestra' }); continue }
+    if (!prev) {
+      // Vinculada pero sin historial (state perdido): si difieren, conflicto; si no, nada.
+      if (contentHash(r) !== l.hash) plan.push({ op: 'conflict', remote: r, local: l, winner: (l.mtimeMs || 0) > (r.updatedAt || 0) ? 'local' : 'remote' })
+      continue
+    }
+    const remoteChanged = (r.updatedAt || 0) > (prev.remoteUpdatedAt || 0)
+    const localChanged = l.hash !== prev.localHash
+    if (remoteChanged && localChanged) {
+      plan.push({ op: 'conflict', remote: r, local: l, winner: (l.mtimeMs || 0) > (r.updatedAt || 0) ? 'local' : 'remote' })
+    } else if (remoteChanged) {
+      plan.push({ op: 'pull', remote: r, local: l, reason: 'cambió en Orquestra' })
+    } else if (localChanged) {
+      plan.push({ op: 'push', remote: r, local: l })
+    }
+  }
+  for (const l of local) {
+    if (!l.id) plan.push({ op: 'create', local: l })
+    else if (!remoteIds.has(l.id)) plan.push({ op: 'orphan', local: l })
+  }
+  return plan
+}
+
+// ── Disco ────────────────────────────────────────────────────────────────────
+
+async function scanVault(dir, rel = '') {
+  const out = []
+  for (const ent of await fs.readdir(path.join(dir, rel), { withFileTypes: true })) {
+    if (ent.name.startsWith('.')) continue
+    const relPath = path.join(rel, ent.name)
+    if (ent.isDirectory()) out.push(...await scanVault(dir, relPath))
+    else if (ent.name.endsWith('.md') && !ent.name.endsWith(CONFLICT_SUFFIX)) out.push(relPath)
+  }
+  return out
+}
+
+async function readLocal(dir) {
+  const files = await scanVault(dir)
+  const notes = []
+  const attachments = []
+  for (const file of files) {
+    const full = path.join(dir, file)
+    const [text, stat] = await Promise.all([fs.readFile(full, 'utf8'), fs.stat(full)])
+    const { meta, extra, body } = parseNote(text)
+    const fileTitle = path.basename(file, '.md')
+    const title = titleOfFile(fileTitle, meta)
+    const note = { file, title, body, tags: meta.tags, id: meta.orquestraId || null, mtimeMs: stat.mtimeMs, extra }
+    note.hash = contentHash(note)
+    notes.push(note)
+    for (const emb of body.matchAll(/!\[\[([^\]]+)\]\]|!\[[^\]]*\]\((?!https?:)([^)]+)\)/g)) attachments.push({ file, ref: emb[1] || emb[2] })
+  }
+  return { notes, attachments }
+}
+
+async function readState(dir) {
+  try { return JSON.parse(await fs.readFile(path.join(dir, STATE_FILE), 'utf8')) } catch { return null }
+}
+
+function uniqueFile(title, taken) {
+  const base = sanitizeFileName(title)
+  let name = `${base}.md`
+  for (let n = 2; taken.has(name.toLowerCase()); n++) name = `${base} (${n}).md`
+  taken.add(name.toLowerCase())
+  return name
+}
+
+// ── Comando ──────────────────────────────────────────────────────────────────
+
+const LABEL = { pull: '↓ bajar', push: '↑ subir', create: '↑ crear', conflict: '⚠ conflicto', orphan: '? sin entrada en Orquestra' }
+
+export async function runVaultSync(argv) {
+  const dirArg = argv.find(a => !a.startsWith('--'))
+  if (!dirArg) {
+    console.log('Uso: orquestra-mcp vault sync <carpeta-del-vault> [--apply | --dry-run]\n' +
+      'Sincroniza la base de conocimiento del workspace con esa carpeta. Córrelo desde la carpeta de un\n' +
+      'proyecto ya conectado con "orquestra-mcp setup" (de ahí salen la cuenta y el workspace).')
+    return
+  }
+  const dir = path.resolve(dirArg)
+  await fs.mkdir(dir, { recursive: true })
+  const config = loadConfig()
+  const projectId = config.defaultProjectId
+  if (!projectId) throw new Error('Esta carpeta no está conectada a un proyecto de Orquestra -- corre "npx orquestra-mcp setup" primero.')
+
+  const state = await readState(dir)
+  if (state && state.workspaceId !== config.workspaceId) {
+    throw new Error(`Esta carpeta ya se sincroniza con otro workspace (${state.workspaceId}). Usa otra carpeta.`)
+  }
+  // Primera vez: solo muestra el plan, salvo --apply explícito.
+  const apply = argv.includes('--apply') || (!!state && !argv.includes('--dry-run'))
+
+  const { items: remote } = await apiGet(config, '/v1/knowledge', { projectId, full: 'true' })
+  const { notes: local, attachments } = await readLocal(dir)
+  const plan = planSync({ remote, local, state })
+
+  console.log(`Vault: ${dir}\nOrquestra: ${remote.length} entradas · Vault: ${local.length} notas · ${plan.length} cambios${apply ? '' : ' (vista previa, no se escribe nada)'}`)
+  for (const p of plan) console.log(`  ${LABEL[p.op]}  ${p.local?.file || p.remote?.title}${p.reason ? `  (${p.reason})` : ''}${p.op === 'conflict' ? `  -- gana ${p.winner === 'local' ? 'el vault' : 'Orquestra'}` : ''}`)
+  if (attachments.length) console.log(`  ${attachments.length} imagen(es)/adjunto(s) del vault no se sincronizan en esta versión (solo texto).`)
+  if (!apply) {
+    if (plan.length) console.log('\nPara aplicar: orquestra-mcp vault sync ' + dirArg + ' --apply')
+    return
+  }
+
+  const entries = { ...(state?.entries || {}) }
+  const taken = new Set(local.map(l => path.basename(l.file).toLowerCase()))
+  const writeRemote = async (r, file, extra = []) => {
+    const fileTitle = path.basename(file, '.md')
+    await fs.mkdir(path.dirname(path.join(dir, file)), { recursive: true })
+    await fs.writeFile(path.join(dir, file), serializeNote({ id: r.id, updatedAt: r.updatedAt, title: r.title, fileTitle, tags: r.tags || [], body: r.body || '', extra }))
+    entries[r.id] = { file, remoteUpdatedAt: r.updatedAt || 0, localHash: contentHash({ title: r.title, body: r.body, tags: r.tags || [] }) }
+  }
+  const push = async (l, id) => {
+    const body = { projectId, title: l.title, body: l.body, tags: l.tags }
+    const saved = id ? await apiPatch(config, '/v1/knowledge', { id, ...body }) : await apiPost(config, '/v1/knowledge', body)
+    // Reescribe el frontmatter con el id/updatedAt nuevos, sin tocar el texto.
+    await writeRemote({ ...saved, title: l.title, body: l.body, tags: saved.tags || l.tags }, l.file, l.extra)
+  }
+  const saveConflictCopy = async (file, text) => {
+    await fs.writeFile(path.join(dir, file.replace(/\.md$/, CONFLICT_SUFFIX)), text)
+  }
+
+  let failed = 0
+  for (const p of plan) {
+    try {
+      if (p.op === 'pull') await writeRemote(p.remote, p.local?.file || entries[p.remote.id]?.file || uniqueFile(p.remote.title, taken), p.local?.extra)
+      else if (p.op === 'push') await push(p.local, p.remote.id)
+      else if (p.op === 'create') await push(p.local, null)
+      else if (p.op === 'conflict') {
+        if (p.winner === 'local') {
+          await saveConflictCopy(p.local.file, serializeNote({ id: p.remote.id, title: p.remote.title, fileTitle: '', tags: p.remote.tags || [], body: p.remote.body || '' }))
+          await push(p.local, p.remote.id)
+        } else {
+          await saveConflictCopy(p.local.file, await fs.readFile(path.join(dir, p.local.file), 'utf8'))
+          await writeRemote(p.remote, p.local.file, p.local.extra)
+        }
+      }
+    } catch (err) {
+      failed++
+      console.error(`  ✗ ${p.local?.file || p.remote?.title}: ${err.message}`)
+    }
+  }
+  await fs.writeFile(path.join(dir, STATE_FILE), JSON.stringify({ workspaceId: config.workspaceId, syncedAt: Date.now(), entries }, null, 2))
+  console.log(failed ? `\nListo con ${failed} error(es) -- vuelve a correrlo para reintentar.` : '\nListo.')
+}