orquestra-mcp 1.55.0 → 1.58.0

package/bin/orquestra-mcp.mjs

@@ -15,8 +15,10 @@ Uso:
                                 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)
+                                Sincroniza la base de conocimiento del workspace (notas e
+                                imágenes/videos) con una carpeta de tu vault de Obsidian.
+                                La 1ra vez solo muestra el plan; --help lista las opciones
+                                (--dry-run, --no-attachments, --verbose)
   npx orquestra-mcp --help     Muestra esta ayuda
 
 Config (la deja lista "setup"): ~/.orquestra/mcp-config.json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orquestra-mcp",
-  "version": "1.55.0",
+  "version": "1.58.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/server.mjs

@@ -284,7 +284,7 @@ export function createServer() {
   registerRead(
     'list_tasks',
     '/v1/tasks',
-    '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. No incluye actividades (reuniones/llamadas/seguimientos) -- esas van con list_activities.',
+    'Lista las tareas de un proyecto de Orquestra, opcionalmente filtradas por estatus/módulo/tipo/prioridad/responsable/tag/groupKey (código de agrupación, ej. V2). Cada tarea trae su groupCode si lo tiene. 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. No incluye actividades (reuniones/llamadas/seguimientos) -- esas van con list_activities.',
     {
       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)'),
@@ -293,6 +293,7 @@ export function createServer() {
       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)'),
       workCategory: z.enum(WORK_CATEGORIES).optional().describe('Categoría de trabajo para filtrar (opcional): plan | build | delivery | review'),
+      groupKey: z.string().max(10).optional().describe('Clave de agrupación exacta (ej. "V2") para traer solo las tareas de ese grupo (groupCode V2-1, V2-2...) -- úsalo antes de crear una tarea nueva de una iniciativa para reutilizar la clave y ver cuáles existen (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) => ({
@@ -304,6 +305,7 @@ export function createServer() {
       assignedTo: args.assignedTo,
       tag: args.tag,
       workCategory: args.workCategory,
+      groupKey: args.groupKey,
       includeClosed: args.includeClosed,
     })
   )
@@ -788,6 +790,7 @@ export function createServer() {
       skipParity: z.boolean().optional().describe('true = NO sumar las plataformas hermanas al scope aunque tengan el mismo productKey. Solo cuando el trabajo es genuinamente de UNA plataforma (ej. un ajuste de Gradle que no tiene contraparte en iOS) -- no lo mandes por default. Las tareas type="bug" nunca propagan, sin necesidad de esto.'),
       parityExempt: z.boolean().optional().describe('true = este trabajo es de UNA sola plataforma y no cuenta en get_parity_summary (se pone solo cuando skipParity va con scope de una sola dist). false para volver a contarla.'),
       parityOf: z.string().optional().describe('Folio: id de la tarea ORIGEN de la que esta es la hermana para otra plataforma (ej. la versión iOS de una tarea de Android). En paridad cuentan como UN item y al cerrar esta, su plataforma queda hecha en el origen. El origen no puede ser hermana de otra. "" lo quita.'),
+      groupKey: z.string().max(10).optional().describe('Código de agrupación (ORQ-464): clave corta de una iniciativa que cruza módulos (ej. "V2", "LANZ"; 2-10 letras/números, empieza con letra). El server asigna groupCode = clave + número ("V2-3"), separado del moduleCode y del folio ORQ-N. Úsalo cuando la tarea es parte de una iniciativa/entrega mayor que atraviesa varios módulos; propónlo tú al armar ese trabajo. Reutiliza la MISMA clave para todas las tareas del mismo grupo y revisa con list_tasks (groupKey) las que ya existen antes de inventar una nueva. No uses la clave de un módulo (400). Sin groupKey la tarea no lleva grupo.'),
       moduleCode: z.string().max(40).optional().describe('Clave de la tarea dentro de su módulo (ej. "AUTH-3"), ADEMÁS del folio ORQ-N. NO la mandes normalmente: si el módulo tiene clave (key), el server la asigna sola. Solo para conservar la clave que ya traía de otro sistema al importar (ej. "PROJ-128" de Jira/Linear).'),
       relatedTaskId: z.string().optional().describe('"Bloqueada por" -- id de otra tarea. LEGACY desde ORQ-248: si vas a bloquear por más de una tarea, usa blockedByIds en vez de esto (relatedTaskId se sigue llenando solo, como blockedByIds[0], para paridad con iOS/Android).'),
       blockedByIds: z.array(z.string()).optional().describe('"Bloqueada por" -- ids de otras tareas (puede ser más de una). Esta tarea se muestra como bloqueada mientras ALGUNA de esas no llegue a un estatus final (isFinal). Reemplaza a relatedTaskId para bloqueos múltiples -- preferí este campo, no relatedTaskId, salvo que de verdad sea un solo bloqueador.'),
@@ -836,6 +839,7 @@ export function createServer() {
         .describe('Alcance por distribución -- usa get_parity_summary para ver el scope actual antes de editarlo'),
       parityExempt: z.boolean().optional().describe('true = este trabajo es de UNA sola plataforma y no cuenta en get_parity_summary; false para volver a contarla.'),
       parityOf: z.string().optional().describe('Folio: id de la tarea ORIGEN de la que esta es la hermana para otra plataforma (ej. la versión iOS de una tarea de Android). En paridad cuentan como UN item y al cerrar esta, su plataforma queda hecha en el origen. El origen no puede ser hermana de otra. "" lo quita.'),
+      groupKey: z.string().max(10).optional().describe('Código de agrupación (ORQ-464): clave corta de una iniciativa que cruza módulos (ej. "V2"; 2-10 letras/números, empieza con letra). Estable: editar la tarea sin groupKey NO cambia su groupCode ni se gasta número si mandas la misma clave. Otra clave la reasigna (número nuevo de esa clave, ej. "LANZ-1"); "" quita el código. Reutiliza la misma clave para las tareas del mismo grupo y revisa antes con list_tasks (groupKey). No uses la clave de un módulo (400).'),
       moduleCode: z.string().max(40).optional().describe('Clave de la tarea dentro de su módulo (ej. "AUTH-3"), texto libre editable a mano. "" la quita. Mover la tarea a otro módulo (moduleId) NO la cambia: la clave es estable.'),
       relatedTaskId: z.string().optional().describe('"Bloqueada por" -- id de otra tarea, o "" para quitar el bloqueo. LEGACY, ver create_task -- preferí blockedByIds.'),
       blockedByIds: z.array(z.string()).optional().describe('"Bloqueada por" -- reemplaza el array COMPLETO (no hace merge), [] quita todos los bloqueos. Ver create_task.'),
@@ -872,8 +876,8 @@ export function createServer() {
     location: z.string().optional().describe('Plataforma o lugar ("Zoom", "Oficina del cliente") o contexto libre para un seguimiento.'),
     participants: z.array(z.string()).optional().describe('Nombres libres de quienes participan (cliente, equipo) -- no uids.'),
     description: z.string().optional().describe('Notas previas.'),
-    agendaItems: z.array(z.union([z.string(), z.object({ id: z.string().optional(), text: z.string(), group: z.string().max(60).optional(), createdAt: z.number().optional(), createdBy: z.string().optional() })])).optional()
-      .describe('Puntos a revisar en la reunión (ej. "Revisar [[ORQ-123]]"). Lista simple, NO checklist. Cada punto puede llevar group (agrupa puntos bajo un encabezado, máx. 60 caracteres). Reemplaza la lista COMPLETA: para agregar uno, lee la actual con list_activities y manda todos, con sus id para conservarlos Y con su group -- si reenvías un punto sin group, pierde su grupo.'),
+    agendaItems: z.array(z.union([z.string(), z.object({ id: z.string().optional(), text: z.string(), group: z.string().max(60).optional(), resolution: z.string().max(2000).optional(), resolutionStatus: z.enum(['pendiente', 'decidido', 'pospuesto', '']).optional(), createdAt: z.number().optional(), createdBy: z.string().optional() })])).optional()
+      .describe('Puntos a revisar en la reunión (ej. "Revisar [[ORQ-123]]"). Lista simple, NO checklist. Cada punto puede llevar group (agrupa puntos bajo un encabezado, máx. 60 caracteres). Reemplaza la lista COMPLETA: para agregar uno, lee la actual con list_activities y manda todos, con sus id para conservarlos Y con su group -- si reenvías un punto sin group, pierde su grupo. Cada punto puede llevar además resolution (qué se decidió, máx. 2000 caracteres) y resolutionStatus ("pendiente" | "decidido" | "pospuesto"): son informativos, NO bloquean el cierre de la actividad. Si reenvías un punto con su id sin esos campos, el server conserva los guardados; manda "" para borrarlos. list_activities los devuelve en cada punto.'),
     outcome: z.string().optional().describe('Resultado / minuta corta -- qué se acordó. Llénalo al marcarla hecha.'),
     nextStep: z.string().optional().describe('Siguiente paso acordado. Si es trabajo real, además crea la tarea con create_task y liga su id en nextStepTaskId.'),
     nextStepTaskId: z.string().optional().describe('id de la tarea creada desde nextStep.'),
@@ -1041,7 +1045,7 @@ export function createServer() {
   registerRead(
     'list_activities',
     '/v1/activities',
-    'Lista las actividades (reuniones, llamadas, seguimientos) de un proyecto de Orquestra. status "scheduled" = agenda (próximas primero), "done" = bitácora (más recientes primero); sin status trae todas. from/to acotan por día.',
+    'Lista las actividades (reuniones, llamadas, seguimientos) de un proyecto de Orquestra. status "scheduled" = agenda (próximas primero), "done" = bitácora (más recientes primero); sin status trae todas. from/to acotan por día. Cada punto de agendaItems puede traer resolution y resolutionStatus (pendiente/decidido/pospuesto).',
     {
       status: z.enum(ACTIVITY_STATUSES).optional(),
       type: z.enum(ACTIVITY_TYPES).optional(),

package/src/vaultAttachments.mjs

@@ -0,0 +1,190 @@
+// Imágenes y videos del vault de Obsidian (ORQ-299): se suben a S3 como adjuntos de la
+// entrada de conocimiento (`entityType: 'knowledge'`, /v1/attachments/upload-url +
+// POST /v1/knowledge/{id}/attachments) y se bajan de vuelta al vault en otra máquina.
+//
+// El texto de la nota NO se reescribe: `![[foto.png]]` / `![](img/foto.png)` quedan tal cual,
+// porque el adjunto guarda como `fileName` la ruta del archivo relativa al vault. Así un
+// `vault sync` en otra Mac vuelve a poner cada archivo donde Obsidian lo espera.
+//
+// Reglas (iguales a las del adjunto normal, `add_attachment`): png/jpg/jpeg/gif/webp hasta
+// 15 MB y mp4/mov/webm hasta 500 MB. Cualquier otro tipo (pdf, audio, zip...) se reporta y no
+// se sincroniza. Nunca se borra un archivo del vault; solo se reemplaza en S3 la versión
+// anterior de un archivo que cambió.
+import { createHash } from 'node:crypto'
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import { apiGet, apiPost, apiDelete, putToPresignedUrl } from './api.mjs'
+
+export const IMAGE_MIME = { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp' }
+export const VIDEO_MIME = { mp4: 'video/mp4', mov: 'video/quicktime', webm: 'video/webm' }
+export const MAX_IMAGE_BYTES = 15 * 1024 * 1024
+export const MAX_VIDEO_BYTES = 500 * 1024 * 1024
+
+const toPosix = p => p.split(path.sep).join('/')
+const extOf = p => path.extname(p).slice(1).toLowerCase()
+
+// ── Referencias (puro) ──────────────────────────────────────────────────────
+
+/** Referencias a archivos incrustados en el texto de una nota: `![[x|alias]]` y `![](ruta)` (no URLs). */
+export function embedRefs(body) {
+  const refs = []
+  for (const m of (body || '').matchAll(/!\[\[([^\]]+)\]\]|!\[[^\]]*\]\((?!https?:|data:)([^)]+)\)/g)) {
+    let ref = m[1]
+    if (ref !== undefined) {
+      ref = ref.split('|')[0].split('#')[0].trim()
+    } else {
+      ref = m[2].trim().replace(/^<|>$/g, '').replace(/\s+"[^"]*"$/, '')
+      try { ref = decodeURIComponent(ref) } catch { /* se queda como venía */ }
+      ref = ref.split('#')[0]
+    }
+    if (ref) refs.push(ref)
+  }
+  return [...new Set(refs)]
+}
+
+/** Índice de archivos del vault para resolver referencias: { all: Set<rel>, byBase: Map<lowerBasename, rel[]> }. */
+export function buildFileIndex(relPaths) {
+  const all = new Set(relPaths)
+  const byBase = new Map()
+  for (const rel of relPaths) {
+    const key = path.posix.basename(rel).toLowerCase()
+    byBase.set(key, [...(byBase.get(key) || []), rel].sort())
+  }
+  return { all, byBase }
+}
+
+/**
+ * Ruta (relativa al vault) del archivo al que apunta `ref`, o null si no existe.
+ * Mismo orden que Obsidian: ruta desde la raíz del vault, ruta relativa a la nota y, por último,
+ * solo el nombre (el más cercano a la nota si hay varios con el mismo nombre).
+ */
+export function resolveRef(ref, noteFile, index) {
+  const clean = ref.replace(/\\/g, '/').replace(/^\/+/, '')
+  if (index.all.has(clean)) return clean
+  const near = path.posix.normalize(path.posix.join(path.posix.dirname(toPosix(noteFile)), clean))
+  if (!near.startsWith('..') && index.all.has(near)) return near
+  const candidates = index.byBase.get(path.posix.basename(clean).toLowerCase())
+  if (!candidates?.length) return null
+  const dir = path.posix.dirname(toPosix(noteFile))
+  return candidates.find(c => path.posix.dirname(c) === dir) || candidates[0]
+}
+
+/** ¿Se sincroniza este archivo? → { ok, kind, mime } o { ok:false, reason: 'unsupported' | 'toolarge' }. */
+export function classifyFile(rel, size) {
+  const ext = extOf(rel)
+  const image = IMAGE_MIME[ext]
+  const video = VIDEO_MIME[ext]
+  if (!image && !video) return { ok: false, reason: 'unsupported' }
+  const max = image ? MAX_IMAGE_BYTES : MAX_VIDEO_BYTES
+  if (size > max) return { ok: false, reason: 'toolarge', maxMb: max / 1024 / 1024 }
+  return { ok: true, kind: image ? 'image' : 'video', mime: image || video }
+}
+
+/** Seguro para escribir dentro del vault: relativa, sin `..` ni rutas absolutas. */
+export function isSafeRelPath(rel) {
+  if (!rel || path.isAbsolute(rel) || /^[a-zA-Z]:/.test(rel)) return false
+  const norm = path.posix.normalize(String(rel).replace(/\\/g, '/'))
+  return !norm.startsWith('..') && !norm.startsWith('/') && !norm.split('/').includes('.git')
+}
+
+// ── Plan de subida (puro) ───────────────────────────────────────────────────
+
+/**
+ * notes: [{file, id|null, title, body}]
+ * files: Map<rel, {size, hash}>  (solo hace falta de los archivos referenciados; ver `fileInfoFor`)
+ * index: salida de buildFileIndex
+ * attState: { [entryId]: { [rel]: {attachmentId, hash} } }
+ * → [{ note, rel, status, ... }] con status:
+ *     upload (nuevo) | replace (cambió) | unchanged | missing | unsupported | toolarge
+ * Una misma imagen usada en dos notas se sube una vez por nota (cada entrada tiene sus adjuntos).
+ */
+export function planAttachmentUploads({ notes, files, index, attState = {} }) {
+  const out = []
+  for (const note of notes) {
+    for (const ref of embedRefs(note.body)) {
+      const ext = extOf(ref)
+      // `![[Otra nota]]` (transclusión) no tiene extensión de archivo: no es un adjunto.
+      if (!ext || ext === 'md') continue
+      const rel = resolveRef(ref, note.file, index)
+      if (!rel) { out.push({ note, ref, rel: null, status: 'missing' }); continue }
+      const info = files.get(rel)
+      const cls = classifyFile(rel, info?.size ?? 0)
+      if (!cls.ok) { out.push({ note, ref, rel, status: cls.reason, size: info?.size, maxMb: cls.maxMb }); continue }
+      const prev = note.id ? attState[note.id]?.[rel] : null
+      const status = !prev ? 'upload' : prev.hash === info.hash ? 'unchanged' : 'replace'
+      out.push({ note, ref, rel, status, size: info.size, hash: info.hash, kind: cls.kind, mime: cls.mime, prev })
+    }
+  }
+  return out
+}
+
+// ── Disco ────────────────────────────────────────────────────────────────────
+
+/** Todos los archivos NO .md del vault (rutas relativas, posix). Las carpetas/archivos que empiezan con "." se saltan (.obsidian). */
+export async function scanVaultFiles(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 scanVaultFiles(dir, relPath))
+    else if (!ent.name.endsWith('.md')) out.push(toPosix(relPath))
+  }
+  return out
+}
+
+/** Tamaño y hash de contenido de los archivos referenciados (solo los que existen). */
+export async function fileInfoFor(dir, rels) {
+  const info = new Map()
+  for (const rel of new Set(rels)) {
+    try {
+      const buf = await fs.readFile(path.join(dir, rel))
+      info.set(rel, { size: buf.length, hash: createHash('sha1').update(buf).digest('hex') })
+    } catch { /* desaparecido entre el escaneo y la lectura: queda como missing */ }
+  }
+  return info
+}
+
+// ── Red ──────────────────────────────────────────────────────────────────────
+
+/** Adjuntos de una entrada en Orquestra, uno por ruta (si hay repetidos gana el más reciente). */
+export async function listRemoteAttachments(config, projectId, entryId) {
+  const { items } = await apiGet(config, `/v1/knowledge/${entryId}/attachments`, { projectId })
+  const byPath = new Map()
+  for (const a of items || []) {
+    if ((a.kind !== 'image' && a.kind !== 'video') || !a.key || !a.fileName) continue
+    const prev = byPath.get(a.fileName)
+    if (!prev || (a.createdAt || 0) > (prev.createdAt || 0)) byPath.set(a.fileName, a)
+  }
+  return byPath
+}
+
+/** Sube un archivo del vault como adjunto de la entrada; si reemplaza uno anterior, borra la versión vieja. */
+export async function uploadAttachment(config, projectId, entryId, dir, item) {
+  const buffer = await fs.readFile(path.join(dir, item.rel))
+  const { uploadUrl, key } = await apiPost(config, '/v1/attachments/upload-url', {
+    projectId, entityType: 'knowledge', entityId: entryId,
+    fileName: item.rel, fileType: item.mime, fileSize: item.size,
+  })
+  await putToPresignedUrl(uploadUrl, buffer, item.mime)
+  const created = await apiPost(config, `/v1/knowledge/${entryId}/attachments`, {
+    projectId, kind: item.kind, key, fileName: item.rel, fileType: item.mime, fileSize: item.size,
+  })
+  if (item.prev?.attachmentId) {
+    // Es la versión anterior del MISMO archivo (el id sale de nuestro estado): la nueva ya quedó guardada.
+    await apiDelete(config, `/v1/knowledge/${entryId}/attachments`, { projectId, id: item.prev.attachmentId }).catch(() => {})
+  }
+  return { attachmentId: created.id, hash: item.hash, size: item.size }
+}
+
+/** Baja un adjunto al vault SIN pisar un archivo que ya exista. Devuelve true si lo escribió. */
+export async function downloadAttachment(config, projectId, dir, attachment) {
+  if (!isSafeRelPath(attachment.fileName)) throw new Error(`ruta no segura en Orquestra: ${attachment.fileName}`)
+  const target = path.join(dir, attachment.fileName)
+  if (await fs.access(target).then(() => true, () => false)) return false
+  const { url } = await apiGet(config, '/v1/attachments/view-url', { projectId, key: attachment.key })
+  const res = await fetch(url, { signal: AbortSignal.timeout(120_000) })
+  if (!res.ok) throw new Error(`HTTP ${res.status} al bajar ${attachment.fileName}`)
+  await fs.mkdir(path.dirname(target), { recursive: true })
+  await fs.writeFile(target, Buffer.from(await res.arrayBuffer()))
+  return true
+}

package/src/vaultSync.mjs

@@ -13,11 +13,16 @@
 // 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).
+// Imágenes y videos del vault (ORQ-299): se suben a S3 como adjuntos de la entrada y se bajan
+// de vuelta en otra máquina -- ver src/vaultAttachments.mjs. `--no-attachments` los salta.
 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'
+import {
+  buildFileIndex, planAttachmentUploads, scanVaultFiles, fileInfoFor, embedRefs, resolveRef,
+  listRemoteAttachments, uploadAttachment, downloadAttachment, isSafeRelPath,
+} from './vaultAttachments.mjs'
 
 export const STATE_FILE = '.orquestra-sync.json'
 const CONFLICT_SUFFIX = '.conflict.md'
@@ -142,7 +147,6 @@ async function scanVault(dir, rel = '') {
 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)])
@@ -152,9 +156,8 @@ async function readLocal(dir) {
     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 }
+  return { notes }
 }
 
 async function readState(dir) {
@@ -169,18 +172,154 @@ function uniqueFile(title, taken) {
   return name
 }
 
+
+// ── Reporte (puro) ───────────────────────────────────────────────────────────
+
+const LABEL = {
+  pull: '↓ Bajar de Orquestra al vault',
+  push: '↑ Subir del vault a Orquestra',
+  create: '↑ Crear en Orquestra (notas nuevas del vault)',
+  conflict: '⚠ Conflictos (cambiaron en los dos lados)',
+  orphan: '? Sin entrada en Orquestra',
+}
+const OP_ORDER = ['pull', 'push', 'create', 'conflict', 'orphan']
+const DONE_LABEL = { pull: '↓ bajada', push: '↑ subida', create: '↑ creada', conflict: '⚠ conflicto resuelto', orphan: '? sin entrada' }
+
+export function formatBytes(n) {
+  if (n >= 1024 * 1024) return `${(n / 1024 / 1024).toFixed(1)} MB`
+  if (n >= 1024) return `${Math.round(n / 1024)} KB`
+  return `${n} B`
+}
+
+export function ago(ms, now = Date.now()) {
+  const min = Math.floor((now - ms) / 60000)
+  if (min < 1) return 'hace un momento'
+  if (min < 60) return `hace ${min} min`
+  const h = Math.round(min / 60)
+  if (h < 24) return `hace ${h} h`
+  return `hace ${Math.round(h / 24)} d`
+}
+
+const itemName = p => p.local?.file || p.remote?.title
+
+/**
+ * Texto del reporte antes de aplicar (o la vista previa). Todo lo que decide el usuario está aquí:
+ * qué pasa con cada nota y cada archivo, por qué, y el siguiente paso.
+ * att: { enabled, uploads:[{rel,title,size,status}], downloads:[{rel,title,size?}], unchanged:n,
+ *        missing:[{rel,title}], unsupported:[{rel,title}], toolarge:[{rel,title,size,maxMb}] }
+ */
+export function renderReport({ dir, dirArg, apply, firstRun, lastSyncAt, remoteCount, localCount, plan, att, verbose = false, now = Date.now() }) {
+  const out = []
+  out.push(`Vault: ${dir}`)
+  out.push(`Orquestra: ${remoteCount} entradas · Vault: ${localCount} notas · ${firstRun ? 'Primera sincronización' : `Última sincronización ${ago(lastSyncAt, now)}`}`)
+  out.push(apply ? 'Modo: APLICAR CAMBIOS' : 'Modo: VISTA PREVIA -- no se escribe nada todavía')
+  if (firstRun) {
+    out.push('', 'Cómo funciona:',
+      '  • Cada nota del vault es una entrada de la base de conocimiento de tu workspace (el nombre del archivo es el título).',
+      '  • Al sincronizar se añade un bloque de propiedades (frontmatter) con orquestraId; no toques esas líneas.',
+      '  • NUNCA se borra nada: una nota que borres del vault se vuelve a bajar, y si cambia en los dos lados se guarda una copia .conflict.md.')
+  }
+
+  out.push('', `NOTAS -- ${plan.length === 0 ? 'todo al día' : `${plan.length} cambio${plan.length === 1 ? '' : 's'}`}`)
+  for (const op of OP_ORDER) {
+    const items = plan.filter(p => p.op === op)
+    if (!items.length) continue
+    out.push(`  ${LABEL[op]} (${items.length})`)
+    for (const p of items) {
+      const why = op === 'conflict' ? `gana ${p.winner === 'local' ? 'la versión del vault' : 'la de Orquestra'}; la otra queda como .conflict.md` : p.reason
+      out.push(`      • ${itemName(p)}${why ? `  -- ${why}` : ''}`)
+    }
+    if (op === 'orphan') out.push('        (tiene orquestraId pero esa entrada ya no existe en Orquestra; no se toca. Para crearla de nuevo, borra la línea orquestraId del archivo.)')
+  }
+
+  if (att.enabled) {
+    const nothing = !att.uploads.length && !att.downloads.length && !att.missing.length && !att.unsupported.length && !att.toolarge.length
+    out.push('', `IMÁGENES Y VIDEOS -- ${nothing ? (att.unchanged ? `${att.unchanged} ya sincronizados` : 'ninguno referenciado en las notas') : 'cambios'}`)
+    if (att.uploads.length) {
+      const bytes = att.uploads.reduce((a, u) => a + (u.size || 0), 0)
+      out.push(`  ↑ Subir a Orquestra (${att.uploads.length}, ${formatBytes(bytes)})`)
+      for (const u of att.uploads) out.push(`      • ${u.rel}  (${formatBytes(u.size || 0)}, en "${u.title}"${u.status === 'replace' ? ', cambió: se reemplaza la versión anterior' : ''})`)
+    }
+    if (att.downloads.length) {
+      out.push(`  ↓ Bajar al vault (${att.downloads.length})`)
+      for (const d of att.downloads) out.push(`      • ${d.rel}  (en "${d.title}")`)
+    }
+    if (att.unchanged && !nothing) out.push(`  ✓ ${att.unchanged} ya sincronizados`)
+    if (att.missing.length) {
+      out.push(`  ✗ Referenciados pero no existen en el vault (${att.missing.length}) -- revisa el nombre o la ruta`)
+      for (const m of att.missing) out.push(`      • ${m.rel || m.ref}  (en "${m.title}")`)
+    }
+    if (att.unsupported.length) {
+      out.push(`  – No se sincronizan (${att.unsupported.length}): solo png/jpg/gif/webp y mp4/mov/webm`)
+      for (const m of att.unsupported) out.push(`      • ${m.rel}  (en "${m.title}")`)
+    }
+    if (att.toolarge.length) {
+      out.push(`  – Demasiado grandes (${att.toolarge.length})`)
+      for (const m of att.toolarge) out.push(`      • ${m.rel}  (${formatBytes(m.size || 0)}, máximo ${m.maxMb} MB)`)
+    }
+  } else {
+    out.push('', 'IMÁGENES Y VIDEOS -- omitidos (--no-attachments)')
+  }
+
+  const total = plan.length + (att.uploads?.length || 0) + (att.downloads?.length || 0)
+  out.push('')
+  if (!apply) {
+    if (total) out.push(`Siguiente paso: revisa la lista y aplica con\n  orquestra-mcp vault sync ${dirArg} --apply`)
+    else out.push('Nada que hacer: el vault y Orquestra están igual.')
+  }
+  return out
+}
+
+/** Resumen final de lo que SÍ se hizo. */
+export function renderSummary(c) {
+  const parts = []
+  const add = (n, singular, plural) => { if (n) parts.push(`${n} ${n === 1 ? singular : plural}`) }
+  add(c.pull, 'nota bajada', 'notas bajadas')
+  add(c.push, 'nota subida', 'notas subidas')
+  add(c.create, 'nota creada en Orquestra', 'notas creadas en Orquestra')
+  add(c.conflict, 'conflicto resuelto', 'conflictos resueltos')
+  add(c.up, 'archivo subido', 'archivos subidos')
+  add(c.down, 'archivo bajado', 'archivos bajados')
+  const lines = []
+  lines.push(c.failed ? `Listo con ${c.failed} error(es) -- vuelve a correr el comando para reintentar solo lo que falló.` : parts.length ? `✓ Listo: ${parts.join(', ')}.` : '✓ Listo: no había nada que cambiar.')
+  if (c.conflict) lines.push('  Revisa las copias *.conflict.md junto a cada nota en conflicto; cuando termines puedes borrarlas.')
+  lines.push('  El estado quedó en .orquestra-sync.json (no lo borres ni lo edites). La próxima vez solo se tocará lo que cambie.')
+  return lines
+}
+
 // ── Comando ──────────────────────────────────────────────────────────────────
 
-const LABEL = { pull: '↓ bajar', push: '↑ subir', create: '↑ crear', conflict: '⚠ conflicto', orphan: '? sin entrada en Orquestra' }
+const HELP = [
+  'Uso: orquestra-mcp vault sync <carpeta-del-vault> [opciones]',
+  '',
+  'Sincroniza la base de conocimiento de tu workspace con una carpeta de Obsidian, en los dos sentidos.',
+  'Córrelo desde la carpeta de un proyecto ya conectado con "orquestra-mcp setup" (de ahí salen la cuenta y el workspace).',
+  '',
+  'Opciones:',
+  '  --apply            escribe los cambios (la primera vez, sin esta opción solo se muestra el plan)',
+  '  --dry-run          solo muestra el plan, aunque ya hayas sincronizado antes',
+  '  --no-attachments   no sincroniza imágenes ni videos (solo el texto de las notas)',
+  '  --verbose          también lista lo que ya está al día',
+  '  --help             muestra esta ayuda',
+  '',
+  'Qué sincroniza: notas .md (el nombre del archivo es el título, el frontmatter guarda orquestraId y tags) y las',
+  'imágenes/videos (png, jpg, gif, webp, mp4, mov, webm) que las notas incrustan con ![[archivo]] o ![](ruta).',
+  'Nunca borra nada. Si una nota cambia en los dos lados, gana la más reciente y la otra queda como .conflict.md.',
+]
+
+/** Reparte `items` en `limit` tareas a la vez. */
+async function mapLimit(items, limit, fn) {
+  const out = new Array(items.length)
+  let next = 0
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, async () => {
+    while (next < items.length) { const i = next++; out[i] = await fn(items[i], i) }
+  }))
+  return out
+}
 
 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
