nexusflex-mcp 3.0.0 → 3.6.0

package/device-auth.mjs

@@ -1,132 +1,132 @@
-// ============================================================================
-//  Device-flow del MCP (autorización web, estilo OAuth device code) + guardado
-//  local del token. El MCP NO pide email/contraseña: pide un código, el usuario
-//  lo autoriza desde el navegador (ya logueado en Nexus Flex) y el MCP recibe un
-//  token de vida larga, revocable y con el scope exacto del usuario.
-// ============================================================================
-import fs from "fs";
-import os from "os";
-import path from "path";
-import { spawn, execFileSync } from "child_process";
-
-/** Ruta del token guardado. Override con NEXUSFLEX_MCP_TOKEN_FILE. */
-export function tokenFilePath() {
-  if (process.env.NEXUSFLEX_MCP_TOKEN_FILE) return process.env.NEXUSFLEX_MCP_TOKEN_FILE;
-  return path.join(os.homedir(), ".nexusflex-mcp", "token.json");
-}
-
-/** Etiqueta legible para el token (aparece en "Conexiones" de la web). */
-export function defaultClientName() {
-  return process.env.NEXUSFLEX_MCP_CLIENT_NAME || `Claude MCP (${os.hostname?.() || "equipo"})`;
-}
-
-/** Restringe el archivo del token al usuario actual (privado). En POSIX: chmod 600.
- *  En Windows chmod es no-op → usamos icacls para dejar SOLO al usuario actual. */
-function restringirPermisos(file) {
-  if (process.platform === "win32") {
-    try {
-      const user = process.env.USERNAME || process.env.USER;
-      // Corta la herencia y elimina a todos, dejando control total solo al usuario.
-      execFileSync("icacls", [file, "/inheritance:r", "/grant:r", `${user}:F`], { stdio: "ignore" });
-    } catch {
-      console.error("[nexusflex-mcp] ADVERTENCIA: no se pudieron restringir los permisos del token en Windows. Usá una cuenta de un solo usuario.");
-    }
-    return;
-  }
-  try { fs.chmodSync(file, 0o600); } catch { /* best-effort */ }
-}
-
-/** Guarda el token junto con la API a la que pertenece (no reusar entre servidores). */
-export function saveToken(token, apiUrl) {
-  const file = tokenFilePath();
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, JSON.stringify({ token, apiUrl, savedAt: new Date().toISOString() }, null, 2), { mode: 0o600 });
-  restringirPermisos(file);
-  return file;
-}
-
-/** Lee el token guardado SI corresponde a esta misma API. */
-export function loadToken(apiUrl) {
-  try {
-    const file = tokenFilePath();
-    // Aviso si en POSIX el archivo quedó legible por grupo/otros (permisos flojos).
-    if (process.platform !== "win32") {
-      try {
-        const mode = fs.statSync(file).mode;
-        if ((mode & 0o077) !== 0) console.error("[nexusflex-mcp] ADVERTENCIA: el archivo de token tiene permisos demasiado abiertos.");
-      } catch { /* ignora */ }
-    }
-    const raw = JSON.parse(fs.readFileSync(file, "utf8"));
-    if (raw?.token && raw?.apiUrl === apiUrl) return raw.token;
-  } catch { /* no hay archivo o está corrupto */ }
-  return null;
-}
-
-/** Borra el token guardado (logout local). */
-export function clearToken() {
-  try { fs.rmSync(tokenFilePath()); return true; } catch { return false; }
-}
-
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-
-/** Intenta abrir el navegador en la URL (best-effort, no falla si no puede). */
-function abrirNavegador(url) {
-  try {
-    const cmd = process.platform === "win32" ? "cmd" : process.platform === "darwin" ? "open" : "xdg-open";
-    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
-    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
-    child.on("error", () => {});
-    child.unref?.();
-  } catch { /* sin navegador disponible */ }
-}
-
-/**
- * Corre el device-flow completo contra la API: pide el código, muestra la URL +
- * user_code por stderr (y abre el navegador si `open`), poll-ea hasta que el
- * usuario autoriza y devuelve el token. Lanza si el usuario rechaza o vence.
- */
-export async function runDeviceFlow(apiUrl, { open = true, log = (...a) => console.error(...a), timeoutMs } = {}) {
-  const clientName = defaultClientName();
-  const startRes = await fetch(`${apiUrl}/mcp/device/start`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ client_name: clientName }),
-  });
-  if (!startRes.ok) throw new Error(`No se pudo iniciar la autorización (${startRes.status}).`);
-  const s = await startRes.json();
-  const { device_code, user_code, verification_uri, verification_uri_complete } = s;
-  let interval = Math.max(2, Number(s.interval) || 5);
-  const deadline = Date.now() + (timeoutMs ?? (Number(s.expires_in) || 600) * 1000);
-
-  log("");
-  log("┌───────────────────────────────────────────────────────────┐");
-  log("│  🔌 Conectar Nexus Flex — autorizá el acceso del asistente  │");
-  log("└───────────────────────────────────────────────────────────┘");
-  log(`   1) Abrí:   ${verification_uri}`);
-  log(`   2) Código: ${user_code}`);
-  log(`   (o directo: ${verification_uri_complete})`);
-  log("");
-  log("   Esperando tu autorización en el navegador…");
-  if (open) abrirNavegador(verification_uri_complete);
-
-  while (Date.now() < deadline) {
-    await sleep(interval * 1000);
-    const r = await fetch(`${apiUrl}/mcp/device/token`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ device_code }),
-    });
-    const data = await r.json().catch(() => ({}));
-    if (r.ok && data.access_token) {
-      log("   ✅ ¡Autorizado! Conexión lista.");
-      return data.access_token;
-    }
-    if (data.error === "authorization_pending") continue;
-    if (data.error === "slow_down") { interval += 2; continue; }
-    if (data.error === "access_denied") throw new Error("Rechazaste el acceso desde el navegador.");
-    if (data.error === "expired_token") throw new Error("El código venció. Volvé a intentar.");
-    // invalid_grant u otro: cortamos
-    throw new Error(`No se pudo completar la autorización (${data.error || r.status}).`);
-  }
-  throw new Error("Se agotó el tiempo de espera de la autorización.");
-}
+// ============================================================================
+//  Device-flow del MCP (autorización web, estilo OAuth device code) + guardado
+//  local del token. El MCP NO pide email/contraseña: pide un código, el usuario
+//  lo autoriza desde el navegador (ya logueado en Nexus Flex) y el MCP recibe un
+//  token de vida larga, revocable y con el scope exacto del usuario.
+// ============================================================================
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { spawn, execFileSync } from "child_process";
+
+/** Ruta del token guardado. Override con NEXUSFLEX_MCP_TOKEN_FILE. */
+export function tokenFilePath() {
+  if (process.env.NEXUSFLEX_MCP_TOKEN_FILE) return process.env.NEXUSFLEX_MCP_TOKEN_FILE;
+  return path.join(os.homedir(), ".nexusflex-mcp", "token.json");
+}
+
+/** Etiqueta legible para el token (aparece en "Conexiones" de la web). */
+export function defaultClientName() {
+  return process.env.NEXUSFLEX_MCP_CLIENT_NAME || `Claude MCP (${os.hostname?.() || "equipo"})`;
+}
+
+/** Restringe el archivo del token al usuario actual (privado). En POSIX: chmod 600.
+ *  En Windows chmod es no-op → usamos icacls para dejar SOLO al usuario actual. */
+function restringirPermisos(file) {
+  if (process.platform === "win32") {
+    try {
+      const user = process.env.USERNAME || process.env.USER;
+      // Corta la herencia y elimina a todos, dejando control total solo al usuario.
+      execFileSync("icacls", [file, "/inheritance:r", "/grant:r", `${user}:F`], { stdio: "ignore" });
+    } catch {
+      console.error("[nexusflex-mcp] ADVERTENCIA: no se pudieron restringir los permisos del token en Windows. Usá una cuenta de un solo usuario.");
+    }
+    return;
+  }
+  try { fs.chmodSync(file, 0o600); } catch { /* best-effort */ }
+}
+
+/** Guarda el token junto con la API a la que pertenece (no reusar entre servidores). */
+export function saveToken(token, apiUrl) {
+  const file = tokenFilePath();
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify({ token, apiUrl, savedAt: new Date().toISOString() }, null, 2), { mode: 0o600 });
+  restringirPermisos(file);
+  return file;
+}
+
+/** Lee el token guardado SI corresponde a esta misma API. */
+export function loadToken(apiUrl) {
+  try {
+    const file = tokenFilePath();
+    // Aviso si en POSIX el archivo quedó legible por grupo/otros (permisos flojos).
+    if (process.platform !== "win32") {
+      try {
+        const mode = fs.statSync(file).mode;
+        if ((mode & 0o077) !== 0) console.error("[nexusflex-mcp] ADVERTENCIA: el archivo de token tiene permisos demasiado abiertos.");
+      } catch { /* ignora */ }
+    }
+    const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (raw?.token && raw?.apiUrl === apiUrl) return raw.token;
+  } catch { /* no hay archivo o está corrupto */ }
+  return null;
+}
+
+/** Borra el token guardado (logout local). */
+export function clearToken() {
+  try { fs.rmSync(tokenFilePath()); return true; } catch { return false; }
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** Intenta abrir el navegador en la URL (best-effort, no falla si no puede). */
+function abrirNavegador(url) {
+  try {
+    const cmd = process.platform === "win32" ? "cmd" : process.platform === "darwin" ? "open" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {});
+    child.unref?.();
+  } catch { /* sin navegador disponible */ }
+}
+
+/**
+ * Corre el device-flow completo contra la API: pide el código, muestra la URL +
+ * user_code por stderr (y abre el navegador si `open`), poll-ea hasta que el
+ * usuario autoriza y devuelve el token. Lanza si el usuario rechaza o vence.
+ */
+export async function runDeviceFlow(apiUrl, { open = true, log = (...a) => console.error(...a), timeoutMs } = {}) {
+  const clientName = defaultClientName();
+  const startRes = await fetch(`${apiUrl}/mcp/device/start`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ client_name: clientName }),
+  });
+  if (!startRes.ok) throw new Error(`No se pudo iniciar la autorización (${startRes.status}).`);
+  const s = await startRes.json();
+  const { device_code, user_code, verification_uri, verification_uri_complete } = s;
+  let interval = Math.max(2, Number(s.interval) || 5);
+  const deadline = Date.now() + (timeoutMs ?? (Number(s.expires_in) || 600) * 1000);
+
+  log("");
+  log("┌───────────────────────────────────────────────────────────┐");
+  log("│  🔌 Conectar Nexus Flex — autorizá el acceso del asistente  │");
+  log("└───────────────────────────────────────────────────────────┘");
+  log(`   1) Abrí:   ${verification_uri}`);
+  log(`   2) Código: ${user_code}`);
+  log(`   (o directo: ${verification_uri_complete})`);
+  log("");
+  log("   Esperando tu autorización en el navegador…");
+  if (open) abrirNavegador(verification_uri_complete);
+
+  while (Date.now() < deadline) {
+    await sleep(interval * 1000);
+    const r = await fetch(`${apiUrl}/mcp/device/token`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ device_code }),
+    });
+    const data = await r.json().catch(() => ({}));
+    if (r.ok && data.access_token) {
+      log("   ✅ ¡Autorizado! Conexión lista.");
+      return data.access_token;
+    }
+    if (data.error === "authorization_pending") continue;
+    if (data.error === "slow_down") { interval += 2; continue; }
+    if (data.error === "access_denied") throw new Error("Rechazaste el acceso desde el navegador.");
+    if (data.error === "expired_token") throw new Error("El código venció. Volvé a intentar.");
+    // invalid_grant u otro: cortamos
+    throw new Error(`No se pudo completar la autorización (${data.error || r.status}).`);
+  }
+  throw new Error("Se agotó el tiempo de espera de la autorización.");
+}

