@fullqueso/mcp-bc-gastos 1.28.0 → 1.31.0

package/.env.example

@@ -17,3 +17,10 @@ BC_COMPANY_FQFR=guid-for-franquicias
 
 # Optional
 LOG_LEVEL=info
+
+# Per-request BC fetch timeout (ms). A hung request is aborted + retried instead
+# of blocking the MCP forever (BUG #1 fix). Default 90000. Raise for heavy reports.
+BC_FETCH_TIMEOUT_MS=90000
+
+# CRM rate endpoint (get_crm_rate) — opcional, default abajo
+CRM_RATE_BASE=https://crm-rate.fullqueso.com/api/v1

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # CHANGELOG
 
+## [1.31.0] — 2026-07-01
+
+### Added — KPIs de nómina operativa: tienda vs eventos, activos vs pagados
+Contratos existentes intactos (solo se agregan campos). Todo USD. Verificado contra BC real (mayo 2026, FQ01/FQ28/FQ88/FQFR).
+
+- **`paid_employees` en `get_payroll_documents` (con `include_employee_count=true`).** Además de `summary.unique_employees`, ahora `summary.paid_employees`: lista agregada por empleado en el período con `{ employee_code, employee_name, cedula, cost_usd, lines, payroll_types:[...], classification }`. Permite cruzar activos vs pagados sin leer las líneas doc por doc.
+- **Deduplicación por cédula.** `unique_employees` y `paid_employees` deduplican por `cedula` cuando existe (una persona puede tener un código SEMANAL y otro EVENTO → se consolidan costo y líneas en un registro). `summary.duplicate_codes: [{ cedula, codes:[...] }]` expone los casos multi-código para limpieza en BC. Si `cedula` es null se trata el código como persona única (no se fusiona por nombre). El consolidado (`store="all"`) re-deduplica también entre tiendas (misma cédula en dos tiendas = una persona).
+  - Resolución de cédula en 2 pasos: si un código tiene cédula en alguna línea, las líneas con cédula en blanco de ese código heredan la cédula (evita partir un código en dos personas). Verificado mayo 2026: 0 splits, 0 merges; 82 personas = 58 con cédula (1:1) + 24 códigos sin cédula en BC (data-quality, tratados como únicos).
+- **Clasificación evento/operativo por empleado** (relevante FQ01): `classification` = `"evento"` (todos sus pagos EVENTO), `"operativo"` (ningún EVENTO — SEMANAL/VACACIONES/LIQUIDACION), `"mixto"` (tiene EVENTO y no-EVENTO). Evita marcar como "inactivo no declarado" a quien solo trabaja eventos.
+- **Buckets de nómina tienda vs eventos** en `summary` (per-store y consolidado): `store_payroll` = Σ `cost_usd` de docs SEMANAL + VACACIONES + LIQUIDACION; `event_payroll` = Σ EVENTO. `total_cost_usd` se mantiene igual (gerencia queda solo ahí). Constantes `STORE_PAYROLL_TYPES`/`EVENT_PAYROLL_TYPES` en `tools/payroll/cost-model.js`.
+
+### Added — Denominador de ventas correcto para el KPI (get_sales_analysis / compare_sales_by_store)
+- **`revenue_store`, `revenue_events`, `revenue_intercompany`, `revenue_non_sales` + `revenue_total`** en `summary` (y por tienda en `compare_sales_by_store`), además del `total_revenue_usd` actual (sin cambios). Identidad: `revenue_total = revenue_store + revenue_intercompany + revenue_events + revenue_non_sales`.
+- **`revenue_store = revenue_total − intercompañía − eventos − no-venta`.** Se excluye del denominador de tienda la venta intercompañía, la venta de eventos y el ingreso **no-venta** (FX gains + rebajas de compra) — este último por recomendación aceptada por FP.
+- **Cuentas configurables (no inline), por tienda** en `config/income-accounts.js`, verificadas contra el CoA real:
+  - `INTERCOMPANY_REVENUE_ACCOUNTS = ['40310']` (tiendas operativas; FQ01/FQ88, FQ28=0).
+  - `EVENT_REVENUE_ACCOUNTS = ['40180','40700']` (solo FQ01 con movimiento).
+  - `NON_SALES_REVENUE_ACCOUNTS = ['40580','40540','40550']` (dif. cambiario + descuentos/rebajas de compra).
+  - **FQFR** usa `FQFR_INTERCOMPANY_REVENUE_ACCOUNTS = ['40420','40430','40660','40930']` (royalties/fees del master de franquicia, NO 40310) vía `getRevenueClassification(storeCode)` → sus buckets salen correctos aunque el KPI no aplique.
+  - Lógica en `splitRevenueBuckets(glRevenue, total, storeCode)` (`utils/sales-aggregation.js`); `calculateSummary` ahora recibe `storeCode` (los dos tools de ventas lo pasan por tienda).
+- **KPI** (lo calcula el consumidor cruzando ambos tools): `nomina_tienda_pct = store_payroll / revenue_store`; `nomina_eventos_pct = event_payroll / revenue_events` (**null si `revenue_events = 0`** → solo FQ01). **FQFR excluido por completo** del KPI (`KPI_PAYROLL_STORES = ['FQ01','FQ28','FQ88']`).
+  - Verificado mayo 2026 (2 fases, `tests/verify-payroll-sales-kpi.js`):
+    - **Estricto** (− interco − eventos), coincide con la validación de FP: FQ01 8.36% tienda / 31.02% eventos (rev_store 86,987.43); FQ28 10.22% (77,407.51); FQ88 8.75% (150,122.32).
+    - **Refinado** (además − no-venta): FQ01 8.36% (86,940.37); FQ28 10.25% (77,146.08); FQ88 8.80% (149,322.16).
+
+### Nota operativa
+- **Reiniciar Claude Desktop** tras el publish para que los tools recarguen (G-002).
+
+---
+
+## [1.30.0] — 2026-07-01
+
+### Fixed
+- **BUG #1 — `get_employees`/`get_payroll_documents` con `store="all"` podían colgar el MCP indefinidamente.** Causa raíz: `fetch()` no tenía timeout → una sola petición colgada nunca resolvía, y como el consolidado usaba `Promise.all`, una tienda colgada tumbaba todo el call (aparecía como "MCP no responde").
+  - **`lib/bc-client.js` — timeout por petición (AbortController).** Cada intento de `fetchWithRetry` aborta a los `BC_FETCH_TIMEOUT_MS` (default **90000**, env-tunable) y reintenta; al agotar reintentos lanza un error claro de timeout en vez de colgarse. Cubre token + todas las llamadas v2.0/OData/custom (afecta a las 54 tools; el default generoso no toca ninguna llamada legítima — todas las observadas <1s).
+  - **Consolidación multi-tienda resiliente.** `get_payroll_documents` y `get_employees` con `store="all"` ahora usan `Promise.allSettled`: una tienda que falle/timeoutee devuelve data parcial + un array `errors[]` por tienda, nunca cuelga ni bota el consolidado.
+  - Verificado: per-store discovery <500ms; el timeout aborta+reintenta (3x) y lanza error en ~6s con `BC_FETCH_TIMEOUT_MS=1`.
+
+### Changed / Added — KPIs de nómina operativa
+- **#2/#3 — Costo total en USD por documento (`total_cost_usd`) robusto a drafts sin distribuir.** Nuevo módulo `tools/payroll/cost-model.js` como **fuente única de verdad del costo**. Regla (verificada contra 448 docs reales): `total_cost_usd = totalGrossUSD (>0) → si no, bonos-equivalente USD → si no, neto (MAX, no suma)`. El campo `cost_basis` (`gross`|`bonuses`|`net`) hace auditable de dónde salió el número, y `net_distributed:false` marca los drafts cuyo neto aún no se reparte por método de pago (elimina el parche `max(neto,bonos)`).
+  - **Por qué la suma `net_usd + net_ves/tasa` estaba mal:** VACACIONES/LIQUIDACION contabilizan el MISMO monto en `totalNetUSD` **y** `totalNetVES` → esa suma **duplica** el costo. `totalGrossUSD` es el costo real y ya está en el header (antes no se seleccionaba).
+  - Expuestos en cada documento: `total_cost_usd`, `cost_basis`, `net_distributed`, `total_gross_usd`, `total_deductions_usd`. Agregado `total_cost_usd` a `summary` y `consolidated`.
+- **#4 — Enums de `payroll_type` corregidos a los valores reales de BC + `exclude_managerial`.** El enum viejo `[SEMANAL|QUINCENAL|MENSUAL]` estaba mal (QUINCENAL/MENSUAL no existen).
+  - `get_payroll_documents`: `SEMANAL, GERENCIAL, GERENCIAL_CIERRE, EVENTO, VACACIONES, LIQUIDACION`. Nuevo flag `exclude_managerial` → excluye GERENCIAL + GERENCIAL_CIERRE server-side (nómina operativa en un solo call).
+  - `get_employees`: `SEMANAL, GERENCIAL, EVENTO`. Nuevo flag `exclude_managerial` → excluye `payrollType GERENCIAL` + `employeeType Management`.
+- **#5 — `summary.by_type` ahora trae costo, no solo conteo.** De `{ TIPO: n }` a `{ TIPO: { count, lines, cost_usd } }` (per-store y consolidado).
+- **#6 — Headcount único de empleados pagados en el periodo.** Nuevo flag `include_employee_count` en `get_payroll_documents` → `summary.unique_employees` (y `consolidated.unique_employees`). Lee las líneas de los docs filtrados en lotes de OR (no doc-por-doc). Distingue el headcount real de `total_employees_lines` (que duplica al mismo empleado por cada corrida semanal).
+- **#7 — Costo por empleado en USD en `get_payroll_lines`.** Expuesto `total_ves_equivalent` (campo de la API antes sin usar) y `cost_usd` por línea = `totalVESEquivalent / tasa` (la tasa se lee del header en 1 llamada extra). `summary` trae `total_cost_usd`, `total_ves_equivalent`, `payroll_type`, `status`, `exchange_rate`.
+  - **Nota (L-001):** la API `fqPayrollLines` **no** expone días/horas trabajados ni FTE por línea → no se pueden calcular KPIs de productividad laboral sin ampliar la extensión de BC. Documentado, no fabricado.
+
+### Nota operativa
+- **Reiniciar Claude Desktop** tras el publish para que los tools recarguen (G-002).
+
+---
+
+## [1.29.0] — 2026-06-21
+
+### Added
+- **`get_crm_rate` — tasa de cambio Bs/USD desde el CRM de Full Queso (tasa de referencia, hora Caracas).** Complementa a `get_exchange_rate` (que trae la tasa BCV contable vigente en BC): este tool consulta el endpoint del CRM `https://crm-rate.fullqueso.com` y expone tanto la tasa **USDT/Binance** (paralelo) como la **BCV** (oficial), histórica o del día.
+  - **Dos monedas con sinónimos:** `coin` acepta `USDT`/`BINANCE` (paralelo, mismo valor) y `VES`/`BCV` (oficial). La descripción dispara con "tasa USDT, tasa Binance, dólar Binance, tasa paralelo/paralela, tasa BCV, tasa oficial, tasa del día, tasa histórica".
+  - **Histórica vs del día automático:** con `date` (YYYY-MM-DD) → `GET /api/v1/history/price?coin={VES|USDT}&date=...`; sin `date` → `GET /api/v1/coin/{bcv|usdt}` (momento de la consulta).
+  - Maneja `400` (coin/date inválidos → error claro), `404` (sin registro → `price: null` + mensaje) y fallo de conexión. Precio redondeado a 2 decimales; respuesta incluye `queried_at_caracas` y `source`.
+  - Base URL configurable vía env **`CRM_RATE_BASE`** (default `https://crm-rate.fullqueso.com/api/v1`). El endpoint no requiere auth de BC → tool autónomo (ignora `bcClient`).
+  - Nuevo `tools/get-crm-rate.js`; registrado en `server.js` (import + lista de tools + switch).
+  - **Verificado contra el endpoint real (21-jun-2026):** USDT del día ≈798.35; BCV del día 612.43; histórica USDT 19-jun 805.40; histórica VES 19-jun **607.39** (coincide con el ejemplo del doc); 404 (1990) y coin inválido (DOGE) manejados. `node --check` OK.
+
+### Nota operativa
+- **Reiniciar Claude Desktop** tras el publish para que el tool recargue (G-002).
+
+---
+
 ## [1.28.0] — 2026-06-12
 
 ### Added