-  }
+  if (!dirArg || argv.includes('--help')) { console.log(HELP.join('\n')); return }
   const dir = path.resolve(dirArg)
   await fs.mkdir(dir, { recursive: true })
   const config = loadConfig()
@@ -193,19 +332,82 @@ export async function runVaultSync(argv) {
   }
   // Primera vez: solo muestra el plan, salvo --apply explícito.
   const apply = argv.includes('--apply') || (!!state && !argv.includes('--dry-run'))
+  const withAtt = !argv.includes('--no-attachments')
+  const verbose = argv.includes('--verbose')
 
+  console.log('Leyendo Orquestra y el vault...')
   const { items: remote } = await apiGet(config, '/v1/knowledge', { projectId, full: 'true' })
-  const { notes: local, attachments } = await readLocal(dir)
+  const { notes: local } = await readLocal(dir)
   const plan = planSync({ remote, local, state })
+  const remoteIds = new Set(remote.map(r => r.id))
 
-  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
+  // ── Adjuntos: qué subir (según el vault) y qué bajar (según Orquestra) ──
+  const attState = structuredClone(state?.attachments || {})
+  const remoteCache = new Map()
+  const remoteFor = async id => {
+    if (!remoteCache.has(id)) remoteCache.set(id, await listRemoteAttachments(config, projectId, id).catch(() => new Map()))
+    return remoteCache.get(id)
+  }
+  const att = { enabled: withAtt, uploads: [], downloads: [], unchanged: 0, missing: [], unsupported: [], toolarge: [] }
+
+  async function planUploads(notes) {
+    // Las huérfanas (orquestraId que ya no existe) no se tocan; las nuevas (sin id) se suben al crearse.
+    const eligible = notes.filter(n => !n.id || remoteIds.has(n.id) || n.created)
+    const rels = new Set()
+    for (const n of eligible) for (const ref of embedRefs(n.body)) rels.add(ref)
+    const index = buildFileIndex(await scanVaultFiles(dir))
+    const referenced = []
+    for (const n of eligible) for (const ref of embedRefs(n.body)) { const rel = resolveRef(ref, n.file, index); if (rel) referenced.push(rel) }
+    const files = await fileInfoFor(dir, referenced)
+    const items = planAttachmentUploads({ notes: eligible, files, index, attState })
+    // Sin estado (se perdió el .orquestra-sync.json) pero ya subido: si Orquestra tiene el mismo archivo del mismo tamaño, se adopta en vez de duplicar.
+    await mapLimit(items.filter(i => i.status === 'upload' && i.note.id), 4, async it => {
+      const r = (await remoteFor(it.note.id)).get(it.rel)
+      if (r && r.fileSize === it.size) { it.status = 'adopt'; it.adoptId = r.id }
+    })
+    return items
+  }
+
+  const classify = items => {
+    att.uploads = []; att.unchanged = 0; att.missing = []; att.unsupported = []; att.toolarge = []
+    for (const it of items) {
+      const row = { rel: it.rel, ref: it.ref, title: it.note.title, size: it.size, status: it.status, maxMb: it.maxMb }
+      if (it.status === 'upload' || it.status === 'replace') att.uploads.push(row)
+      else if (it.status === 'unchanged' || it.status === 'adopt') att.unchanged++
+      else if (it.status === 'missing') att.missing.push(row)
+      else if (it.status === 'unsupported') att.unsupported.push(row)
+      else if (it.status === 'toolarge') att.toolarge.push(row)
+    }
+  }
+
+  async function planDownloads(entryIds, titleOf) {
+    const rows = []
+    await mapLimit(entryIds, 4, async id => {
+      for (const a of (await remoteFor(id)).values()) {
+        if (!isSafeRelPath(a.fileName)) continue
+        if (await fs.access(path.join(dir, a.fileName)).then(() => true, () => false)) continue
+        rows.push({ id, rel: a.fileName, title: titleOf(id), attachment: a })
+      }
+    })
+    return rows
+  }
+
+  let uploadItems = []
+  let pullIds = []
+  if (withAtt) {
+    uploadItems = await planUploads(local)
+    classify(uploadItems)
+    pullIds = [...new Set(plan.filter(p => p.op === 'pull' || (p.op === 'conflict' && p.winner === 'remote')).map(p => p.remote.id))]
+    const titles = new Map(remote.map(r => [r.id, r.title]))
+    att.downloads = (await planDownloads(pullIds, id => titles.get(id) || id)).map(({ rel, title }) => ({ rel, title }))
   }
 
