orquestra-mcp 1.55.0 → 1.56.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.56.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/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)
 }