package/config/income-accounts.js

@@ -25,6 +25,35 @@ export const COGS_ACCOUNTS = {
   57020: { name: 'Costos Diversos', nameEn: 'Diverse Costs' },
 };
 
+// ── Revenue classification for the store-payroll KPI denominator ─────────────
+// Verified against the real CoA (tests/discover-revenue-accounts.js, May 2026):
+//   40310 "Ventas Materia Prima otras tiendas" = intercompany de tienda (FQ01/FQ88,
+//          FQ28=0); su costo par es 50110 (see LESSONS L-011).
+//   40180 "Ventas Eventos - NEN" + 40700 "Ventas Eventos" = event sales (solo FQ01).
+//   40580 "Ganancia por dif. cambiario" + 40540/40550 "Descuentos/Rebajas en Compras"
+//          = ingreso NO-venta → fuera del denominador de tienda (confirmado por FP).
+// revenue_store = revenue_total − intercompany − events − non_sales.
+export const INTERCOMPANY_REVENUE_ACCOUNTS = ['40310'];
+export const EVENT_REVENUE_ACCOUNTS = ['40180', '40700'];
+export const NON_SALES_REVENUE_ACCOUNTS = ['40580', '40540', '40550'];
+
+// FQFR (master de franquicia): su intercompañía usa cuentas propias (royalties/fees),
+// NO 40310, y no tiene ventas de evento de tienda. El KPI de nómina/ventas NO aplica a
+// FQFR (ver KPI_PAYROLL_STORES) — esta clasificación es solo para que sus buckets de
+// venta salgan correctos si alguien consulta ventas de FQFR.
+export const FQFR_INTERCOMPANY_REVENUE_ACCOUNTS = ['40420', '40430', '40660', '40930'];
+
+// Tiendas a las que aplica el KPI nómina/ventas (FQFR excluido por completo).
+export const KPI_PAYROLL_STORES = ['FQ01', 'FQ28', 'FQ88'];
+
+// Cuentas de clasificación de ingreso por tienda (interco/eventos/no-venta).
+export function getRevenueClassification(storeCode) {
+  if (storeCode === 'FQFR') {
+    return { intercompany: FQFR_INTERCOMPANY_REVENUE_ACCOUNTS, events: [], nonSales: NON_SALES_REVENUE_ACCOUNTS };
+  }
+  return { intercompany: INTERCOMPANY_REVENUE_ACCOUNTS, events: EVENT_REVENUE_ACCOUNTS, nonSales: NON_SALES_REVENUE_ACCOUNTS };
+}
+
 // Income group labels for breakdown (by 100-prefix: 40110 → 40100)
 export const INCOME_GROUP_LABELS = {
   40100: '40100_ingreso_ventas',

package/lib/bc-client.js

@@ -18,6 +18,12 @@ export class BCClient {
     this._inflightRequests = new Map();
     this.STORE_DATA_TTL = 5 * 60 * 1000;      // 5 minutes
     this.EXCHANGE_RATE_TTL = 15 * 60 * 1000;   // 15 minutes
+
+    // Per-request hard timeout (ms). Without this a single hung fetch() never
+    // rejects → the whole tool call (and, via Promise.all consolidations, the
+    // MCP process) hangs forever. Generous default (all observed BC calls are
+    // <1s); tunable via env for unusually heavy OData reports. See L-015.
+    this.FETCH_TIMEOUT_MS = Number(process.env.BC_FETCH_TIMEOUT_MS) || 90000;
   }
 
   /**
@@ -135,8 +141,12 @@ export class BCClient {
 
   async fetchWithRetry(url, options, retries = 3) {
     for (let attempt = 1; attempt <= retries; attempt++) {
+      // Abort a hung request so it fails fast (and retries) instead of blocking
+      // forever. Each attempt gets its own controller/timer. See L-015.
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.FETCH_TIMEOUT_MS);
       try {
-        const response = await fetch(url, options);
+        const response = await fetch(url, { ...options, signal: controller.signal });
         if (response.status === 429 && attempt < retries) {
           const retryAfter = response.headers.get('Retry-After');
           const delay = retryAfter ? parseInt(retryAfter) * 1000 : attempt * 3000;
@@ -146,10 +156,20 @@ export class BCClient {
         }
         return response;
       } catch (err) {
-        if (attempt === retries) throw err;
+        const timedOut = err.name === 'AbortError';
+        if (attempt === retries) {
+          throw timedOut
+            ? new Error(`BC request timed out after ${this.FETCH_TIMEOUT_MS}ms (${retries} attempts): ${url}`)
+            : err;
+        }
         const delay = attempt * 2000;
-        logger.warn(`Fetch failed (attempt ${attempt}/${retries}), retrying in ${delay}ms...`);
+        logger.warn(
+          `Fetch ${timedOut ? `timed out (>${this.FETCH_TIMEOUT_MS}ms)` : 'failed'} ` +
+          `(attempt ${attempt}/${retries}), retrying in ${delay}ms...`
+        );
         await new Promise((r) => setTimeout(r, delay));
+      } finally {
+        clearTimeout(timer);
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fullqueso/mcp-bc-gastos",
-  "version": "1.28.0",
+  "version": "1.31.0",
   "description": "MCP server for Business Central operational expense analysis, bank reconciliation, POS reconciliation, accounts receivable/payable, multi-payment draft visibility, payroll, inventory cost analysis, and manager reports - Full Queso franchise stores",
   "main": "server.js",
   "bin": {

package/server.js

@@ -33,6 +33,7 @@ import { accountTransactionsTool, handleAccountTransactions } from './tools/acco
 import { vendorTransactionsTool, handleVendorTransactions } from './tools/vendor-transactions.js';
 import { listVendorsTool, handleListVendors } from './tools/list-vendors.js';
 import { exchangeRateTool, handleGetExchangeRate } from './tools/get-exchange-rate.js';
+import { crmRateTool, handleGetCrmRate } from './tools/get-crm-rate.js';
 
 // Auditoria tools (bank reconciliation)
 import { listBankAccountsTool, handleListBankAccounts } from './tools/auditoria/list-bank-accounts.js';
@@ -138,6 +139,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       vendorTransactionsTool,
       listVendorsTool,
       exchangeRateTool,
+      crmRateTool,
       // Auditoria (bank reconciliation)
       listBankAccountsTool,
       reconciliationStatusTool,
@@ -234,6 +236,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case 'get_exchange_rate':
         result = await handleGetExchangeRate(bcClient, args);
         break;
+      case 'get_crm_rate':
+        result = await handleGetCrmRate(bcClient, args);
+        break;
       // Auditoria (bank reconciliation)
       case 'list_bank_accounts':
         result = await handleListBankAccounts(bcClient, args);

package/tools/get-crm-rate.js

@@ -0,0 +1,109 @@
+// tools/get-crm-rate.js
+// Tasa de cambio Bs/USD desde el CRM de Full Queso (hora Caracas).
+// Fuente: https://crm-rate.fullqueso.com
+//   - USDT == Binance == tasa paralelo
+//   - VES  == BCV     == tasa oficial
+// Histórica (con fecha) o del día (sin fecha).
+
+import { DateTime } from 'luxon';
+
+const CRM_RATE_BASE =
+  process.env.CRM_RATE_BASE || 'https://crm-rate.fullqueso.com/api/v1';
+
+// Normaliza el coin del usuario al símbolo del endpoint.
+function normalizeCoin(raw) {
+  const c = String(raw || '').trim().toUpperCase();
+  if (['USDT', 'BINANCE', 'PARALELO', 'PARALELA'].includes(c)) {
+    return { history: 'USDT', live: 'usdt', label: 'USDT/Binance' };
+  }
+  if (['VES', 'BCV', 'OFICIAL', 'BS'].includes(c)) {
+    return { history: 'VES', live: 'bcv', label: 'BCV (oficial)' };
+  }
+  return null;
+}
+
+export const crmRateTool = {
+  name: 'get_crm_rate',
+  description:
+    'Obtiene la tasa de cambio Bs/USD desde el CRM de Full Queso (hora Caracas). ' +
+    'Dos monedas: USDT (equivalente a la tasa Binance / paralelo) y VES (tasa BCV oficial). ' +
+    'Si se pasa una fecha (YYYY-MM-DD) retorna la tasa histórica guardada de ese día; ' +
+    'si se omite la fecha retorna la tasa del momento de la consulta. ' +
+    'Usar SIEMPRE que se pida: tasa USDT, tasa Binance, dólar Binance, tasa paralelo/paralela, ' +
+    'tasa BCV, tasa oficial, tasa del día o tasa histórica de una fecha. ' +
+    'Para tasa BCV vigente contable en Business Central usar get_exchange_rate; este tool es la tasa de referencia del CRM.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      coin: {
+        type: 'string',
+        enum: ['USDT', 'BINANCE', 'VES', 'BCV'],
+        description:
+          'Moneda/tasa. USDT y BINANCE son equivalentes (paralelo). VES y BCV son equivalentes (oficial BCV).',
+      },
+      date: {
+        type: 'string',
+        description:
+          'Fecha histórica (YYYY-MM-DD), hora Caracas. Si se omite, devuelve la tasa actual.',
+      },
+    },
+    required: ['coin'],
+  },
+};
+
+export async function handleGetCrmRate(_bcClient, args) {
+  const coin = normalizeCoin(args.coin);
+  if (!coin) {
+    throw new Error(
+      `coin inválido: "${args.coin}". Válidos: USDT/BINANCE (paralelo) o VES/BCV (oficial).`
+    );
+  }
+
+  const isHistorical = !!args.date;
+  let url;
+  if (isHistorical) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(args.date)) {
+      throw new Error(`date inválida: "${args.date}". Formato esperado YYYY-MM-DD.`);
+    }
+    url = `${CRM_RATE_BASE}/history/price?coin=${coin.history}&date=${args.date}`;
+  } else {
+    url = `${CRM_RATE_BASE}/coin/${coin.live}`;
+  }
+
+  let res;
+  try {
+    res = await fetch(url, { headers: { Accept: 'application/json' } });
+  } catch (e) {
+    throw new Error(`No se pudo conectar al CRM de tasas (${CRM_RATE_BASE}): ${e.message}`);
+  }
+
+  if (res.status === 400) {
+    throw new Error('CRM 400: coin o date inválidos.');
+  }
+  if (res.status === 404) {
+    return {
+      coin: coin.label,
+      date: args.date || null,
+      price: null,
+      message: `No hay registro de tasa ${coin.label} para ${args.date}.`,
+    };
+  }
+  if (!res.ok) {
+    throw new Error(`CRM respondió ${res.status} en ${url}`);
+  }
+
+  const data = await res.json();
+  const nowCcs = DateTime.now().setZone('America/Caracas');
+  const price =
+    typeof data.price === 'number' ? Math.round(data.price * 100) / 100 : data.price;
+
+  return {
+    coin: coin.label,
+    type: isHistorical ? 'historica' : 'del_dia',
+    date: isHistorical ? args.date : nowCcs.toISODate(),
+    queried_at_caracas: nowCcs.toFormat('yyyy-MM-dd HH:mm:ss'),
+    price,
+    label: `1 USD = ${price} Bs (${coin.label})`,
+    source: url,
+  };
+}

package/tools/payroll/cost-model.js

@@ -0,0 +1,51 @@
+// Single source of truth for "how much did this payroll document cost", in USD.
+//
+// Grounded in 448 real BC documents (tests/validate-payroll-cost-model.js):
+//   - Undistributed Drafts:    totalGrossUSD = 0, totalNet* = 0, only totalBonuses* carries value.
+//   - Posted / Accrued docs:   totalGrossUSD is populated and equals the real cost.
+//   - VACACIONES / LIQUIDACION: net is double-booked (the same amount lands in BOTH
+//                              totalNetUSD *and* totalNetVES) → `net_usd + net_ves/rate`
+//                              DOUBLE-COUNTS. Never use that sum as the cost.
+//
+// Rule (in order): cost = totalGrossUSD (>0)  →  else bonuses-equivalent  →  else net (MAX, not sum).
+// `cost_basis` records which branch was used so the number is auditable, and
+// `net_distributed` flags drafts whose net hasn't been split across payment methods yet.
+
+const EPS = 0.005;
+
+// Payroll-cost buckets for the store-vs-events KPI. Managerial (GERENCIAL /
+// GERENCIAL_CIERRE) is neither → stays only in total_cost_usd.
+export const STORE_PAYROLL_TYPES = ['SEMANAL', 'VACACIONES', 'LIQUIDACION'];
+export const EVENT_PAYROLL_TYPES = ['EVENTO'];
+
+export function round2(n) {
+  return Math.round(n * 100) / 100;
+}
+
+export function computeDocCost(doc) {
+  const rate = doc.exchangeRate || 0;
+  const grossUsd = doc.totalGrossUSD || 0;
+  const bonusUsdEq = (doc.totalBonusesUSD || 0) + (rate ? (doc.totalBonusesVES || 0) / rate : 0);
+  // max() (not sum) guards against net booked in both currencies (the double-count above).
+  const netUsdEq = Math.max(doc.totalNetUSD || 0, rate ? (doc.totalNetVES || 0) / rate : 0);
+
+  let cost, basis;
+  if (grossUsd > EPS) {
+    cost = grossUsd;
+    basis = 'gross';
+  } else if (bonusUsdEq > EPS) {
+    cost = bonusUsdEq;
+    basis = 'bonuses';
+  } else {
+    cost = netUsdEq;
+    basis = 'net';
+  }
+
+  const netDistributed = (doc.totalNetUSD || 0) !== 0 || (doc.totalNetVES || 0) !== 0;
+
+  return {
+    total_cost_usd: round2(cost),
+    cost_basis: basis,          // 'gross' | 'bonuses' | 'net' — which field the cost came from
+    net_distributed: netDistributed, // false = Draft not yet split across payment methods (#3)
+  };
+}

package/tools/payroll/employees.js

@@ -1,10 +1,14 @@
 import { resolveStores } from '../../config/company-config.js';
 import { logger } from '../../utils/logger.js';
 
+// Real employee payrollType values in BC (discovered, not assumed — see L-001):
+//   EVENTO, GERENCIAL, SEMANAL. (QUINCENAL/MENSUAL never existed.)
+const EMPLOYEE_PAYROLL_TYPES = ['SEMANAL', 'GERENCIAL', 'EVENTO'];
+
 export const employeesTool = {
   name: 'get_employees',
   description:
-    'Lista empleados de una tienda con datos de nomina: tipo, status, salarios base, bonos predeterminados, fechas. Filtros por status, tipo de nomina, busqueda por nombre.',
+    'Lista empleados de una tienda con datos de nomina: tipo, status, salarios base, bonos predeterminados, fechas. Filtros por status, tipo de nomina, y exclude_managerial para headcount operativo. Soporta multi-tienda (resiliente: una tienda que falle no tumba el consolidado).',
   inputSchema: {
     type: 'object',
     properties: {
@@ -20,8 +24,13 @@ export const employeesTool = {
       },
       payroll_type: {
         type: 'string',
-        enum: ['SEMANAL', 'QUINCENAL', 'MENSUAL'],
-        description: 'Filtrar por tipo de nomina.',
+        enum: EMPLOYEE_PAYROLL_TYPES,
+        description: 'Filtrar por tipo de nomina. Valores reales de empleado: SEMANAL, GERENCIAL, EVENTO.',
+      },
+      exclude_managerial: {
+        type: 'boolean',
+        description:
+          'Excluir empleados gerenciales (payrollType GERENCIAL / employeeType Management) → headcount operativo. Default: false.',
       },
       employee_search: {
         type: 'string',
@@ -46,10 +55,19 @@ export async function handleEmployees(bcClient, args) {
     return processStore(bcClient, stores[0], args);
   }
 
-  const results = await Promise.all(
+  // Resilient consolidation: a single store hanging/failing must not take down
+  // the whole "all" response (root cause behind BUG #1). See L-015 / L-016.
+  const settled = await Promise.allSettled(
     stores.map((s) => processStore(bcClient, s, args))
   );
 
+  const results = [];
+  const errors = [];
+  settled.forEach((r, i) => {
+    if (r.status === 'fulfilled') results.push(r.value);
+    else errors.push({ store: stores[i].code, error: String(r.reason?.message || r.reason) });
+  });
+
   const consolidated = {
     total_employees: 0,
     by_status: {},
@@ -70,7 +88,9 @@ export async function handleEmployees(bcClient, args) {
     }
   }
 
-  return { stores: results, consolidated };
+  const out = { stores: results, consolidated };
+  if (errors.length) out.errors = errors;
+  return out;
 }
 
 async function processStore(bcClient, storeInfo, args) {
@@ -79,6 +99,10 @@ async function processStore(bcClient, storeInfo, args) {
 
   const filters = [`companyCode eq '${storeInfo.code}'`, `status eq '${status}'`];
   if (args.payroll_type) filters.push(`payrollType eq '${args.payroll_type}'`);
+  if (args.exclude_managerial) {
+    filters.push(`payrollType ne 'GERENCIAL'`);
+    filters.push(`employeeType ne 'Management'`);
+  }
   if (args.employee_code) filters.push(`employeeCode eq '${args.employee_code}'`);
 
   const url = bcClient.buildPayrollApiUrl(companyId, 'fqEmployees', {

package/tools/payroll/payroll-documents.js

@@ -1,10 +1,17 @@
 import { resolveStores } from '../../config/company-config.js';
 import { logger } from '../../utils/logger.js';
+import { computeDocCost, round2, STORE_PAYROLL_TYPES, EVENT_PAYROLL_TYPES } from './cost-model.js';
+
+// Real document payrollType values in BC (discovered, not assumed — see LESSONS L-001):
+//   EVENTO, GERENCIAL, GERENCIAL_CIERRE, LIQUIDACION, SEMANAL, VACACIONES
+// The old enum [SEMANAL|QUINCENAL|MENSUAL] was wrong (QUINCENAL/MENSUAL don't exist).
+const DOC_PAYROLL_TYPES = ['SEMANAL', 'GERENCIAL', 'GERENCIAL_CIERRE', 'EVENTO', 'VACACIONES', 'LIQUIDACION'];
+const MANAGERIAL_TYPES = ['GERENCIAL', 'GERENCIAL_CIERRE'];
 
 export const payrollDocumentsTool = {
   name: 'get_payroll_documents',
   description:
-    'Lista documentos de nomina (headers) con filtros por periodo, tipo, status. Muestra totales por documento, cantidad de empleados, tasas de cambio. Soporta multi-tienda.',
+    'Lista documentos de nomina (headers) con filtros por periodo, tipo, status. Devuelve costo total en USD por documento (total_cost_usd, robusto a drafts sin distribuir), buckets store_payroll/event_payroll, tasas de cambio, y un summary con costo por tipo. Con include_employee_count agrega empleados unicos y pagados (dedup por cedula) para cruzar activos vs pagados. Soporta multi-tienda y excluir gerencia (exclude_managerial) para KPIs de nomina operativa.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -19,8 +26,14 @@ export const payrollDocumentsTool = {
       },
       payroll_type: {
         type: 'string',
-        enum: ['SEMANAL', 'QUINCENAL', 'MENSUAL'],
-        description: 'Filtrar por tipo de nomina.',
+        enum: DOC_PAYROLL_TYPES,
+        description:
+          'Filtrar por tipo de documento de nomina. Valores reales: SEMANAL, GERENCIAL, GERENCIAL_CIERRE, EVENTO, VACACIONES, LIQUIDACION.',
+      },
+      exclude_managerial: {
+        type: 'boolean',
+        description:
+          'Excluir nomina gerencial (GERENCIAL + GERENCIAL_CIERRE) en un solo call → deja la nomina operativa. Default: false.',
       },
       status: {
         type: 'string',
@@ -35,6 +48,11 @@ export const payrollDocumentsTool = {
         type: 'string',
         description: 'Fecha fin (YYYY-MM-DD) para filtrar por documentDate.',
       },
+      include_employee_count: {
+        type: 'boolean',
+        description:
+          'Calcular empleados unicos + lista paid_employees (dedup por cedula, con costo/lineas/tipos/clasificacion) y duplicate_codes. Requiere leer las lineas de los docs filtrados (consultas extra, en lotes). Default: false.',
+      },
       summary_only: {
         type: 'boolean',
         description: 'Solo resumen (sin lista de documentos). Default: false.',
@@ -52,38 +70,82 @@ export async function handlePayrollDocuments(bcClient, args) {
   const summaryOnly = args.summary_only || false;
 
   if (stores.length === 1) {
-    return processStore(bcClient, stores[0], args, summaryOnly);
+    const r = await processStore(bcClient, stores[0], args, summaryOnly);
+    delete r.summary._paid_contribs;
+    return r;
   }
 
-  const results = await Promise.all(
+  // Resilient consolidation: one store failing/timing out must NOT hang or nuke
+  // the whole "all" response (root cause behind BUG #1). See L-015 / L-016.
+  const settled = await Promise.allSettled(
     stores.map((s) => processStore(bcClient, s, args, summaryOnly))
   );
 
+  const results = [];
+  const errors = [];
+  settled.forEach((r, i) => {
+    if (r.status === 'fulfilled') results.push(r.value);
+    else errors.push({ store: stores[i].code, error: String(r.reason?.message || r.reason) });
+  });
+
   const consolidated = {
     total_documents: 0,
     total_employees_lines: 0,
+    total_cost_usd: 0,
+    store_payroll: 0,
+    event_payroll: 0,
     total_net_usd: 0,
     total_net_ves: 0,
     by_status: { Draft: 0, Posted: 0 },
     by_type: {},
   };
 
+  const allContribs = [];
+  let anyEmployeeCount = false;
+
   for (const r of results) {
     consolidated.total_documents += r.summary.total_documents;
     consolidated.total_employees_lines += r.summary.total_employees_lines;
+    consolidated.total_cost_usd += r.summary.total_cost_usd;
+    consolidated.store_payroll += r.summary.store_payroll;
+    consolidated.event_payroll += r.summary.event_payroll;
     consolidated.total_net_usd += r.summary.total_net_usd;
     consolidated.total_net_ves += r.summary.total_net_ves;
     consolidated.by_status.Draft += r.summary.by_status.Draft || 0;
     consolidated.by_status.Posted += r.summary.by_status.Posted || 0;
-    for (const [type, count] of Object.entries(r.summary.by_type)) {
-      consolidated.by_type[type] = (consolidated.by_type[type] || 0) + count;
+    for (const [type, agg] of Object.entries(r.summary.by_type)) {
+      const c = consolidated.by_type[type] || { count: 0, lines: 0, cost_usd: 0 };
+      c.count += agg.count;
+      c.lines += agg.lines;
+      c.cost_usd = round2(c.cost_usd + agg.cost_usd);
+      consolidated.by_type[type] = c;
+    }
+    if (r.summary._paid_contribs) {
+      anyEmployeeCount = true;
+      allContribs.push(...r.summary._paid_contribs);
     }
   }
 
+  consolidated.total_cost_usd = round2(consolidated.total_cost_usd);
+  consolidated.store_payroll = round2(consolidated.store_payroll);
+  consolidated.event_payroll = round2(consolidated.event_payroll);
   consolidated.total_net_usd = round2(consolidated.total_net_usd);
   consolidated.total_net_ves = round2(consolidated.total_net_ves);
 
-  return { stores: results, consolidated };
+  if (anyEmployeeCount) {
+    // Re-dedup across stores too (same cédula in two stores = one person).
+    const agg = aggregatePaidEmployees(allContribs);
+    consolidated.unique_employees = agg.unique_employees;
+    consolidated.paid_employees = agg.paid_employees;
+    consolidated.duplicate_codes = agg.duplicate_codes;
+  }
+
+  // Strip the internal contribution list from per-store summaries before returning.
+  for (const r of results) delete r.summary._paid_contribs;
+
+  const out = { stores: results, consolidated };
+  if (errors.length) out.errors = errors;
+  return out;
 }
 
 async function processStore(bcClient, storeInfo, args, summaryOnly) {
@@ -92,12 +154,16 @@ async function processStore(bcClient, storeInfo, args, summaryOnly) {
   const filters = [];
   if (args.period_code) filters.push(`periodCode eq '${args.period_code}'`);
   if (args.payroll_type) filters.push(`payrollType eq '${args.payroll_type}'`);
+  if (args.exclude_managerial) {
+    for (const t of MANAGERIAL_TYPES) filters.push(`payrollType ne '${t}'`);
+  }
   if (args.status) filters.push(`status eq '${args.status}'`);
   if (args.start_date) filters.push(`documentDate ge ${args.start_date}`);
   if (args.end_date) filters.push(`documentDate le ${args.end_date}`);
 
   const params = {
-    $select: 'documentNo,periodCode,payrollType,companyCode,documentDate,postingDate,paymentDate,status,lineCount,totalBonusesVES,totalBonusesUSD,totalNetUSD,totalNetVES,exchangeRate,createdBy,postedBy,createdDateTime,postedDateTime',
+    $select:
+      'documentNo,periodCode,payrollType,companyCode,documentDate,postingDate,paymentDate,status,lineCount,totalGrossUSD,totalDeductionsUSD,totalBonusesVES,totalBonusesUSD,totalNetUSD,totalNetVES,exchangeRate,createdBy,postedBy,createdDateTime,postedDateTime',
     $orderby: 'documentDate desc',
   };
   if (filters.length > 0) params.$filter = filters.join(' and ');
@@ -110,6 +176,9 @@ async function processStore(bcClient, storeInfo, args, summaryOnly) {
   const summary = {
     total_documents: data.length,
     total_employees_lines: 0,
+    total_cost_usd: 0,
+    store_payroll: 0,
+    event_payroll: 0,
     total_net_usd: 0,
     total_net_ves: 0,
     by_status: { Draft: 0, Posted: 0 },
@@ -122,12 +191,19 @@ async function processStore(bcClient, storeInfo, args, summaryOnly) {
     const lineCount = doc.lineCount || 0;
     const netUsd = doc.totalNetUSD || 0;
     const netVes = doc.totalNetVES || 0;
+    const cost = computeDocCost(doc);
 
     summary.total_employees_lines += lineCount;
+    summary.total_cost_usd += cost.total_cost_usd;
     summary.total_net_usd += netUsd;
     summary.total_net_ves += netVes;
     summary.by_status[doc.status] = (summary.by_status[doc.status] || 0) + 1;
-    summary.by_type[doc.payrollType] = (summary.by_type[doc.payrollType] || 0) + 1;
+
+    const typeAgg = summary.by_type[doc.payrollType] || { count: 0, lines: 0, cost_usd: 0 };
+    typeAgg.count += 1;
+    typeAgg.lines += lineCount;
+    typeAgg.cost_usd = round2(typeAgg.cost_usd + cost.total_cost_usd);
+    summary.by_type[doc.payrollType] = typeAgg;
 
     if (!summaryOnly) {
       documents.push({
@@ -140,6 +216,11 @@ async function processStore(bcClient, storeInfo, args, summaryOnly) {
         payment_date: doc.paymentDate,
         status: doc.status,
         line_count: lineCount,
+        total_cost_usd: cost.total_cost_usd,
+        cost_basis: cost.cost_basis,
+        net_distributed: cost.net_distributed,
+        total_gross_usd: round2(doc.totalGrossUSD || 0),
+        total_deductions_usd: round2(doc.totalDeductionsUSD || 0),
         total_bonuses_ves: round2(doc.totalBonusesVES || 0),
         total_bonuses_usd: round2(doc.totalBonusesUSD || 0),
         total_net_usd: round2(netUsd),
@@ -153,9 +234,28 @@ async function processStore(bcClient, storeInfo, args, summaryOnly) {
     }
   }
 
+  summary.total_cost_usd = round2(summary.total_cost_usd);
   summary.total_net_usd = round2(summary.total_net_usd);
   summary.total_net_ves = round2(summary.total_net_ves);
 
+  // #4 (buckets) — tienda vs eventos (gerencia queda solo en total_cost_usd).
+  summary.store_payroll = round2(
+    STORE_PAYROLL_TYPES.reduce((s, t) => s + (summary.by_type[t]?.cost_usd || 0), 0)
+  );
+  summary.event_payroll = round2(
+    EVENT_PAYROLL_TYPES.reduce((s, t) => s + (summary.by_type[t]?.cost_usd || 0), 0)
+  );
+
+  // #6/#1/#2/#3 — empleados pagados (dedup por cedula) en el periodo (opt-in).
+  if (args.include_employee_count) {
+    const contribs = await fetchPaidContribs(bcClient, companyId, data);
+    const agg = aggregatePaidEmployees(contribs);
+    summary.unique_employees = agg.unique_employees;
+    summary.paid_employees = agg.paid_employees;
+    summary.duplicate_codes = agg.duplicate_codes;
+    summary._paid_contribs = contribs; // internal, stripped before return
+  }
+
   const result = {
     store: storeInfo.code,
     store_name: storeInfo.name,
@@ -167,6 +267,90 @@ async function processStore(bcClient, storeInfo, args, summaryOnly) {
   return result;
 }
 
-function round2(n) {
-  return Math.round(n * 100) / 100;
+// Per-line contributions (one per employee-line) with the document's payrollType
+// and exchangeRate, so cost_usd = totalVESEquivalent / rate. Lines only filter by
+// documentNo → batch in OR-chunks to avoid N calls.
+async function fetchPaidContribs(bcClient, companyId, docs, chunkSize = 15) {
+  const docMap = {};
+  for (const d of docs) docMap[d.documentNo] = { payrollType: d.payrollType, rate: d.exchangeRate || 0 };
+  const documentNos = docs.map((d) => d.documentNo);
+
+  const contribs = [];
+  for (let i = 0; i < documentNos.length; i += chunkSize) {
+    const chunk = documentNos.slice(i, i + chunkSize);
+    const filter = chunk.map((no) => `documentNo eq '${no}'`).join(' or ');
+    const url = bcClient.buildPayrollApiUrl(companyId, 'fqPayrollLines', {
+      $filter: filter,
+      $select: 'documentNo,employeeCode,employeeName,cedulaDeIdentidad,totalVESEquivalent',
+    });
+    const lines = await bcClient.apiCallAllPages(url);
+    for (const l of lines) {
+      const dm = docMap[l.documentNo] || {};
+      const rate = dm.rate || 0;
+      contribs.push({
+        employee_code: l.employeeCode,
+        employee_name: l.employeeName,
+        cedula: l.cedulaDeIdentidad,
+        payroll_type: dm.payrollType,
+        cost_usd: rate ? (l.totalVESEquivalent || 0) / rate : 0,
+      });
+    }
+  }
+  return contribs;
+}
+
+// Aggregate line contributions into one record per PERSON, deduped by cédula.
+// A person with a SEMANAL code and an EVENTO code (same cédula) collapses into one
+// record; their codes are surfaced in duplicate_codes for BC cleanup. When cédula
+// is null/empty the code is treated as a unique person (never merge by name).
+export function aggregatePaidEmployees(contribs) {
+  // Pass 1: learn each code's cédula from ANY line that carries one, so a line
+  // with a blank cédula still collapses into that person (avoids splitting one
+  // code into two when the cédula is only populated on some weeks).
+  const codeToCedula = {};
+  for (const c of contribs) {
+    const ced = c.cedula != null && String(c.cedula).trim() ? String(c.cedula).trim() : null;
+    if (ced && c.employee_code && !codeToCedula[c.employee_code]) codeToCedula[c.employee_code] = ced;
+  }
+
+  const byPerson = new Map();
+  for (const c of contribs) {
+    const cedula =
+      (c.cedula != null && String(c.cedula).trim() ? String(c.cedula).trim() : null) ||
+      codeToCedula[c.employee_code] ||
+      null;
+    const key = cedula ? `ced:${cedula}` : `code:${c.employee_code}`;
+    let p = byPerson.get(key);
+    if (!p) {
+      p = { employee_code: c.employee_code, employee_name: c.employee_name || null, cedula, cost_usd: 0, lines: 0, types: new Set(), codes: new Set() };
+      byPerson.set(key, p);
+    }
+    p.cost_usd += c.cost_usd || 0;
+    p.lines += 1;
+    if (c.payroll_type) p.types.add(c.payroll_type);
+    if (c.employee_code) p.codes.add(c.employee_code);
+    if (!p.employee_name && c.employee_name) p.employee_name = c.employee_name;
+  }
+
+  const paid_employees = [];
+  const duplicate_codes = [];
+  for (const p of byPerson.values()) {
+    const codes = [...p.codes].sort();
+    const hasEvento = p.types.has('EVENTO');
+    const hasNonEvento = [...p.types].some((t) => t !== 'EVENTO');
+    const classification = hasEvento && hasNonEvento ? 'mixto' : hasEvento ? 'evento' : 'operativo';
+    paid_employees.push({
+      employee_code: p.employee_code,
+      employee_name: p.employee_name,
+      cedula: p.cedula,
+      cost_usd: round2(p.cost_usd),
+      lines: p.lines,
+      payroll_types: [...p.types].sort(),
+      classification,
+    });
+    if (p.cedula && codes.length > 1) duplicate_codes.push({ cedula: p.cedula, codes });
+  }
+
+  paid_employees.sort((a, b) => b.cost_usd - a.cost_usd);
+  return { unique_employees: byPerson.size, paid_employees, duplicate_codes };
 }

package/tools/payroll/payroll-lines.js

@@ -1,10 +1,11 @@
 import { resolveStores } from '../../config/company-config.js';
 import { logger } from '../../utils/logger.js';
+import { round2 } from './cost-model.js';
 
 export const payrollLinesTool = {
   name: 'get_payroll_lines',
   description:
-    'Detalle de nomina por empleado para un documento especifico. Muestra bonos, pagos por metodo (cash VES, banco VES, cash USD), totales, y balance. Requiere document_no.',
+    'Detalle de nomina por empleado para un documento. Muestra bonos, pagos por metodo (cash VES, banco VES, cash USD), y el costo por empleado en USD (cost_usd, derivado de totalVESEquivalent a la tasa del documento) → base para "costo por persona". Requiere document_no. Nota: la API de nomina NO expone dias/horas trabajados ni FTE por linea.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -42,39 +43,57 @@ export async function handlePayrollLines(bcClient, args) {
   const filters = [`documentNo eq '${document_no}'`];
   if (args.employee_code) filters.push(`employeeCode eq '${args.employee_code}'`);
 
-  const url = bcClient.buildPayrollApiUrl(companyId, 'fqPayrollLines', {
+  // Header holds the exchangeRate (lines don't) → needed for per-employee cost_usd.
+  const headerUrl = bcClient.buildPayrollApiUrl(companyId, 'fqPayrollDocuments', {
+    $filter: `documentNo eq '${document_no}'`,
+    $select: 'documentNo,payrollType,status,documentDate,exchangeRate',
+  });
+
+  const linesUrl = bcClient.buildPayrollApiUrl(companyId, 'fqPayrollLines', {
     $filter: filters.join(' and '),
-    $select: 'documentNo,lineNo,employeeCode,employeeName,cedulaDeIdentidad,transportBonusVES,productivityBonusUSD,extraRedobleUSD,specialDateBonusUSD,foodBonusUSD,payCashVES,payBankVES,payCashUSD,totalBonusesVES,totalBonusesUSD,totalPayVES,totalPayUSD,balanceDifference',
+    $select:
+      'documentNo,lineNo,employeeCode,employeeName,cedulaDeIdentidad,transportBonusVES,productivityBonusUSD,extraRedobleUSD,specialDateBonusUSD,foodBonusUSD,payCashVES,payBankVES,payCashUSD,totalBonusesVES,totalBonusesUSD,totalVESEquivalent,totalPayVES,totalPayUSD,balanceDifference',
     $orderby: 'lineNo',
   });
 
-  const data = await bcClient.apiCallAllPages(url);
-  logger.info(`${storeInfo.code}: ${data.length} payroll lines for ${document_no}`);
+  const [headerRows, data] = await Promise.all([
+    bcClient.apiCallAllPages(headerUrl),
+    bcClient.apiCallAllPages(linesUrl),
+  ]);
+  const header = headerRows[0] || null;
+  const rate = header?.exchangeRate || 0;
+  logger.info(`${storeInfo.code}: ${data.length} payroll lines for ${document_no} (rate=${rate || 'n/a'})`);
 
-  let lines = data.map((line) => ({
-    document_no: line.documentNo,
-    line_no: line.lineNo,
-    employee_code: line.employeeCode,
-    employee_name: line.employeeName,
-    cedula: line.cedulaDeIdentidad || null,
-    bonuses: {
-      transport_ves: round2(line.transportBonusVES || 0),
-      productivity_usd: round2(line.productivityBonusUSD || 0),
-      extra_redoble_usd: round2(line.extraRedobleUSD || 0),
-      special_date_usd: round2(line.specialDateBonusUSD || 0),
-      food_usd: round2(line.foodBonusUSD || 0),
-    },
-    payments: {
-      cash_ves: round2(line.payCashVES || 0),
-      bank_ves: round2(line.payBankVES || 0),
-      cash_usd: round2(line.payCashUSD || 0),
-    },
-    total_bonuses_ves: round2(line.totalBonusesVES || 0),
-    total_bonuses_usd: round2(line.totalBonusesUSD || 0),
-    total_pay_ves: round2(line.totalPayVES || 0),
-    total_pay_usd: round2(line.totalPayUSD || 0),
-    balance_difference: round2(line.balanceDifference || 0),
-  }));
+  let lines = data.map((line) => {
+    const vesEquivalent = round2(line.totalVESEquivalent || 0);
+    return {
+      document_no: line.documentNo,
+      line_no: line.lineNo,
+      employee_code: line.employeeCode,
+      employee_name: line.employeeName,
+      cedula: line.cedulaDeIdentidad || null,
+      bonuses: {
+        transport_ves: round2(line.transportBonusVES || 0),
+        productivity_usd: round2(line.productivityBonusUSD || 0),
+        extra_redoble_usd: round2(line.extraRedobleUSD || 0),
+        special_date_usd: round2(line.specialDateBonusUSD || 0),
+        food_usd: round2(line.foodBonusUSD || 0),
+      },
+      payments: {
+        cash_ves: round2(line.payCashVES || 0),
+        bank_ves: round2(line.payBankVES || 0),
+        cash_usd: round2(line.payCashUSD || 0),
+      },
+      total_bonuses_ves: round2(line.totalBonusesVES || 0),
+      total_bonuses_usd: round2(line.totalBonusesUSD || 0),
+      total_ves_equivalent: vesEquivalent,
+      // Per-employee cost in USD = full pay (VES-equivalent) at the document rate.
+      cost_usd: rate ? round2(vesEquivalent / rate) : null,
+      total_pay_ves: round2(line.totalPayVES || 0),
+      total_pay_usd: round2(line.totalPayUSD || 0),
+      balance_difference: round2(line.balanceDifference || 0),
+    };
+  });
 
   // Client-side name search
   if (args.employee_search) {
@@ -85,7 +104,12 @@ export async function handlePayrollLines(bcClient, args) {
   // Summary totals
   const summary = {
     document_no,
+    payroll_type: header?.payrollType || null,
+    status: header?.status || null,
+    exchange_rate: rate || null,
     total_employees: lines.length,
+    total_cost_usd: 0,
+    total_ves_equivalent: 0,
     total_bonuses_ves: 0,
     total_bonuses_usd: 0,
     total_pay_ves: 0,
@@ -97,6 +121,8 @@ export async function handlePayrollLines(bcClient, args) {
   };
 
   for (const line of lines) {
+    summary.total_ves_equivalent += line.total_ves_equivalent;
+    if (line.cost_usd != null) summary.total_cost_usd += line.cost_usd;
     summary.total_bonuses_ves += line.total_bonuses_ves;
     summary.total_bonuses_usd += line.total_bonuses_usd;
     summary.total_pay_ves += line.total_pay_ves;
@@ -107,6 +133,8 @@ export async function handlePayrollLines(bcClient, args) {
     if (Math.abs(line.balance_difference) > 0.01) summary.employees_with_balance_diff++;
   }
 
+  summary.total_cost_usd = rate ? round2(summary.total_cost_usd) : null;
+  summary.total_ves_equivalent = round2(summary.total_ves_equivalent);
   summary.total_bonuses_ves = round2(summary.total_bonuses_ves);
   summary.total_bonuses_usd = round2(summary.total_bonuses_usd);
   summary.total_pay_ves = round2(summary.total_pay_ves);
@@ -122,7 +150,3 @@ export async function handlePayrollLines(bcClient, args) {
     lines,
   };
 }
-
-function round2(n) {
-  return Math.round(n * 100) / 100;
-}

package/tools/ventas/sales-analysis.js

@@ -99,7 +99,7 @@ export async function handleSalesAnalysis(bcClient, args) {
       data.lines.map((l) => ({ ...l, storeCode: code, storeName: data.storeName }))
     );
 
-    const storeSummary = calculateSummary(data.invoices, data.lines, exchangeRate, data.glRevenue);
+    const storeSummary = calculateSummary(data.invoices, data.lines, exchangeRate, data.glRevenue, code);
     byStoreResults.push({
       store_code: code,
       store_name: data.storeName,

package/tools/ventas/sales-store-comparison.js

@@ -59,7 +59,7 @@ export async function handleSalesStoreComparison(bcClient, args) {
   const storesSummaries = {};
 
   for (const [code, data] of Object.entries(allStoresData)) {
-    const summary = calculateSummary(data.invoices, data.lines, exchangeRate, data.glRevenue);
+    const summary = calculateSummary(data.invoices, data.lines, exchangeRate, data.glRevenue, code);
     storesSummaries[data.storeName] = { summary };
 
     const storeResult = {
@@ -69,6 +69,10 @@ export async function handleSalesStoreComparison(bcClient, args) {
 
     if (showAll || requestedMetrics.includes('revenue')) {
       storeResult.revenue_usd = summary.total_revenue_usd;
+      storeResult.revenue_store = summary.revenue_store;               // neto de interco, eventos y no-venta
+      storeResult.revenue_events = summary.revenue_events;
+      storeResult.revenue_intercompany = summary.revenue_intercompany;
+      storeResult.revenue_non_sales = summary.revenue_non_sales;
       storeResult.revenue_breakdown = summary.revenue_breakdown;
       storeResult.margin_usd = summary.total_margin_usd;
       storeResult.margin_pct = summary.margin_pct;

package/utils/sales-aggregation.js

@@ -1,3 +1,5 @@
+import { getRevenueClassification } from '../config/income-accounts.js';
+
 export function aggregateByField(lines, field) {
   const map = {};
   for (const line of lines) {
@@ -43,7 +45,7 @@ export function aggregateByDate(lines) {
     .sort((a, b) => a.date.localeCompare(b.date));
 }
 
-export function calculateSummary(invoices, lines, exchangeRate = null, glRevenue = null) {
+export function calculateSummary(invoices, lines, exchangeRate = null, glRevenue = null, storeCode = null) {
   const totalTransactions = invoices.length;
   const totalQuantity = lines.reduce((sum, l) => sum + (l.quantity || 0), 0);
   const totalCostUSD = lines.reduce((sum, l) => sum + (l.unitCostUSD || 0) * (l.quantity || 0), 0);
@@ -55,8 +57,18 @@ export function calculateSummary(invoices, lines, exchangeRate = null, glRevenue
   const marginPct = totalRevenueUSD && totalRevenueUSD !== 0
     ? (totalMarginUSD / totalRevenueUSD) * 100 : 0;
 
+  // Split revenue into the buckets that matter for the store-payroll KPI: store
+  // (own operation, the denominator) vs events (own ratio) vs intercompany (not a
+  // store sale) vs non-sales income (FX gains, purchase rebates). Store-aware.
+  const buckets = splitRevenueBuckets(glRevenue, totalRevenueUSD, storeCode);
+
   return {
     total_revenue_usd: totalRevenueUSD !== null ? Math.round(totalRevenueUSD * 100) / 100 : null,
+    revenue_total: buckets.revenue_total,               // alias of total_revenue_usd (explicit)
+    revenue_store: buckets.revenue_store,               // total − intercompany − events − non_sales
+    revenue_events: buckets.revenue_events,
+    revenue_intercompany: buckets.revenue_intercompany,
+    revenue_non_sales: buckets.revenue_non_sales,        // FX gains + purchase rebates (excluded)
     total_transactions: totalTransactions,
     total_quantity: totalQuantity,
     avg_ticket_usd: avgTicketUSD !== null ? Math.round(avgTicketUSD * 100) / 100 : null,
@@ -68,6 +80,28 @@ export function calculateSummary(invoices, lines, exchangeRate = null, glRevenue
   };
 }
 
+// revenue_store = total − intercompany − events − non_sales. Accounts per store
+// from config (not inline). Identity: total = store + interco + events + non_sales.
+export function splitRevenueBuckets(glRevenue, totalRevenueUSD, storeCode = null) {
+  if (!glRevenue || !glRevenue.breakdown || totalRevenueUSD === null) {
+    return { revenue_total: totalRevenueUSD ?? null, revenue_store: null, revenue_events: null, revenue_intercompany: null, revenue_non_sales: null };
+  }
+  const b = glRevenue.breakdown;
+  const sumAccts = (accts) => accts.reduce((s, a) => s + (b[a] || 0), 0);
+  const r2 = (n) => Math.round(n * 100) / 100;
+  const { intercompany, events, nonSales } = getRevenueClassification(storeCode);
+  const ic = sumAccts(intercompany);
+  const ev = sumAccts(events);
+  const ns = sumAccts(nonSales);
+  return {
+    revenue_total: r2(totalRevenueUSD),
+    revenue_intercompany: r2(ic),
+    revenue_events: r2(ev),
+    revenue_non_sales: r2(ns),
+    revenue_store: r2(totalRevenueUSD - ic - ev - ns),
+  };
+}
+
 export function calculateGrowth(current, previous) {
   if (!previous || previous === 0) return null;
   return ((current - previous) / Math.abs(previous)) * 100;