package/docs.mjs

@@ -0,0 +1,322 @@
+// ============================================================================
+//  Documentación integrada del MCP de Nexus Flex — fuente de verdad de la ayuda
+//  por herramienta (tool `ayuda`). Cada tool trae: qué hace, cómo usarlo (params),
+//  un ejemplo resuelto y qué NO hace (para no inferir comportamiento inexistente).
+//
+//  ⚠️ ESPEJO: este archivo está DUPLICADO en `backend/src/services/mcp-docs.ts`
+//  (el conector remoto se deploya sin la carpeta mcp/). Si editás uno, editá el
+//  otro — igual que MCP_VERSION/NOVEDADES. Mantené el contenido idéntico.
+// ============================================================================
+
+// Tópicos transversales (no son tools) — se consultan con `ayuda tema:<clave>`.
+export const TOPICS = {
+  facturacion_marketplace: [
+    "FACTURACIÓN DEL MARKETPLACE DE RUTAS PÚBLICAS",
+    "",
+    "Adjudicar una ruta (ruta_adjudicar) es OPERATIVO: cierra la subasta, marca el",
+    "nodo ganador (nodoToma) y deja registrada la OBLIGACIÓN al precio de la oferta",
+    "(precioAcordado). NO crea ningún asiento automático de facturación semanal, ni",
+    "en rendiciones, ni en comisiones de afiliado, ni en el clearing entre nodos.",
+    "El marketplace NO mueve dinero.",
+    "",
+    "Es decir: adjudicar ≠ colecta. Una colecta entre nodos sí genera un ítem de",
+    "clearing; una ruta adjudicada, NO. El pago entre el nodo que publica y el que",
+    "toma se acuerda y se salda MANUALMENTE (efectivo con el cadete, o descontándolo",
+    "de lo que un nodo ya le debe al otro por otros conceptos).",
+    "",
+    "Cómo verificarlo desde el MCP:",
+    "  • mis_rutas → estado 'adjudicada', nodoToma y precioAcordado de cada ruta tuya.",
+    "  • rendiciones / comisiones_afiliado_ver → NO listarán la ruta adjudicada.",
+    "",
+    "Qué falta (roadmap, todavía NO implementado): un settlement automático que,",
+    "al adjudicar, cargue el precioAcordado en la cuenta corriente entre los dos",
+    "nodos. Mientras no exista, tratá el pago como manual y avisáselo al usuario.",
+  ].join("\n"),
+
+  dinero: [
+    "DINERO — QUÉ NO HACE NUNCA EL MCP",
+    "",
+    "El MCP nunca mueve plata: no registra pagos de vendedores, no factura, no",
+    "concilia caja, no imputa cobros/haberes en cuentas corrientes. Hay una denylist",
+    "de dinero (mcpMoneyGuard) heredada del backend. Las únicas escrituras 'con",
+    "olor a plata' son configuraciones de TARIFA (colecta_configurar, precio_",
+    "actualizar, afiliacion_crear) o el REGISTRO de una obligación (comision_liquidar",
+    "marca comisiones ya devengadas como pagadas; ruta_adjudicar deja el precio",
+    "acordado). Ver tema facturacion_marketplace.",
+  ].join("\n"),
+
+  aislamiento: [
+    "AISLAMIENTO ENTRE NODOS",
+    "",
+    "Cada token de MCP pertenece a un usuario. Todos los tools llaman a la API REST",
+    "del backend con ese token, así que heredan el MISMO gateo que la web:",
+    "requireAuth + requirePermiso + scope por nodo/idCliente. Un vendedor solo ve",
+    "SUS envíos/stock; un operador solo su nodo; el admin global ve la red. Ningún",
+    "tool puede leer ni escribir datos de otro nodo (salvo lo que es público por",
+    "diseño, como el marketplace de rutas abiertas). Si un tool devuelve 403 es el",
+    "aislamiento del backend, no un bug.",
+  ].join("\n"),
+};
+
+// Guías de arranque por rol (onboarding). Se muestran al conectar (server
+// `instructions`) y con el tool `guia`. Metodología para empezar a usar el sistema
+// rápido y bien, con las herramientas concretas de cada paso.
+export const GUIAS = {
+  mensajero: [
+    "GUÍA DEL MENSAJERO — registrar lo que colectás, en el momento",
+    "",
+    "La idea: cuando pasás a colectar a un cliente, en vez de anotar a mano, me",
+    "mandás las FOTOS y yo cargo los envíos por vos. Paso a paso:",
+    "",
+    "1) Sacá una FOTO de cada paquete que agarrás: la etiqueta (Flex/Mercado Libre",
+    "   o la que sea) y, si tiene QR, que se vea. Si el paquete NO tiene etiqueta,",
+    "   sacá foto igual (datos del paquete: a quién va, dirección, teléfono).",
+    "2) Mandámelas todas juntas (un grupo de fotos). Yo leo cada una y registro el",
+    "   envío del cliente que estás colectando:",
+    "   • Con etiqueta ML / QR  → lo registro con `envio_desde_etiqueta_ml`",
+    "     (guardo el QR real, la etiqueta queda reimprimible).",
+    "   • Sin etiqueta, con datos → lo registro con `envio_cargar` como pedido",
+    "     manual y se le puede generar una etiqueta NUEVA para pegar.",
+    "3) IMPORTANTE (aislamiento): SOLO podés registrar envíos de clientes de TU",
+    "   nodo, o de un cliente que tengas COLECTADO (incluye colectas tomadas del",
+    "   marketplace de colectas). De otros clientes, no.",
+    "4) Cada envío queda 'A retirar', atribuido a vos, con un LINK de etiqueta",
+    "   imprimible. El vendedor lo ve al toque en su cuenta.",
+    "5) Al llegar al nodo, el centro procesa los envíos; a los que cargaste sin",
+    "   etiqueta se les pega una y salen normal. Después se escanean, aparecen en",
+    "   el mapa y se te suma la tarifa como cualquier reparto.",
+    "",
+    "Tips: si una etiqueta se rompió o no se lee, cargá el envío con `envio_cargar`",
+    "y generás una nueva. Consultá el estado de un envío con `envio_consultar`, tu",
+    "ruta con `mi_ruta` y tus colectas con `mis_colectas`.",
+    "(Próximamente: aviso en la app para imprimir de una todas las etiquetas que",
+    "cargaste por acá.)",
+  ].join("\n"),
+
+  cliente: [
+    "GUÍA DEL VENDEDOR — cargá tus ventas y seguí tu operación desde acá",
+    "",
+    "1) Cargar una venta/envío: `envio_cargar` con destinatario, teléfono,",
+    "   dirección y localidad (montoCobro si cobrás contra entrega). Te devuelvo",
+    "   el tracking + un link de etiqueta para imprimir + un link para subir una",
+    "   foto del paquete.",
+    "2) ¿Vendés por Mercado Libre? Mandame la foto de la etiqueta y la registro",
+    "   con `envio_desde_etiqueta_ml` (queda con el QR real).",
+    "3) Colecta (que te retiren): `mi_colecta` para ver cómo estás, `colecta_auto`",
+    "   para prender/apagar la automática, `colecta_solicitar` para una por única vez.",
+    "4) Tu negocio: `mi_stock` / `mi_disponible` (para no sobrevender), ",
+    "   `mi_rentabilidad`, `mis_top_productos`, `mis_kpis`. Sucursales de retiro con",
+    "   `mis_sucursales` / `sucursal_guardar`.",
+    "",
+    "Todo lo tuyo es solo tuyo (aislamiento). Nunca toco dinero por acá.",
+  ].join("\n"),
+
+  nodo: [
+    "GUÍA DEL NODO (operador/admin) — implementar y operar Nexus Flex rápido",
+    "",
+    "Puesta a punto:",
+    "  • Vendedores: `cliente_crear` / `cliente_editar` (asigná su lista de precio).",
+    "  • Choferes: `chofer_crear` (te devuelvo una clave temporal para pasarle).",
+    "  • Colecta: `colecta_configurar` (pago del nodo/mensajero, cobro por vendedor).",
+    "  • Zonas: `asignar_mensajero_zona` (mensajero↔metazona), `asignar_nodo_zona`",
+    "    (un nodo de tu grupo cubre una localidad).",
+    "",
+    "El día a día:",
+    "  • `colecta_pendientes` (hoy + mañana) y `colecta_asignar` (que Fulano levante",
+    "    a tal cliente).",
+    "  • Envíos: los cadetes pueden cargar lo que colectan por MCP (foto→envío); vos",
+    "    los ves 'A retirar'. Consultá con `envio_consultar`, corregí con",
+    "    `cobro_corregir` / `envio_reasignar_cliente`.",
+    "  • Rendiciones: `rendiciones` (qué falta recuperar/rendir).",
+    "",
+    "Clearing entre nodos (eficiente):",
+    "  • Metazonas + grupos logísticos rutean los envíos al nodo que cubre la zona.",
+    "    Recibís lo que te rutean con `envios_por_zona` → `procesar_zona` (aceptar) o",
+    "    `rechazar_zona`. El clearing sale de la config de tarifas por grupo.",
+    "  • Marketplace de rutas (`rutas_publicas`, `ruta_publicar`/`ofertar`/`adjudicar`):",
+    "    subasta abierta entre nodos. OJO: adjudicar NO factura automático — el pago",
+    "    entre nodos se salda a mano (ver `ayuda tema:facturacion_marketplace`).",
+    "  • Números: `kpi_nodo` (P&L, top clientes), `metricas_por_tipo`.",
+    "",
+    "Aislamiento: todo lo que ves/hacés es de TU nodo (o tu grupo cuando corresponde).",
+  ].join("\n"),
+};
+
+// Devuelve la guía de arranque para un rol (mensajero/cliente/operador/admin).
+export function guiaOnboarding(rol) {
+  if (rol === "mensajero") return GUIAS.mensajero;
+  if (rol === "cliente") return GUIAS.cliente;
+  if (rol === "operador" || rol === "admin") return GUIAS.nodo;
+  return [GUIAS.cliente, "", "— — —", "", GUIAS.nodo].join("\n");
+}
+
+// Orden y agrupación para el índice (solo se muestran los que el usuario tiene).
+export const GROUPS = [
+  { titulo: "General", tools: ["mis_datos", "guia", "ayuda", "mcp_version", "sugerencia_crear"] },
+  { titulo: "Vendedor — mi operación", tools: ["mis_envios", "envio_consultar", "mis_sucursales", "sucursal_guardar", "mi_colecta", "colecta_solicitar", "colecta_auto"] },
+  { titulo: "Vendedor — mi stock y números", tools: ["mi_stock", "mi_disponible", "mi_rentabilidad", "mis_productos", "mis_top_productos", "mis_kpis"] },
+  { titulo: "Mensajero", tools: ["mi_ruta", "mis_colectas"] },
+  { titulo: "Envíos (staff)", tools: ["envio_cargar", "envio_desde_etiqueta_ml", "envio_reasignar_cliente", "cobro_corregir"] },
+  { titulo: "Colecta y zonas (staff)", tools: ["colecta_ver", "colecta_pendientes", "colecta_configurar", "colecta_asignar", "colecta_desasignar", "zonas_reparto", "asignar_mensajero_zona", "asignar_nodo_zona", "envios_por_zona", "procesar_zona", "rechazar_zona"] },
+  { titulo: "Rendiciones y reclamos", tools: ["rendiciones", "rendicion_revertir", "reclamos_listar"] },
+  { titulo: "Marketplace de rutas", tools: ["rutas_publicas", "mis_rutas", "ruta_ofertas", "ruta_publicar", "ruta_ofertar", "ruta_adjudicar"] },
+  { titulo: "Afiliados", tools: ["afiliacion_listar", "comisiones_afiliado_ver", "afiliado_crear", "afiliacion_crear", "afiliacion_editar", "comision_liquidar"] },
+  { titulo: "Métricas / KPIs", tools: ["kpi_nodo", "kpi_red", "metricas_por_tipo", "top_productos"] },
+  { titulo: "WMS del nodo", tools: ["stock_nodo", "productos_nodo", "producto_crear"] },
+  { titulo: "Gestión del nodo", tools: ["clientes_del_nodo", "cliente_crear", "cliente_editar", "precios_ver", "precio_actualizar", "cuentas_vinculadas", "generar_enlace_vinculacion"] },
+  { titulo: "Usuarios / choferes", tools: ["chofer_listar", "chofer_crear", "chofer_editar", "usuario_habilitar_reparto"] },
+  { titulo: "Administración (red)", tools: ["nodos_listar", "nodo_crear", "sugerencias_listar"] },
+];
+
+// Doc por herramienta: que=qué hace, uso=cómo/params, ej=ejemplo resuelto, no=qué NO hace.
+export const TOOL_DOCS = {
+  ayuda: { que: "Devuelve esta documentación: índice de herramientas o la ficha completa de una (qué hace, params, ejemplo, qué NO hace) y tópicos transversales.", uso: "Sin argumentos = índice. `tool:<nombre>` = ficha de esa herramienta. `tema:<clave>` = tópico (facturacion_marketplace, dinero, aislamiento).", ej: "ayuda tool:ruta_adjudicar → te explica cómo adjudicar y aclara que no mueve dinero.", no: "No ejecuta nada ni consulta datos; es solo lectura de documentación estática." },
+  guia: { que: "Guía de ARRANQUE para tu rol: la metodología para empezar a usar Nexus Flex rápido, con las herramientas de cada paso (mensajero: foto→envío al colectar; vendedor: cargar ventas; nodo: implementar + operar + clearing).", uso: "Sin argumentos = tu guía según tu rol. `rol:<mensajero|cliente|nodo>` para ver otra.", ej: "Recién conectás como mensajero → guia → te explico cómo registrar lo que colectás sacando fotos.", no: "No ejecuta acciones; es la metodología. Para el detalle de una herramienta usá `ayuda tool:<x>`." },
+  mis_datos: { que: "Tu usuario, rol y nodo/cliente: define tu ALCANCE (qué podés ver/hacer).", uso: "Sin parámetros.", ej: "Antes de operar, mis_datos → confirmás que sos operador del nodo 6 y qué permisos tenés.", no: "No lista otros usuarios ni cambia nada." },
+  mcp_version: { que: "Versión del MCP corriendo, por qué vía (remoto/npx) y las novedades recientes.", uso: "Sin parámetros.", ej: "El usuario pregunta 'tengo lo último' → mcp_version.", no: "No actualiza el MCP." },
+  sugerencia_crear: { que: "Registra una sugerencia/mejora/bug del usuario (queda para el equipo).", uso: "mensaje (obligatorio); categoria opcional (funcionalidad|mejora|bug|otro). Se adjunta tu usuario/rol/nodo solo.", ej: "sugerencia_crear mensaje:'Sumar recordatorio de colecta' categoria:mejora.", no: "No abre tickets externos ni notifica por mail." },
+
+  mis_envios: { que: "Tus envíos/paquetes (solo los tuyos).", uso: "estado opcional (filtra por estado).", ej: "mis_envios estado:'En camino' → los que están en reparto.", no: "No muestra envíos de otros vendedores; no los edita." },
+  envio_consultar: { que: "Busca UN envío por tracking/código y devuelve estado, historial, destino y datos de cobro/cambio.", uso: "codigo (tracking o código). Vendedor: entre SUS envíos; staff: dentro de su nodo. Si hay varios matches, pasá el tracking completo.", ej: "El vendedor pregunta '¿dónde está 44000...?' → envio_consultar codigo:'44000123'.", no: "No cambia el estado del envío; no busca fuera de tu alcance." },
+  mis_sucursales: { que: "Tus sucursales / puntos de retiro (la principal = tu dirección de retiro), con horario de corte y ventanas.", uso: "Sin parámetros.", ej: "mis_sucursales → confirmás desde dónde te colectan.", no: "No las edita (para eso, sucursal_guardar)." },
+  sucursal_guardar: { que: "Crea o edita una sucursal tuya (punto de retiro). Geocodifica la dirección sola.", uso: "id vacío = nueva; nombre obligatorio; principal:true la vuelve tu dirección de retiro; horarioCorte HH:MM y ventanas opcionales.", ej: "Cambiar tu retiro: sucursal_guardar id:<principal> direccion:'Av. Rivadavia 5000, CABA' principal:true.", no: "No mueve dinero; el detalle de piso/depto/timbre va aparte, no al geocoder." },
+  mi_colecta: { que: "Estado de tu colecta (retiro): si la automática está prendida, si pediste una por única vez y el aviso de costo.", uso: "Sin parámetros.", ej: "mi_colecta → ver si mañana te pasan a buscar.", no: "No la prende/apaga (colecta_auto) ni la solicita (colecta_solicitar)." },
+  colecta_solicitar: { que: "Pedís que te retiren los envíos POR ÚNICA VEZ, aunque tengas la automática apagada.", uso: "Sin parámetros. Devuelve el aviso de costo si aplica.", ej: "colecta_solicitar → aparecés en el panel de colecta del nodo.", no: "No prende la colecta automática permanente; no mueve dinero." },
+  colecta_auto: { que: "Prende (true) o apaga (false) tu colecta AUTOMÁTICA.", uso: "activa (bool).", ej: "colecta_auto activa:false → dejás de que te retiren; llevás vos al depósito.", no: "No agenda una colecta puntual (para eso colecta_solicitar)." },
+
+  mi_stock: { que: "Tu stock físico (solo tus productos).", uso: "Sin parámetros.", ej: "mi_stock → ver unidades por SKU.", no: "No muestra disponible-para-vender (usá mi_disponible)." },
+  mi_disponible: { que: "Disponible por SKU = físico − comprometido; marca ⚠️ si está bajo el mínimo.", uso: "Sin parámetros.", ej: "mi_disponible → cuántas unidades podés seguir vendiendo sin sobrevender.", no: "No repone stock." },
+  mi_rentabilidad: { que: "Margen por SKU (precio − flete real − COGS).", uso: "desde/hasta YYYY-MM-DD (default: mes en curso).", ej: "mi_rentabilidad desde:2026-08-01 → margen del mes.", no: "No incluye gastos fijos del negocio; es por SKU." },
+  mis_productos: { que: "Tu catálogo de productos.", uso: "Sin parámetros.", ej: "mis_productos → ver SKUs cargados.", no: "No da de alta (producto_crear, si el nodo tiene WMS)." },
+  mis_top_productos: { que: "Ranking de tus productos más despachados.", uso: "desde/hasta YYYY-MM-DD (default: mes).", ej: "mis_top_productos → qué se vende más.", no: "No muestra rentabilidad (usá mi_rentabilidad)." },
+  mis_kpis: { que: "Tus métricas + benchmark anónimo de tu nodo.", uso: "desde/hasta opcionales.", ej: "mis_kpis → tu tasa de entrega vs. el promedio del nodo.", no: "No revela datos de otros vendedores (el benchmark es anónimo)." },
+
+  mi_ruta: { que: "Tus entregas asignadas: las paradas de tu ruta del día.", uso: "Sin parámetros.", ej: "mi_ruta → orden de reparto de hoy.", no: "No marca entregas (eso se hace escaneando en la app)." },
+  mis_colectas: { que: "Las colectas/retiros que tenés asignados.", uso: "Sin parámetros.", ej: "mis_colectas → a qué vendedores tenés que ir a buscar.", no: "No las completa/confirma desde acá." },
+
+  envio_cargar: { que: "Registra un envío nuevo (queda 'A retirar') y devuelve tracking + link de etiqueta + link para subir foto.", uso: "Obligatorios: destinatario, telefono, direccion, localidad. Staff pasa `cliente` (nombre del vendedor de su nodo); el vendedor no. montoCobro = cobro contra entrega (opcional).", ej: "Staff: envio_cargar cliente:'Distri Sur' destinatario:'Ana' telefono:'11...' direccion:'Belgrano 100' localidad:'Lanús' montoCobro:15000.", no: "No mueve dinero (montoCobro es el cobro a destino, no un asiento); no imprime, devuelve el link." },
+  envio_desde_etiqueta_ml: { que: "Registra un envío a partir de lo que VOS (Claude) leíste de la foto de una etiqueta de Mercado Libre.", uso: "Leé la etiqueta: mlShipmentId + (si podés) mlQr crudo, mlSenderId del vendedor y el destino. El vendedor se mapea por mlSenderId (cuenta vinculada) o `cliente` por nombre. Una llamada por etiqueta.", ej: "envio_desde_etiqueta_ml mlSenderId:'123456' mlShipmentId:'44000...' destinatario:'Juan' direccion:'...' localidad:'Avellaneda'.", no: "No mueve dinero; si no reconoce el vendedor por mlSenderId tenés que pasar `cliente`." },
+  envio_reasignar_cliente: { que: "Mueve UN envío (por tracking) a otro cliente/vendedor de tu nodo cuando se cargó mal.", uso: "tracking + cliente (nombre o id destino, de tu nodo). Queda en el historial.", ej: "envio_reasignar_cliente tracking:'44000...' cliente:'Comercial Norte'.", no: "No cruza nodos; no cambia el estado del envío." },
+  cobro_corregir: { que: "Ajusta el monto a cobrar contra entrega de un envío (se cobró de más/de menos), guardando el original en el historial.", uso: "envioId + monto nuevo; motivo opcional.", ej: "cobro_corregir envioId:987 monto:12000 motivo:'lista vieja'.", no: "No mueve dinero en cuentas: corrige el DATO del envío." },
+
+  colecta_ver: { que: "Resumen de valores de colecta del nodo: pago default, cobros por cliente y pagos pactados por cliente+mensajero.", uso: "Sin parámetros.", ej: "colecta_ver → cuánto se paga/cobra por colecta.", no: "No cambia tarifas (colecta_configurar)." },
+  colecta_pendientes: { que: "Panel de colectas del nodo: `items` = a retirar HOY (por cliente, con corte y mensajero asignado); `itemsManana` = clientes cuyos envíos entraron después del corte → van a mañana.", uso: "Sin parámetros. Trae el colectaId para desasignar.", ej: "'¿Quién levanta a Distri Sur?' → colecta_pendientes y mirás items.", no: "No asigna (colecta_asignar) ni configura tarifas." },
+  colecta_configurar: { que: "Setea un valor de colecta según alcance.", uso: "alcance: 'nodo' (pago default por colecta), 'mensajero' (default de ese cadete), 'cliente' (cuánto se le COBRA a ese vendedor; idCliente + valor, minEnvios opcional), 'par' (pago pactado a un mensajero por un cliente puntual; idCliente + mensajero + valor). Scopeado a tu nodo.", ej: "colecta_configurar alcance:cliente idCliente:'130' valor:2500 minEnvios:5 → gratis desde 5 envíos, sino $2500.", no: "No mueve dinero: es config de tarifa (el cobro se aplica al liquidar)." },
+  colecta_asignar: { que: "Asigna la colecta de un cliente a un mensajero (ambos por nombre de tu nodo) y avisa al cadete.", uso: "cliente + mensajero (nombres). Si el corte venció, la programa para el próximo día hábil.", ej: "colecta_asignar cliente:'Distri Sur' mensajero:'Maxi'.", no: "No mueve dinero; no cruza nodos." },
+  colecta_desasignar: { que: "Quita la asignación de una colecta (los envíos vuelven a 'sin colecta').", uso: "colectaId (lo devuelve colecta_pendientes).", ej: "colecta_desasignar colectaId:44.", no: "No borra los envíos; no mueve dinero." },
+  zonas_reparto: { que: "Zonas de reparto del nodo con sus metazonas y qué mensajeros tiene cada una.", uso: "Sin parámetros.", ej: "zonas_reparto → ver quién cubre Palermo.", no: "No asigna (asignar_mensajero_zona / asignar_nodo_zona)." },
+  asignar_mensajero_zona: { que: "Asigna un mensajero de tu nodo a una metazona; si la zona existe le suma el cadete, si no la crea.", uso: "mensajero + metazona; nombre opcional.", ej: "asignar_mensajero_zona mensajero:'Maxi' metazona:'Palermo'.", no: "No cruza nodos." },
+  asignar_nodo_zona: { que: "Asigna un NODO COMPLETO (de tu grupo logístico) a una metazona, cuando ese nodo cubre toda la localidad.", uso: "nodo (nombre, debe compartir grupo logístico) + metazona; nombre opcional.", ej: "asignar_nodo_zona nodo:'RL' metazona:'Portela'.", no: "No suma nodos fuera de tu grupo logístico." },
+  envios_por_zona: { que: "Envíos que OTROS nodos te rutearon por zona de reparto, agrupados por zona (para aceptar/rechazar).", uso: "Sin parámetros. Cada envío trae su id (para procesar_zona/rechazar_zona).", ej: "envios_por_zona → ver qué te mandaron por la zona Sur.", no: "No los acepta solo: usá procesar_zona o rechazar_zona." },
+  procesar_zona: { que: "ACEPTA (recibe en tu nodo) envíos ruteados por zona.", uso: "envioIds (de envios_por_zona); mensajeroId opcional para asignarlos.", ej: "procesar_zona envioIds:[101,102] mensajeroId:7.", no: "No mueve dinero (el clearing es config)." },
+  rechazar_zona: { que: "RECHAZA envíos ruteados por zona: dejan de aparecerte y quedan para origen u otros nodos de la zona.", uso: "envioIds (de envios_por_zona); motivo opcional.", ej: "rechazar_zona envioIds:[103] motivo:'fuera de mi cobertura'.", no: "No cambia el estado del envío." },
+
+  rendiciones: { que: "Estado de rendiciones: cobros/cambios/devoluciones a recuperar o rendir, con totales y quién tiene cada uno.", uso: "Sin parámetros. Scopeado a tu alcance (vendedor: lo tuyo; nodo: tu nodo; mensajero: lo suyo).", ej: "rendiciones → cuánto falta que rinda cada cadete.", no: "No confirma ni revierte (rendicion_revertir); NO incluye rutas de marketplace adjudicadas (ver ayuda tema:facturacion_marketplace)." },
+  rendicion_revertir: { que: "Revierte un cobro/cambio marcado como 'rendido' por error → vuelve a 'a rendir'.", uso: "envioId + tipo (cobro|cambio); motivo opcional. Deja registro.", ej: "rendicion_revertir envioId:987 tipo:cobro motivo:'se marcó sin recibir'.", no: "No mueve dinero en cuentas; corrige el estado de la rendición." },
+  reclamos_listar: { que: "Reclamos abiertos de clientes ligados a liquidaciones/rendiciones (tipo, estado, trackings en disputa).", uso: "estado opcional (abierto|resuelto). Vendedor: lo suyo; operador: su nodo.", ej: "reclamos_listar estado:abierto → qué cobros están en disputa.", no: "No resuelve reclamos desde acá." },
+
+  rutas_publicas: { que: "Publicaciones ABIERTAS de toda la red que tu nodo puede tomar (con cuántas ofertas tiene cada una). Marca las tuyas con esMia.", uso: "Sin parámetros.", ej: "rutas_publicas → ver qué rutas hay para ofertar.", no: "No oferta (ruta_ofertar)." },
+  mis_rutas: { que: "Tus publicaciones (con estado/adjudicación: nodoToma y precioAcordado) y las ofertas que hiciste a otros.", uso: "Sin parámetros.", ej: "mis_rutas → ver si tu ruta se adjudicó y a quién.", no: "El precioAcordado es la obligación registrada, NO un asiento de facturación (ver ayuda tema:facturacion_marketplace)." },
+  ruta_ofertas: { que: "Ofertas recibidas en una publicación TUYA, de la más barata a la más cara. Solo el que publicó.", uso: "publicacionId. Los ids de oferta sirven para adjudicar.", ej: "ruta_ofertas publicacionId:12 → elegís la mejor y su ofertaId.", no: "No adjudica (ruta_adjudicar)." },
+  ruta_publicar: { que: "Publicás una ruta/colecta/viaje para que cualquier nodo la tome (subasta abierta). VOS le pagás al que la toma.", uso: "titulo (obligatorio); tipo (ruta|colecta|viaje), descripcion, zona, precioMax (tope que ofrecés pagar) opcionales.", ej: "ruta_publicar titulo:'Reparto zona Oeste 40 paquetes' tipo:ruta precioMax:20000.", no: "No mueve dinero: la obligación recién se registra al adjudicar; el pago es manual." },
+  ruta_ofertar: { que: "Ofertás por una publicación de OTRO nodo. precio = lo que cobrás por hacerla (más barato = mejor para el que publica).", uso: "publicacionId + precio; nota opcional. Si ya ofertaste, la actualiza.", ej: "ruta_ofertar publicacionId:12 precio:18000 nota:'salgo 8am'.", no: "No podés ofertar en tu propia publicación." },
+  ruta_adjudicar: { que: "Elegís la oferta ganadora de una publicación TUYA y cerrás la subasta: el nodo ganador la toma a su precio y queda registrada la obligación.", uso: "publicacionId + ofertaId (de ruta_ofertas).", ej: "ruta_adjudicar publicacionId:12 ofertaId:34 → gana el nodo de esa oferta a $18000.", no: "NO crea asiento de facturación/rendición/comisión ni clearing automático: el pago entre nodos se salda MANUALMENTE (ver ayuda tema:facturacion_marketplace)." },
+
+  afiliacion_listar: { que: "Afiliaciones (afiliado↔entidad referida) con su comisión por envío, vigencia y estado.", uso: "afiliado y/o entidad opcionales para filtrar. Scopeado a tu nodo.", ej: "afiliacion_listar afiliado:'Nodo RL'.", no: "No muestra comisiones devengadas (comisiones_afiliado_ver)." },
+  comisiones_afiliado_ver: { que: "Comisiones devengadas por envío (pendiente/liquidada) con totales.", uso: "afiliado, desde, hasta (YYYY-MM-DD) opcionales. Scopeado a tu nodo.", ej: "comisiones_afiliado_ver afiliado:'Nodo RL' desde:2026-08-01.", no: "No las paga (comision_liquidar); NO incluye rutas de marketplace." },
+  afiliado_crear: { que: "Alta de un afiliado (quien trae volumen nuevo a la red).", uso: "nombre + tipo (nodo|mensajero|externo); refId = id del nodo/mensajero (null si externo).", ej: "afiliado_crear nombre:'Juan Ref' tipo:externo.", no: "No crea la afiliación/comisión (afiliacion_crear); no toca dinero." },
+  afiliacion_crear: { que: "Vincula un afiliado con una entidad referida (nodo o cliente) y su comisión RECURRENTE por envío.", uso: "afiliado + entidadTipo (nodo|cliente) + entidad + tipoComision (porcentaje|montoFijo) + valorComision; fechaExpiracion opcional. Una entidad = un afiliado activo.", ej: "afiliacion_crear afiliado:'Juan Ref' entidadTipo:cliente entidad:'Distri Sur' tipoComision:montoFijo valorComision:50.", no: "No paga (comision_liquidar); es config, no mueve dinero." },
+  afiliacion_editar: { que: "Edita una afiliación: valorComision, fechaExpiracion (renovar/extender) y/o activa.", uso: "id + los campos a cambiar.", ej: "afiliacion_editar id:5 activa:false → la das de baja.", no: "No toca dinero." },
+  comision_liquidar: { que: "Marca comisiones devengadas como LIQUIDADAS (registra el pago al afiliado).", uso: "ids = lista de comisiones (de comisiones_afiliado_ver). Requiere permiso de finanzas. Scopeado a tu nodo.", ej: "comision_liquidar ids:[10,11,12].", no: "No calcula comisiones (se devengan solas por envío); no factura." },
+
+  kpi_nodo: { que: "Tablero del nodo: P&L, top clientes, caídas.", uso: "desde/hasta opcionales; nodo solo para admin.", ej: "kpi_nodo desde:2026-08-01 → resultado del mes.", no: "No baja a un vendedor puntual; solo tu nodo (salvo admin)." },
+  kpi_red: { que: "KPIs globales de la red.", uso: "Sin parámetros. Solo admin global.", ej: "kpi_red → panorama SaaS de toda la red.", no: "No desglosa por nodo (usá kpi_nodo con nodo)." },
+  metricas_por_tipo: { que: "Métricas por TIPO de envío (flex/tienda/manual): total, entregados, tasa y % entregado antes de las 21hs. Para admin desglosa por logística.", uso: "desde/hasta YYYY-MM-DD (default 30 días); nodo solo admin.", ej: "metricas_por_tipo → ver si los Flex se entregan a tiempo.", no: "No es por cliente." },
+  top_productos: { que: "Ranking de productos más despachados del nodo (WMS).", uso: "desde/hasta y cliente opcionales.", ej: "top_productos cliente:'Distri Sur'.", no: "Requiere WMS activo en el nodo." },
+
+  stock_nodo: { que: "Stock del depósito del nodo (WMS).", uso: "cliente opcional para filtrar.", ej: "stock_nodo cliente:'Distri Sur'.", no: "Requiere WMS activo; no repone." },
+  productos_nodo: { que: "Catálogo del depósito del nodo (WMS).", uso: "cliente opcional.", ej: "productos_nodo.", no: "Requiere WMS activo." },
+  producto_crear: { que: "Alta de producto en el depósito (WMS).", uso: "nombre + sku/codigoBarra/peso/volumen opcionales; staff pasa idCliente dueño.", ej: "producto_crear nombre:'Remera M' sku:'REM-M' idCliente:'130'.", no: "No mueve dinero; requiere WMS activo." },
+
+  clientes_del_nodo: { que: "Clientes/vendedores del nodo con su lista de precio.", uso: "Sin parámetros. Scopeado a tu nodo.", ej: "clientes_del_nodo → ver a quién facturás y con qué lista.", no: "No los crea/edita (cliente_crear/editar)." },
+  cliente_crear: { que: "Alta de cliente/vendedor en tu nodo.", uso: "nombre obligatorio; telefono/dni/direccion/idLista opcionales.", ej: "cliente_crear nombre:'Nueva Distri' idLista:'ID12'.", no: "No toca dinero; no cruza nodos." },
+  cliente_editar: { que: "Edita un cliente de tu nodo (p. ej. cambiar su lista de precio).", uso: "id + nombre (obligatorio) + los campos a cambiar (idLista, etc.).", ej: "cliente_editar id:130 nombre:'Distri Sur' idLista:'ID12'.", no: "No toca dinero." },
+  precios_ver: { que: "Listas de precios por zona de tu nodo.", uso: "Sin parámetros. Requiere permiso 'precios'.", ej: "precios_ver → ver tarifas por zona.", no: "No las edita (precio_actualizar)." },
+  precio_actualizar: { que: "Cambia precios de una lista creando una VERSIÓN nueva (histórico intacto).", uso: "idLista + los tramos (cercana/media/lejana/muyLejana); referencia/vigenciaDesde opcionales. Requiere permiso 'precios' (y que el conector lo permita).", ej: "precio_actualizar idLista:'ID12' cercana:1500 media:2000 lejana:2800.", no: "No mueve dinero; puede estar deshabilitado por el conector (ALLOW_PRECIOS)." },
+  cuentas_vinculadas: { que: "Cuántas cuentas de tienda hay vinculadas, por proveedor (ML / TiendaNube / TiendaNegocio).", uso: "nodo opcional (solo admin, baja al desglose por cliente).", ej: "cuentas_vinculadas → cuántos vendedores tienen ML conectado.", no: "No vincula (generar_enlace_vinculacion)." },
+  generar_enlace_vinculacion: { que: "Genera el enlace para vincular una tienda; se lo mandás al cliente para que autorice.", uso: "proveedor (ml|tiendanube|tiendanegocio); staff pasa `cliente` (de su nodo).", ej: "generar_enlace_vinculacion proveedor:ml cliente:'Distri Sur'.", no: "No completa la vinculación (la autoriza el dueño de la tienda); no toca dinero." },
+
+  chofer_listar: { que: "Usuarios de tu nodo, incluidos los choferes (rol mensajero): id, nombre, teléfono, activo.", uso: "Sin parámetros. Requiere permiso 'usuarios'.", ej: "chofer_listar → ver tus cadetes.", no: "No crea/edita (chofer_crear/editar)." },
+  chofer_crear: { que: "Da de alta un chofer (mensajero) en tu nodo con una CLAVE TEMPORAL que devuelve el server.", uso: "nombre + telefono + email; mensajeroNombre opcional (macheo con su cta cte). Pasale la clave; la cambia al primer ingreso.", ej: "chofer_crear nombre:'Maxi' telefono:'11...' email:'maxi@...'.", no: "Claude nunca inventa la clave; el server la genera." },
+  chofer_editar: { que: "Edita un chofer de tu nodo: nombre, teléfono, mensajeroNombre y/o activo.", uso: "id + los campos a cambiar.", ej: "chofer_editar id:7 activo:false → lo desactivás.", no: "No toca credenciales/clave." },
+  usuario_habilitar_reparto: { que: "Marca a un operador/admin de tu nodo como TAMBIÉN mensajero (puede escanear, autoasignarse y entregar).", uso: "id + activo (default true).", ej: "usuario_habilitar_reparto id:4 → ese comisionista ya puede repartir.", no: "No toca credenciales." },
+
+  nodos_listar: { que: "Todas las logísticas (nodos) de la red.", uso: "Sin parámetros. Solo admin global.", ej: "nodos_listar → id/nombre de cada nodo.", no: "No los crea (nodo_crear)." },
+  nodo_crear: { que: "Alta de una logística/nodo.", uso: "nombre + telefono opcional. Solo admin global.", ej: "nodo_crear nombre:'Nodo Oeste' telefono:'11...'.", no: "No toca dinero." },
+  sugerencias_listar: { que: "Sugerencias entrantes de usuarios (funciones/mejoras/bugs) con usuario, rol, nodo, estado.", uso: "rol y/o estado opcionales. Operador: su nodo; admin: todas.", ej: "sugerencias_listar estado:nueva.", no: "No las implementa; es lectura." },
+};
+
+// Renderiza la ayuda. q = nombre de tool o clave de tema (opcional).
+// ctx = { version, disponibles: Set<string> } — disponibles filtra el índice a lo
+// que ese usuario realmente tiene (según su rol/permisos).
+export function renderAyuda(q, ctx = {}) {
+  const version = ctx.version ?? "";
+  const disponibles = ctx.disponibles instanceof Set ? ctx.disponibles : null;
+  const clave = String(q ?? "").trim().toLowerCase().replace(/[^a-z_]/g, "");
+
+  if (!clave) return indice(version, disponibles);
+
+  if (TOPICS[clave]) return TOPICS[clave] + `\n\n(Consultá una herramienta con: ayuda tool:<nombre>)`;
+
+  const d = TOOL_DOCS[clave];
+  if (d) {
+    const tiene = !disponibles || disponibles.has(clave);
+    const nota = tiene ? "" : "\n\n(⚠️ Con tu rol/permiso actual esta herramienta no está disponible.)";
+    return [
+      `🔧 ${clave}`,
+      "",
+      `Qué hace: ${d.que}`,
+      `Cómo usar: ${d.uso}`,
+      `Ejemplo: ${d.ej}`,
+      `Qué NO hace: ${d.no}`,
+    ].join("\n") + nota;
+  }
+
+  // No matcheó: sugerir por prefijo/substring.
+  const cerca = Object.keys(TOOL_DOCS).filter((n) => n.includes(clave)).slice(0, 8);
+  const temas = Object.keys(TOPICS);
+  return [
+    `No encontré una herramienta o tema llamado "${clave}".`,
+    cerca.length ? `¿Quisiste decir?: ${cerca.join(", ")}` : "",
+    `Temas disponibles: ${temas.join(", ")}`,
+    `Sin argumentos, ayuda te da el índice completo.`,
+  ].filter(Boolean).join("\n");
+}
+
+function indice(version, disponibles) {
+  const out = [
+    `AYUDA DEL MCP NEXUS FLEX${version ? ` (v${version})` : ""}`,
+    "",
+    "Pedí el detalle de una herramienta con:  ayuda tool:<nombre>",
+    "Pedí un tema transversal con:            ayuda tema:<clave>",
+    `Temas: ${Object.keys(TOPICS).join(", ")}`,
+    "",
+    "Herramientas" + (disponibles ? " disponibles para vos" : "") + ":",
+  ];
+  for (const g of GROUPS) {
+    const items = g.tools.filter((t) => TOOL_DOCS[t] && (!disponibles || disponibles.has(t)));
+    if (!items.length) continue;
+    out.push("", `▸ ${g.titulo}`);
+    for (const t of items) out.push(`  • ${t} — ${TOOL_DOCS[t].que}`);
+  }
+  // Tools registradas que no estén en ningún grupo (por si se agrega una y se olvida).
+  if (disponibles) {
+    const enGrupos = new Set(GROUPS.flatMap((g) => g.tools));
+    const sueltas = [...disponibles].filter((t) => TOOL_DOCS[t] && !enGrupos.has(t));
+    if (sueltas.length) {
+      out.push("", "▸ Otras");
+      for (const t of sueltas) out.push(`  • ${t} — ${TOOL_DOCS[t].que}`);
+    }
+  }
+  return out.join("\n");
+}