+  for (const line of renderReport({ dir, dirArg, apply, firstRun: !state, lastSyncAt: state?.syncedAt, remoteCount: remote.length, localCount: local.length, plan, att, verbose })) console.log(line)
+  if (verbose && state) console.log(`\n(${local.length - plan.filter(p => p.local).length} notas sin cambios)`)
+  if (!apply) return
+
+  // ── Aplicar ─────────────────────────────────────────────────────────────
+  console.log('\nAplicando...')
   const entries = { ...(state?.entries || {}) }
   const taken = new Set(local.map(l => path.basename(l.file).toLowerCase()))
   const writeRemote = async (r, file, extra = []) => {
@@ -219,17 +421,22 @@ export async function runVaultSync(argv) {
     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)
+    return saved.id || id
   }
   const saveConflictCopy = async (file, text) => {
     await fs.writeFile(path.join(dir, file.replace(/\.md$/, CONFLICT_SUFFIX)), text)
   }
 
-  let failed = 0
+  const done = { pull: 0, push: 0, create: 0, conflict: 0, up: 0, down: 0, failed: 0 }
+  const createdIds = new Set()
+  let n = 0
   for (const p of plan) {
+    n++
+    if (p.op === 'orphan') continue
     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 === 'create') createdIds.add(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 || '' }))
@@ -239,11 +446,55 @@ export async function runVaultSync(argv) {
           await writeRemote(p.remote, p.local.file, p.local.extra)
         }
       }
+      done[p.op]++
+      console.log(`  [${n}/${plan.length}] ✓ ${DONE_LABEL[p.op]} -- ${itemName(p)}`)
     } catch (err) {
-      failed++
-      console.error(`  ✗ ${p.local?.file || p.remote?.title}: ${err.message}`)
+      done.failed++
+      console.error(`  [${n}/${plan.length}] ✗ ${itemName(p)}: ${err.message}`)
+    }
+  }
+
+  if (withAtt) {
+    // Con las notas ya escritas (ids nuevos, cuerpos de Orquestra) se recalcula qué subir.
+    const { notes: after } = await readLocal(dir)
+    const items = await planUploads(after.map(x => ({ ...x, created: createdIds.has(x.id) })))
+    const todo = items.filter(i => ['upload', 'replace', 'adopt'].includes(i.status) && i.note.id)
+    let k = 0
+    for (const it of todo) {
+      k++
+      try {
+        const bucket = (attState[it.note.id] ||= {})
+        if (it.status === 'adopt') {
+          bucket[it.rel] = { attachmentId: it.adoptId, hash: it.hash, size: it.size }
+          continue
+        }
+        bucket[it.rel] = await uploadAttachment(config, projectId, it.note.id, dir, it)
+        done.up++
+        console.log(`  [${k}/${todo.length}] ✓ ↑ ${it.rel}${it.status === 'replace' ? ' (reemplazó la versión anterior)' : ''}`)
+      } catch (err) {
+        done.failed++
+        console.error(`  [${k}/${todo.length}] ✗ ${it.rel}: ${err.message}`)
+      }
+    }
+    const idsToFetch = [...new Set([...pullIds, ...createdIds])]
+    const titles = new Map(after.map(x => [x.id, x.title]))
+    const downloads = await planDownloads(idsToFetch, id => titles.get(id) || id)
+    for (const d of downloads) {
+      try {
+        if (await downloadAttachment(config, projectId, dir, d.attachment)) {
+          done.down++
+          const info = (await fileInfoFor(dir, [d.rel])).get(d.rel)
+          if (info) (attState[d.id] ||= {})[d.rel] = { attachmentId: d.attachment.id, hash: info.hash, size: info.size }
+          console.log(`  ✓ ↓ ${d.rel}`)
+        }
+      } catch (err) {
+        done.failed++
+        console.error(`  ✗ ${d.rel}: ${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.')
+
+  await fs.writeFile(path.join(dir, STATE_FILE), JSON.stringify({ workspaceId: config.workspaceId, syncedAt: Date.now(), entries, attachments: attState }, null, 2))
+  console.log('')
+  for (const line of renderSummary(done)) console.log(line)
 }