@thinkingai/ae-cli 6.1.18 → 6.1.20

package/dist/{data-integration-QEKDWQDY.js → data-integration-4NZ53OMT.js}

@@ -1,15 +1,20 @@
+import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
 import {
+  require_excel,
+  require_styles_xform,
+  require_worksheet_reader,
   validateAndFix,
   validateDraft
-} from "./chunk-RJDU7NYP.js";
+} from "./chunk-LNZBEQXW.js";
+import "./chunk-I4WQAEYB.js";
 import {
   getConfigDir
-} from "./chunk-3FY3RJ26.js";
+} from "./chunk-WZ6YVQSF.js";
 import {
   CliValidationError,
-  LocalDataUploadError
-} from "./chunk-UW5UN47B.js";
-import "./chunk-JHENBQ5B.js";
+  LocalDataUploadError,
+  __toESM
+} from "./chunk-4P355ZWB.js";
 
 // src/commands/data-integration/inspect.ts
 import { basename as basename3 } from "path";
@@ -103,11 +108,14 @@ function assessFileSize(fileName, format, sizeBytes, encoding) {
 }
 
 // src/commands/data-integration/input.ts
+var import_exceljs = __toESM(require_excel(), 1);
+var import_worksheet_reader = __toESM(require_worksheet_reader(), 1);
+var import_styles_xform = __toESM(require_styles_xform(), 1);
 import { createHash } from "crypto";
 import { createReadStream as createReadStream2, statSync } from "fs";
-import { createRequire as createRequire2 } from "module";
 import { extname, basename } from "path";
 import { createInterface } from "readline";
+import { StringDecoder } from "string_decoder";
 import { pipeline } from "stream/promises";
 import XLSXMod from "xlsx";
 import { parse as parseCsv } from "csv-parse";
@@ -626,8 +634,6 @@ function isStrongDateTime(value) {
 
 // src/commands/data-integration/input.ts
 var XLSX = XLSXMod.default ?? XLSXMod;
-var require3 = createRequire2(import.meta.url);
-var ExcelWorksheetReader = require3("exceljs/lib/stream/xlsx/worksheet-reader");
 function resolveLocalDataInputMeta(filePath) {
   let format = resolveFormat(filePath);
   let delimiter;
@@ -664,10 +670,12 @@ async function inspectLocalDataInput(filePath) {
   const meta = resolveLocalDataInputMeta(filePath);
   emitSizeWarning(meta.filePath, meta.format, meta.sizeBytes, meta.encoding);
   try {
+    const discovered = await discoverDataSets(filePath, meta.format);
     return {
       ...meta,
       sha256: await sha256File(filePath),
-      dataSets: await discoverDataSets(filePath, meta.format)
+      dataSets: discovered.visible,
+      ...discovered.hidden.length > 0 ? { excludedDataSets: discovered.hidden } : {}
     };
   } catch (error) {
     if (error instanceof CliValidationError) throw error;
@@ -690,15 +698,28 @@ function emitSizeWarning(filePath, format, sizeBytes, encoding) {
 }
 function selectDataSet(input, requested) {
   if (requested) {
-    const selected = input.dataSets.find((candidate) => candidate.id === requested || candidate.selector === requested || candidate.label === requested);
-    if (!selected) {
-      throw new CliValidationError("The requested Sheet or JSON Path was not found.", {
-        code: "LOCAL_DATA_SET_NOT_FOUND",
-        hint: `Choose one of: ${input.dataSets.map((item) => item.id).join(", ")}`,
-        location: { field: "data-set" }
-      });
+    const matches = (candidate) => candidate.id === requested || candidate.selector === requested || candidate.label === requested;
+    const selected = input.dataSets.find(matches);
+    if (selected) return selected;
+    const excluded = input.excludedDataSets?.find(matches);
+    if (excluded) {
+      process.stderr.write(`Warning: "${excluded.label}" is hidden in the source workbook and was selected explicitly.
+`);
+      return excluded;
     }
-    return selected;
+    throw new CliValidationError("The requested Sheet or JSON Path was not found.", {
+      code: "LOCAL_DATA_SET_NOT_FOUND",
+      hint: `Choose one of: ${input.dataSets.map((item) => item.id).join(", ")}`,
+      location: { field: "data-set" }
+    });
+  }
+  const hidden = input.excludedDataSets ?? [];
+  if (input.dataSets.length === 0 && hidden.length > 0) {
+    throw new CliValidationError("Every data set in this file is hidden in the source.", {
+      code: "LOCAL_DATA_ALL_DATA_SETS_HIDDEN",
+      hint: `Confirm with the user, then pass --data-set with one of: ${hidden.map((item) => item.id).join(", ")}`,
+      location: { field: "data-set" }
+    });
   }
   if (input.dataSets.length !== 1) {
     throw new CliValidationError("This file contains multiple data sets.", {
@@ -736,7 +757,13 @@ async function streamLocalDataRows(input, dataSet, onRow, options = {}) {
     flattenRules: options.flattenRules,
     flattenMisses: options.flattenMisses,
     mergeSheets: options.mergeSheets,
-    warnRagged: options.warnRagged
+    excelDateColumns: options.excelDateColumns,
+    cellIssues: options.cellIssues,
+    warnRagged: options.warnRagged,
+    skipRows: options.skipRows,
+    xlsxStructure: options.xlsxStructure,
+    fillMergedCells: options.fillMergedCells,
+    excludeHiddenRows: options.excludeHiddenRows
   };
   const wrappedRow = wrapRowCallback(onRow);
   try {
@@ -864,6 +891,21 @@ function peekDelimitedRecords(filePath, options = {}) {
   });
   return records.slice(0, options.limit ?? 10);
 }
+var TITLE_ROW_SCAN_LIMIT = 3;
+var TITLE_ROW_MIN_HEADER_WIDTH = 3;
+function detectLeadingTitleRows(rows) {
+  const width = (row) => row.filter((value) => !isMissing(value)).length;
+  const titles = [];
+  for (let index = 0; index < Math.min(rows.length, TITLE_ROW_SCAN_LIMIT); index += 1) {
+    const cells = width(rows[index]);
+    if (cells > 1) break;
+    titles.push({ row: index + 1, non_empty_cells: cells });
+  }
+  if (titles.length === 0) return [];
+  const next = rows[titles.length];
+  if (!next || width(next) < TITLE_ROW_MIN_HEADER_WIDTH) return [];
+  return titles;
+}
 function escapeRegex(source) {
   return source.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
@@ -874,21 +916,29 @@ function isNumeric(value) {
 }
 async function discoverDataSets(filePath, format) {
   if (format === "csv" || format === "tsv" || format === "jsonl") {
-    return [{ id: "$", kind: "file", label: basename(filePath), selector: "$" }];
+    return { visible: [{ id: "$", kind: "file", label: basename(filePath), selector: "$" }], hidden: [] };
   }
   if (format === "xls") {
     const workbook = XLSX.readFile(filePath, { dense: true });
-    return workbook.SheetNames.map((name) => ({ id: `sheet:${name}`, kind: "sheet", label: name, selector: name }));
+    return {
+      visible: workbook.SheetNames.map((name) => ({ id: `sheet:${name}`, kind: "sheet", label: name, selector: name })),
+      hidden: []
+    };
   }
   if (format === "xlsx") {
-    return (await readXlsxSheetDefinitions(filePath)).map((sheet) => ({
+    const sheets = await readXlsxSheetDefinitions(filePath);
+    const toDataSet = (sheet) => ({
       id: `sheet:${sheet.name}`,
       kind: "sheet",
       label: sheet.name,
       selector: sheet.name
-    }));
+    });
+    return {
+      visible: sheets.filter((sheet) => !sheet.hidden).map(toDataSet),
+      hidden: sheets.filter((sheet) => sheet.hidden).map(toDataSet)
+    };
   }
-  return discoverJsonDataSets(filePath);
+  return { visible: await discoverJsonDataSets(filePath), hidden: [] };
 }
 async function discoverJsonDataSets(filePath) {
   const encoding = detectEncoding(filePath);
@@ -934,9 +984,11 @@ function childPath(parent) {
 async function streamDelimited(filePath, onRow, options) {
   const delimiter = options.delimiter ?? ",";
   const encoding = options.encoding ?? "utf-8";
+  const skipRows = Math.max(0, options.skipRows ?? 0);
   let headerNames = options.headerNames;
   if (!headerNames && options.noHeader) {
-    const firstRecord = peekDelimitedRecords(filePath, { delimiter, encoding, limit: 1 })[0] ?? [];
+    const peeked = peekDelimitedRecords(filePath, { delimiter, encoding, limit: skipRows + 1 });
+    const firstRecord = peeked[skipRows] ?? [];
     headerNames = firstRecord.map((_, index) => `col_${index + 1}`);
   }
   const parser = parseCsv({
@@ -950,9 +1002,14 @@ async function streamDelimited(filePath, onRow, options) {
   decodeTextStream(filePath, encoding).pipe(parser);
   let count = 0;
   let widthMismatches = 0;
+  let skipped = 0;
   let resolvedHeaders = headerNames;
   for await (const raw of parser) {
     const values = raw;
+    if (skipped < skipRows) {
+      skipped += 1;
+      continue;
+    }
     if (!resolvedHeaders) {
       resolvedHeaders = dedupeHeaders(values.map((header) => String(header).trim()));
       continue;
@@ -1009,13 +1066,22 @@ async function streamJson(filePath, selector, onRow, options) {
 }
 async function streamXlsx(filePath, sheetName, onRow, options) {
   const sheetDefinitions = await readXlsxSheetDefinitions(filePath);
-  const targets = options.mergeSheets ? sheetDefinitions : sheetDefinitions.filter((sheet) => sheet.name === sheetName);
+  const targets = options.mergeSheets ? sheetDefinitions.filter((sheet) => !sheet.hidden) : sheetDefinitions.filter((sheet) => sheet.name === sheetName);
+  if (options.mergeSheets) {
+    const excluded = sheetDefinitions.filter((sheet) => sheet.hidden).map((sheet) => sheet.name);
+    if (excluded.length > 0) {
+      process.stderr.write(`Warning: skipped ${excluded.length} hidden worksheet(s): ${excluded.join(", ")}.
+`);
+    }
+  }
   if (targets.length === 0) {
     throw new CliValidationError("The requested Excel Sheet was not found.", { code: "LOCAL_DATA_SET_NOT_FOUND" });
   }
   const archive = await unzipper.Open.file(filePath);
-  const sharedStringsEntry = archive.files.find((entry) => entry.path === "xl/sharedStrings.xml");
-  const sharedStrings = sharedStringsEntry ? await readXlsxSharedStrings(sharedStringsEntry) : [];
+  const workbook = await readXlsxWorkbookContext(archive.files);
+  const skipRows = Math.max(0, options.skipRows ?? 0);
+  const collector = options.xlsxStructure;
+  if (collector) collector.filled = Boolean(options.fillMergedCells);
   let count = 0;
   for (const definition of targets) {
     const worksheetEntry = archive.files.find((entry) => entry.path === definition.entryPath);
@@ -1025,19 +1091,37 @@ async function streamXlsx(filePath, sheetName, onRow, options) {
         location: { field: "input-file" }
       });
     }
-    const worksheet = new ExcelWorksheetReader({
-      workbook: {
-        sharedStrings,
-        styles: { getStyleModel: () => null },
-        properties: { model: {} }
-      },
+    const structure = collector || options.fillMergedCells || options.excludeHiddenRows ? await readXlsxSheetStructure(worksheetEntry) : EMPTY_XLSX_SHEET_STRUCTURE;
+    if (collector) {
+      collector.mergedRanges += structure.merged.length;
+      collector.hiddenRowCount += structure.hiddenRows.size;
+      for (const range of structure.merged) {
+        if (collector.mergedRefs.length < XLSX_STRUCTURE_SAMPLE_LIMIT) collector.mergedRefs.push(range.ref);
+      }
+      for (const rowNumber of structure.hiddenRows) {
+        if (collector.hiddenRows.length < XLSX_STRUCTURE_SAMPLE_LIMIT) collector.hiddenRows.push(rowNumber);
+      }
+    }
+    const merges = structure.merged.length > 0 ? new MergedRegionTracker(structure.merged, Boolean(options.fillMergedCells)) : void 0;
+    const hiddenRows = options.excludeHiddenRows ? structure.hiddenRows : void 0;
+    let hiddenColumnsResolved = false;
+    const worksheet = new import_worksheet_reader.default({
+      workbook,
       id: definition.id,
       iterator: worksheetEntry.stream(),
       options: { worksheets: "emit", hyperlinks: "ignore" }
     });
     let headers = options.headerNames;
+    let skipped = 0;
     for await (const excelRow of worksheet) {
-      const values = Array.from({ length: Math.max(0, excelRow.cellCount) }, (_, index) => normalizeExcelValue(excelRow.getCell(index + 1).value));
+      const rawValues = Array.from({ length: Math.max(0, excelRow.cellCount) }, (_, index) => readExcelCellValue(excelRow.getCell(index + 1)));
+      const reads = rawValues.map(readExcelCell);
+      const values = reads.map((read) => read.value);
+      merges?.observe(excelRow.number, values);
+      if (skipped < skipRows) {
+        skipped += 1;
+        continue;
+      }
       if (options.noHeader && !headers) {
         headers = values.map((_, index) => `col_${index + 1}`);
       }
@@ -1046,7 +1130,44 @@ async function streamXlsx(filePath, sheetName, onRow, options) {
         continue;
       }
       if (values.every(isMissing)) continue;
+      if (hiddenRows?.has(excelRow.number)) {
+        if (collector) collector.excludedHiddenRows += 1;
+        continue;
+      }
+      const covered = merges?.covered(excelRow.number, values);
       count += 1;
+      if (collector) {
+        if (!hiddenColumnsResolved) {
+          hiddenColumnsResolved = true;
+          for (const span of structure.hiddenColumns) {
+            for (let column = span.min; column <= Math.min(span.max, headers.length); column += 1) {
+              const header = headers[column - 1];
+              if (header) collector.hiddenColumns.add(header);
+            }
+          }
+        }
+        for (const column of covered ?? []) {
+          const header = headers[column - 1];
+          if (!header) continue;
+          collector.coveredCells.set(header, (collector.coveredCells.get(header) ?? 0) + 1);
+        }
+      }
+      if (options.excelDateColumns) {
+        rawValues.forEach((raw, index) => {
+          const header = headers?.[index];
+          if (header && isExcelDateCell(raw)) options.excelDateColumns?.add(header);
+        });
+      }
+      const cellIssues = options.cellIssues;
+      if (cellIssues) {
+        reads.forEach((read, index) => {
+          const header = headers?.[index];
+          if (!read.issue || !header) return;
+          const byColumn = cellIssues.get(read.issue) ?? /* @__PURE__ */ new Map();
+          byColumn.set(header, (byColumn.get(header) ?? 0) + 1);
+          cellIssues.set(read.issue, byColumn);
+        });
+      }
       const row = Object.fromEntries(headers.map((header, index) => [header, values[index] ?? null]));
       await onRow(
         options.flattenRules && Object.keys(options.flattenRules).length > 0 ? flattenDelimitedRow(row, options.flattenRules) : row,
@@ -1066,28 +1187,29 @@ async function readXlsxSheetDefinitions(filePath) {
       location: { field: "input-file" }
     });
   }
-  const [workbookXml, relationshipsXml] = await Promise.all([
-    workbookEntry.buffer().then((value) => value.toString("utf8")),
-    relationshipsEntry.buffer().then((value) => value.toString("utf8"))
-  ]);
   const targets = /* @__PURE__ */ new Map();
-  for (const match of relationshipsXml.matchAll(/<Relationship\b([^>]*)\/?\s*>/g)) {
-    const attributes = parseXmlAttributes(match[1]);
-    if (attributes.Id && attributes.Target) targets.set(attributes.Id, attributes.Target);
-  }
+  await parseXmlTags(relationshipsEntry, (tag) => {
+    if (xmlLocalName(tag.name) !== "Relationship") return;
+    const id = xmlAttributeByLocalName(tag.attributes, "Id");
+    const target = xmlAttributeByLocalName(tag.attributes, "Target");
+    if (id && target) targets.set(id, target);
+  });
   const sheets = [];
-  for (const match of workbookXml.matchAll(/<sheet\b([^>]*)\/?\s*>/g)) {
-    const attributes = parseXmlAttributes(match[1]);
-    const relationshipId = attributes["r:id"];
+  await parseXmlTags(workbookEntry, (tag) => {
+    if (xmlLocalName(tag.name) !== "sheet") return;
+    const relationshipId = xmlAttributeByLocalName(tag.attributes, "id");
     const target = relationshipId ? targets.get(relationshipId) : void 0;
     const fileNumber = target?.match(/worksheets\/sheet(\d+)\.xml$/)?.[1];
-    if (!attributes.name || !relationshipId || !fileNumber) continue;
+    const name = xmlAttributeByLocalName(tag.attributes, "name");
+    if (!name || !relationshipId || !fileNumber) return;
+    const state = xmlAttributeByLocalName(tag.attributes, "state");
     sheets.push({
-      id: Number(attributes.sheetId ?? fileNumber),
-      name: decodeXml(attributes.name),
-      entryPath: normalizeXlsxEntryPath(target)
+      id: Number(xmlAttributeByLocalName(tag.attributes, "sheetId") ?? fileNumber),
+      name: decodeXml(name),
+      entryPath: normalizeXlsxEntryPath(target),
+      hidden: state === "hidden" || state === "veryHidden"
     });
-  }
+  });
   if (sheets.length === 0) {
     throw new CliValidationError("XLSX workbook contains no readable Sheets.", {
       code: "LOCAL_DATA_XLSX_INVALID",
@@ -1110,25 +1232,21 @@ function readXlsSheetHeaders(filePath) {
 async function readXlsxSheetHeaders(filePath) {
   const sheetDefinitions = await readXlsxSheetDefinitions(filePath);
   const archive = await unzipper.Open.file(filePath);
-  const sharedStringsEntry = archive.files.find((entry) => entry.path === "xl/sharedStrings.xml");
-  const sharedStrings = sharedStringsEntry ? await readXlsxSharedStrings(sharedStringsEntry) : [];
+  const workbook = await readXlsxWorkbookContext(archive.files);
   const sheets = [];
   for (const definition of sheetDefinitions) {
+    if (definition.hidden) continue;
     const worksheetEntry = archive.files.find((entry) => entry.path === definition.entryPath);
     if (!worksheetEntry) continue;
-    const worksheet = new ExcelWorksheetReader({
-      workbook: {
-        sharedStrings,
-        styles: { getStyleModel: () => null },
-        properties: { model: {} }
-      },
+    const worksheet = new import_worksheet_reader.default({
+      workbook,
       id: definition.id,
       iterator: worksheetEntry.stream(),
       options: { worksheets: "emit", hyperlinks: "ignore" }
     });
     let headers = [];
     for await (const excelRow of worksheet) {
-      const values = Array.from({ length: Math.max(0, excelRow.cellCount) }, (_, index) => normalizeExcelValue(excelRow.getCell(index + 1).value));
+      const values = Array.from({ length: Math.max(0, excelRow.cellCount) }, (_, index) => readExcelCell(readExcelCellValue(excelRow.getCell(index + 1))).value);
       headers = firstRowHeaders(values);
       break;
     }
@@ -1139,13 +1257,82 @@ async function readXlsxSheetHeaders(filePath) {
 function firstRowHeaders(values) {
   return dedupeHeaders(values.map((value, index) => String(value ?? `column_${index + 1}`).trim()));
 }
+async function peekXlsxRows(filePath, sheetName, limit = 10) {
+  const sheetDefinitions = await readXlsxSheetDefinitions(filePath);
+  const definition = sheetDefinitions.find((sheet) => sheet.name === sheetName);
+  if (!definition) return [];
+  const archive = await unzipper.Open.file(filePath);
+  const worksheetEntry = archive.files.find((entry) => entry.path === definition.entryPath);
+  if (!worksheetEntry) return [];
+  const workbook = await readXlsxWorkbookContext(archive.files);
+  const worksheet = new import_worksheet_reader.default({
+    workbook,
+    id: definition.id,
+    iterator: worksheetEntry.stream(),
+    options: { worksheets: "emit", hyperlinks: "ignore" }
+  });
+  const rows = [];
+  for await (const excelRow of worksheet) {
+    rows.push(Array.from({ length: Math.max(0, excelRow.cellCount) }, (_, index) => readExcelCell(readExcelCellValue(excelRow.getCell(index + 1))).value));
+    if (rows.length >= limit) break;
+  }
+  return rows;
+}
+var NO_XLSX_STYLES = { getStyleModel: () => null };
+var ELAPSED_TIME_FORMATS = /* @__PURE__ */ new Set(["mm:ss", "mmss.0", "[h]:mm:ss"]);
+function isElapsedTimeFormat(numFmt) {
+  return ELAPSED_TIME_FORMATS.has(numFmt.trim()) || /\[[hms]+\]/i.test(numFmt);
+}
+async function readXlsxWorkbookContext(files) {
+  const sharedStringsEntry = files.find((entry) => entry.path === "xl/sharedStrings.xml");
+  const stylesEntry = files.find((entry) => entry.path === "xl/styles.xml");
+  const workbookEntry = files.find((entry) => entry.path === "xl/workbook.xml");
+  return {
+    sharedStrings: sharedStringsEntry ? await readXlsxSharedStrings(sharedStringsEntry) : [],
+    styles: await readXlsxStyles(stylesEntry),
+    properties: { model: { date1904: workbookEntry ? await readXlsxDate1904(workbookEntry) : false } }
+  };
+}
+async function readXlsxStyles(entry) {
+  if (!entry) return NO_XLSX_STYLES;
+  let styles;
+  try {
+    styles = new import_styles_xform.default();
+    styles.init();
+    await styles.parseStream(entry.stream());
+  } catch {
+    return NO_XLSX_STYLES;
+  }
+  return {
+    getStyleModel: (id) => {
+      let model;
+      try {
+        model = styles.getStyleModel(id);
+      } catch {
+        return null;
+      }
+      if (!model?.numFmt || !isElapsedTimeFormat(model.numFmt)) return model;
+      const { numFmt, ...rest } = model;
+      return rest;
+    }
+  };
+}
+async function readXlsxDate1904(entry) {
+  let date1904 = false;
+  await parseXmlTags(entry, (tag) => {
+    if (xmlLocalName(tag.name) !== "workbookPr") return;
+    const value = xmlAttributeByLocalName(tag.attributes, "date1904");
+    date1904 = value === "1" || value === "true";
+  });
+  return date1904;
+}
 async function readXlsxSharedStrings(entry) {
   const values = [];
   let inItem = false;
   let current = "";
   const parser = new SaxesParser();
   parser.on("opentag", (tag) => {
-    if (tag.name === "si") {
+    if (xmlLocalName(tag.name) === "si") {
       inItem = true;
       current = "";
     }
@@ -1154,26 +1341,147 @@ async function readXlsxSharedStrings(entry) {
     if (inItem) current += text;
   });
   parser.on("closetag", (tag) => {
-    if (tag.name === "si") {
+    if (xmlLocalName(tag.name) === "si") {
       values.push(current);
       inItem = false;
       current = "";
     }
   });
+  const decoder = new StringDecoder("utf8");
   for await (const chunk of entry.stream()) {
-    parser.write(Buffer.from(chunk).toString("utf8"));
+    parser.write(decoder.write(Buffer.from(chunk)));
   }
+  parser.write(decoder.end());
   parser.close();
   return values;
 }
+var EMPTY_XLSX_SHEET_STRUCTURE = {
+  merged: [],
+  hiddenRows: /* @__PURE__ */ new Set(),
+  hiddenColumns: []
+};
+async function readXlsxSheetStructure(entry) {
+  const merged = [];
+  const hiddenRows = /* @__PURE__ */ new Set();
+  const hiddenColumns = [];
+  try {
+    const parser = new SaxesParser();
+    parser.on("opentag", (tag) => {
+      const attributes = tag.attributes;
+      if (xmlLocalName(tag.name) === "mergeCell") {
+        const range = parseMergedRef(attributes.ref ?? "");
+        if (range) merged.push(range);
+        return;
+      }
+      if (xmlLocalName(tag.name) === "row") {
+        const rowNumber = Number(attributes.r);
+        if (isXlsxFlagSet(attributes.hidden) && Number.isInteger(rowNumber) && rowNumber >= 1) {
+          hiddenRows.add(rowNumber);
+        }
+        return;
+      }
+      if (xmlLocalName(tag.name) === "col" && isXlsxFlagSet(attributes.hidden)) {
+        const min = Number(attributes.min);
+        const max = Number(attributes.max);
+        if (Number.isInteger(min) && min >= 1) {
+          hiddenColumns.push({ min, max: Number.isInteger(max) && max >= min ? max : min });
+        }
+      }
+    });
+    const decoder = new StringDecoder("utf8");
+    for await (const chunk of entry.stream()) {
+      parser.write(decoder.write(Buffer.from(chunk)));
+    }
+    parser.write(decoder.end());
+    parser.close();
+  } catch {
+    return EMPTY_XLSX_SHEET_STRUCTURE;
+  }
+  return { merged, hiddenRows, hiddenColumns };
+}
+function isXlsxFlagSet(value) {
+  return value === "1" || value === "true";
+}
+function parseMergedRef(ref) {
+  const match = /^([A-Za-z]+)(\d+):([A-Za-z]+)(\d+)$/.exec(ref.trim());
+  if (!match) return void 0;
+  const left = xlsxColumnNumber(match[1]);
+  const top = Number(match[2]);
+  const right = xlsxColumnNumber(match[3]);
+  const bottom = Number(match[4]);
+  if (right < left || bottom < top || top < 1) return void 0;
+  return { ref: ref.trim().toUpperCase(), top, bottom, left, right };
+}
+function xlsxColumnNumber(letters) {
+  let column = 0;
+  for (const letter of letters.toUpperCase()) column = column * 26 + (letter.charCodeAt(0) - 64);
+  return column;
+}
+var MergedRegionTracker = class {
+  constructor(ranges, fill) {
+    this.fill = fill;
+    this.pending = [...ranges].sort((left, right) => left.top - right.top || left.left - right.left);
+  }
+  fill;
+  pending;
+  next = 0;
+  active = [];
+  /** Advance to `rowNumber`, taking the anchor value of every range that starts on it. */
+  observe(rowNumber, values) {
+    while (this.next < this.pending.length && this.pending[this.next].top <= rowNumber) {
+      this.active.push({ range: this.pending[this.next], anchor: void 0 });
+      this.next += 1;
+    }
+    if (this.active.length === 0) return;
+    this.active = this.active.filter((entry) => entry.range.bottom >= rowNumber);
+    for (const entry of this.active) {
+      if (entry.range.top === rowNumber) entry.anchor = values[entry.range.left - 1];
+    }
+  }
+  /**
+   * The 1-based columns whose cell on this row is empty only because a merge covers it, filled from
+   * the anchor when enabled. `observe` must have run for the same row first.
+   */
+  covered(rowNumber, values) {
+    const columns = [];
+    for (const entry of this.active) {
+      if (isMissing(entry.anchor)) continue;
+      const { range } = entry;
+      for (let column = range.left; column <= range.right; column += 1) {
+        if (range.top === rowNumber && column === range.left) continue;
+        if (!isMissing(values[column - 1])) continue;
+        columns.push(column);
+        if (this.fill) values[column - 1] = entry.anchor;
+      }
+    }
+    return columns;
+  }
+};
 function normalizeXlsxEntryPath(target) {
   const normalized = target.replace(/^\//, "");
   return normalized.startsWith("xl/") ? normalized : `xl/${normalized.replace(/^\.\//, "")}`;
 }
-function parseXmlAttributes(source) {
-  const attributes = {};
-  for (const match of source.matchAll(/([\w:-]+)="([^"]*)"/g)) attributes[match[1]] = match[2];
-  return attributes;
+function xmlLocalName(qname) {
+  const colon = qname.lastIndexOf(":");
+  return colon === -1 ? qname : qname.slice(colon + 1);
+}
+function xmlAttributeByLocalName(attributes, local) {
+  for (const [name, value] of Object.entries(attributes)) {
+    if (xmlLocalName(name) === local) return value;
+  }
+  return void 0;
+}
+async function parseXmlTags(entry, onOpenTag) {
+  const parser = new SaxesParser();
+  parser.on("opentag", (tag) => {
+    onOpenTag({ name: tag.name, attributes: tag.attributes });
+  });
+  const decoder = new StringDecoder("utf8");
+  for await (const chunk of entry.stream()) {
+    parser.write(decoder.write(Buffer.from(chunk)));
+  }
+  parser.write(decoder.end());
+  parser.close();
 }
 function decodeXml(source) {
   return source.replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
@@ -1185,10 +1493,12 @@ async function streamXls(filePath, sheetName, onRow, options) {
     throw new CliValidationError("The requested Excel Sheet was not found.", { code: "LOCAL_DATA_SET_NOT_FOUND" });
   }
   let count = 0;
+  const skipRows = Math.max(0, options.skipRows ?? 0);
   for (const name of names) {
     const sheet = workbook.Sheets[name];
     if (!sheet) continue;
-    const rows = XLSX.utils.sheet_to_json(sheet, { header: 1, raw: true, defval: null });
+    const allRows = XLSX.utils.sheet_to_json(sheet, { header: 1, raw: true, defval: null });
+    const rows = allRows.slice(skipRows);
     if (rows.length === 0) continue;
     let headers = options.headerNames;
     let start = 0;
@@ -1212,16 +1522,127 @@ async function streamXls(filePath, sheetName, onRow, options) {
   }
   return count;
 }
-function normalizeExcelValue(value) {
-  if (value instanceof Date) return value;
+function excelDateToWallClock(value) {
+  const pad = (part, width = 2) => String(part).padStart(width, "0");
+  const date = `${value.getUTCFullYear()}-${pad(value.getUTCMonth() + 1)}-${pad(value.getUTCDate())}`;
+  const [hours, minutes, seconds, ms] = [
+    value.getUTCHours(),
+    value.getUTCMinutes(),
+    value.getUTCSeconds(),
+    value.getUTCMilliseconds()
+  ];
+  if (hours === 0 && minutes === 0 && seconds === 0 && ms === 0) return date;
+  const time = `${pad(hours)}:${pad(minutes)}:${pad(seconds)}`;
+  return ms === 0 ? `${date} ${time}` : `${date} ${time}.${pad(ms, 3)}`;
+}
+function isExcelDateCell(value) {
+  if (value instanceof Date) return true;
+  return Boolean(value && typeof value === "object" && "result" in value && value.result instanceof Date);
+}
+function readExcelCellValue(cell) {
+  if (cell.type !== import_exceljs.default.ValueType.Formula) return cell.value;
+  const model = cell.model;
+  if (!model || !("result" in model)) return cell.value;
+  return { formula: model.formula ?? "", result: model.result };
+}
+var CELL_ISSUE_ORDER = ["formula_no_cached_value", "error_value", "unreadable_object"];
+var CELL_ISSUE_MESSAGES = {
+  formula_no_cached_value: "hold a formula whose last computed result is not stored in the file, and were read as missing. Excel normally saves that result next to the formula; a file exported without it has no value to upload. Recalculate and re-export in Excel, or export values instead of formulas. This tool never evaluates a formula and never guesses a result.",
+  error_value: "hold an Excel error value (#N/A, #DIV/0!, \u2026), and were read as missing. Fix them in the source file if those cells were meant to carry data.",
+  unreadable_object: "arrived in a cell shape this tool does not recognize, and were read as missing rather than passed on as an object. Report the file if these cells do carry data."
+};
+function cellIssueWarnings(cellIssues) {
+  const warnings = [];
+  for (const issue of CELL_ISSUE_ORDER) {
+    const byColumn = cellIssues.get(issue);
+    if (!byColumn || byColumn.size === 0) continue;
+    const columns = [...byColumn.entries()].map(([column, count]) => `${column} (${count})`).join(", ");
+    const total = [...byColumn.values()].reduce((sum, count) => sum + count, 0);
+    warnings.push(`${total} cell(s) ${CELL_ISSUE_MESSAGES[issue]} Affected columns: ${columns}.`);
+  }
+  return warnings;
+}
+function cellIssueCounts(cellIssues) {
+  const counts = {};
+  for (const issue of CELL_ISSUE_ORDER) {
+    const byColumn = cellIssues.get(issue);
+    if (!byColumn || byColumn.size === 0) continue;
+    counts[issue] = Object.fromEntries(byColumn);
+  }
+  return counts;
+}
+var XLSX_STRUCTURE_SAMPLE_LIMIT = 10;
+function createXlsxStructureCollector() {
+  return {
+    mergedRanges: 0,
+    mergedRefs: [],
+    coveredCells: /* @__PURE__ */ new Map(),
+    filled: false,
+    hiddenRows: [],
+    hiddenRowCount: 0,
+    excludedHiddenRows: 0,
+    hiddenColumns: /* @__PURE__ */ new Set()
+  };
+}
+function xlsxStructureReport(collector) {
+  const hasFindings = collector.mergedRanges > 0 || collector.hiddenRowCount > 0 || collector.hiddenColumns.size > 0;
+  if (!hasFindings) return void 0;
+  return {
+    ...collector.mergedRanges > 0 ? {
+      merged_ranges: collector.mergedRanges,
+      merged_range_samples: collector.mergedRefs,
+      merged_covered_cells: Object.fromEntries(collector.coveredCells),
+      merged_cells_filled: collector.filled
+    } : {},
+    ...collector.hiddenRowCount > 0 ? {
+      hidden_rows: collector.hiddenRowCount,
+      hidden_row_samples: collector.hiddenRows,
+      excluded_hidden_rows: collector.excludedHiddenRows
+    } : {},
+    ...collector.hiddenColumns.size > 0 ? { hidden_columns: [...collector.hiddenColumns] } : {}
+  };
+}
+function xlsxStructureWarnings(collector, excludedColumns) {
+  const warnings = [];
+  const sample = (values, total) => values.join(", ") + (total > values.length ? ", \u2026" : "");
+  if (collector.coveredCells.size > 0) {
+    const columns = [...collector.coveredCells.entries()].map(([column, count]) => `${column} (${count})`).join(", ");
+    const total = [...collector.coveredCells.values()].reduce((sum, count) => sum + count, 0);
+    warnings.push(collector.filled ? `${total} cell(s) were empty only because a merged block covers them, and were filled from the value on the block's first row. Affected columns: ${columns}.` : `${total} cell(s) are empty only because a merged block covers them: Excel shows the value on the block's first row only, so every row below it reads as missing. Affected columns: ${columns}. Pass --fill-merged-cells to copy each block's value down its own range, or unmerge and fill the column in the source file.`);
+  }
+  if (collector.hiddenRowCount > 0) {
+    const rows = sample(collector.hiddenRows, collector.hiddenRowCount);
+    warnings.push(collector.excludedHiddenRows > 0 ? `Skipped ${collector.excludedHiddenRows} row(s) hidden in the source worksheet (source row ${rows}).` : `${collector.hiddenRowCount} row(s) are hidden in the source worksheet (source row ${rows}) and were read as data. Pass --exclude-hidden-rows to leave them out.`);
+  }
+  if (collector.hiddenColumns.size > 0) {
+    const excluded = new Set(excludedColumns ?? []);
+    const kept = [...collector.hiddenColumns].filter((column) => !excluded.has(column));
+    if (kept.length > 0) {
+      warnings.push(`${kept.length} column(s) are hidden in the source worksheet and were read as data: ${kept.join(", ")}. List them in the mapping's exclude_columns to leave them out.`);
+    }
+  }
+  return warnings;
+}
+function readExcelCell(value) {
+  if (value instanceof Date) return { value: excelDateToWallClock(value) };
   if (value && typeof value === "object") {
-    if ("result" in value) return value.result ?? null;
-    if ("text" in value) return String(value.text);
+    if ("error" in value) return { value: null, issue: "error_value" };
+    if ("formula" in value || "sharedFormula" in value) {
+      if (!("result" in value)) return { value: null, issue: "formula_no_cached_value" };
+      const result = value.result;
+      if (result === null || result === void 0) return { value: null, issue: "formula_no_cached_value" };
+      if (typeof result === "object" && "error" in result) return { value: null, issue: "error_value" };
+      if (typeof result === "number" && Number.isNaN(result)) return { value: null, issue: "error_value" };
+      if (result instanceof Date) return { value: excelDateToWallClock(result) };
+      return { value: result };
+    }
+    if ("text" in value) return { value: String(value.text) };
     if ("richText" in value) {
-      return value.richText.map((part) => part.text).join("");
+      return { value: value.richText.map((part) => part.text).join("") };
     }
+    return { value: null, issue: "unreadable_object" };
   }
-  return value ?? null;
+  return { value: value ?? null };
 }
 function dedupeHeaders(headers) {
   const counts = /* @__PURE__ */ new Map();
@@ -1263,7 +1684,11 @@ var MAPPING_VERSION = "ae-data-integration-mapping/v1";
 // src/commands/data-integration/mapping.ts
 var VALID_PROPERTY_NAME = /^[a-z][a-z0-9_]{0,49}$/;
 var VALID_CHILD_PROPERTY_NAME = /^[a-z][a-z0-9_]{0,49}(\.[a-z][a-z0-9_]{0,49})+$/;
+var VALID_EVENT_NAME = /^[A-Za-z][A-Za-z0-9_]{0,49}$/;
 var FLATTEN_SUPPORTED_FORMATS = ["csv", "tsv", "json", "jsonl", "xls", "xlsx"];
+var SKIP_ROWS_SUPPORTED_FORMATS = ["csv", "tsv", "xls", "xlsx"];
+var XLSX_STRUCTURE_SUPPORTED_FORMATS = ["xlsx"];
+var XLSX_STRUCTURE_FIELDS = ["fill_merged_cells", "exclude_hidden_rows"];
 function readLocalDataMapping(raw, options) {
   const trimmed = raw.trim();
   let text;
@@ -1319,7 +1744,7 @@ function validateMapping(value, options) {
   if (value.mode !== "user_set" && !value.event_name_field && !value.default_event_name) {
     throw mappingError("Track mappings require an event field or default event name.");
   }
-  if (value.default_event_name && !VALID_PROPERTY_NAME.test(value.default_event_name)) {
+  if (value.default_event_name && !VALID_EVENT_NAME.test(value.default_event_name)) {
     throw mappingError("The default event name is not a legal AE event name.");
   }
   if (!Array.isArray(value.properties)) throw mappingError("Mapping properties must be an array.");
@@ -1353,7 +1778,7 @@ function validateMapping(value, options) {
   if (value.event_meta !== void 0) {
     if (!isRecord(value.event_meta)) throw mappingError("event_meta must be an object keyed by AE event name.");
     for (const [name, meta] of Object.entries(value.event_meta)) {
-      if (!VALID_PROPERTY_NAME.test(name) || !isRecord(meta) || meta.desc !== void 0 && (typeof meta.desc !== "string" || !meta.desc.trim() || meta.desc.length > 200) || meta.tag !== void 0 && (typeof meta.tag !== "string" || !meta.tag.trim() || meta.tag.length > 64)) {
+      if (!VALID_EVENT_NAME.test(name) || !isRecord(meta) || meta.desc !== void 0 && (typeof meta.desc !== "string" || !meta.desc.trim() || meta.desc.length > 200) || meta.tag !== void 0 && (typeof meta.tag !== "string" || !meta.tag.trim() || meta.tag.length > 64)) {
         throw mappingError("event_meta entries need a legal AE event name and non-empty desc/tag strings.");
       }
     }
@@ -1366,7 +1791,7 @@ function validateMapping(value, options) {
       if (!isStringMap(map)) throw mappingError(`value_mapping.${key} must map strings to strings.`);
       if (key === "event_name") {
         for (const target of Object.values(map)) {
-          if (!VALID_PROPERTY_NAME.test(target)) {
+          if (!VALID_EVENT_NAME.test(target)) {
             throw mappingError("value_mapping.event_name values must be legal AE event names.");
           }
         }
@@ -1399,6 +1824,23 @@ function validateMapping(value, options) {
   if (value.headers !== void 0 && !isNonEmptyStringArray(value.headers, true)) {
     throw mappingError("headers must be a non-empty array of unique strings.");
   }
+  if (value.skip_rows !== void 0) {
+    if (typeof value.skip_rows !== "number" || !Number.isInteger(value.skip_rows) || value.skip_rows < 1) {
+      throw mappingError("skip_rows must be a positive integer.");
+    }
+    if (!SKIP_ROWS_SUPPORTED_FORMATS.includes(String(value.source.format))) {
+      throw mappingError(`skip_rows is not supported for ${String(value.source.format)} input.`);
+    }
+  }
+  for (const field of XLSX_STRUCTURE_FIELDS) {
+    if (value[field] === void 0) continue;
+    if (typeof value[field] !== "boolean") {
+      throw mappingError(`${field} must be a boolean when provided.`);
+    }
+    if (!XLSX_STRUCTURE_SUPPORTED_FORMATS.includes(String(value.source.format))) {
+      throw mappingError(`${field} is not supported for ${String(value.source.format)} input.`);
+    }
+  }
   if (value.missing_time !== void 0 && value.missing_time !== "now") {
     throw mappingError('missing_time must be "now" when provided.');
   }
@@ -1433,6 +1875,9 @@ function validateMapping(value, options) {
 function isValidAeName(value) {
   return VALID_PROPERTY_NAME.test(value);
 }
+function isValidEventName(value) {
+  return VALID_EVENT_NAME.test(value);
+}
 function sourceColumns(mapping) {
   const columns = /* @__PURE__ */ new Set();
   const flattenOut = new Set(Object.keys(mapping.flatten_rules ?? {}));
@@ -1674,6 +2119,18 @@ var GLOBAL_UNIQUE_SAMPLE_LIMIT = 2e5;
 var IDENTITY_MAX_LENGTH = 128;
 var COLUMN_SAMPLE_LIMIT = 5;
 var SAMPLE_TRUNCATE_LENGTH = 40;
+var VALUE_FREQUENCY_LIMIT = 200;
+var VALUE_FREQUENCY_TOP = 10;
+var NUMERIC_SAMPLE_LIMIT = 5e3;
+var SUMMARY_ROW_CANDIDATE_LIMIT = 50;
+var SUMMARY_ROW_WARNING_LIMIT = 10;
+var SUMMARY_LABEL_MAX_LENGTH = 24;
+var SUMMARY_LABELS_CJK = ["\u5408\u8BA1", "\u603B\u8BA1", "\u5C0F\u8BA1", "\u6C47\u603B"];
+var SUMMARY_LABELS_LATIN = /* @__PURE__ */ new Set(["total", "totals", "subtotal", "sub total", "grand total", "sum"]);
+var DUPLICATE_KEY_TRACK_LIMIT = 2e5;
+var DUPLICATE_GROUP_LIMIT = 20;
+var DUPLICATE_GROUP_ROW_LIMIT = 10;
+var DUPLICATE_WARNING_GROUP_LIMIT = 3;
 var NESTED_TREE_SAMPLE_LIMIT = 1e3;
 var USER_PROFILE_TYPES = /* @__PURE__ */ new Set([
   "user_set",
@@ -1708,10 +2165,17 @@ async function profileLocalData(input, dataSet, sourceTimezone = "Asia/Shanghai"
   let nestedObjects = [];
   let nestedSeen = 0;
   const delimitedNested = /* @__PURE__ */ new Map();
+  const excelDateColumns = /* @__PURE__ */ new Set();
+  const cellIssues = /* @__PURE__ */ new Map();
+  const xlsxStructure = input.format === "xlsx" ? createXlsxStructureCollector() : void 0;
+  const summaryCandidates = [];
+  let summaryCandidatesTruncated = false;
+  let duplicateKeys;
+  let duplicateKeysResolved = false;
   await streamLocalDataRows(
     input,
     dataSet,
-    (row) => {
+    (row, rowNumber) => {
       rowCount += 1;
       if (collectNestedTree && row !== null && typeof row === "object" && !Array.isArray(row)) {
         nestedSeen += 1;
@@ -1722,6 +2186,10 @@ async function profileLocalData(input, dataSet, sourceTimezone = "Asia/Shanghai"
           if (slot < NESTED_TREE_SAMPLE_LIMIT) nestedObjects[slot] = row;
         }
       }
+      let labelColumn;
+      let numericCells;
+      let keyColumnsPresent = false;
+      let keyColumnsFilled = false;
       for (const name of /* @__PURE__ */ new Set([...columns.keys(), ...Object.keys(row)])) {
         let accumulator = columns.get(name);
         if (!accumulator) {
@@ -1738,11 +2206,23 @@ async function profileLocalData(input, dataSet, sourceTimezone = "Asia/Shanghai"
             ipValidCount: 0,
             lanIpCount: 0,
             samples: [],
-            sampleSet: /* @__PURE__ */ new Set()
+            sampleSet: /* @__PURE__ */ new Set(),
+            valueCounts: /* @__PURE__ */ new Map(),
+            valueCountsOverflow: false,
+            numericCount: 0,
+            numericSum: 0,
+            numericMin: Number.POSITIVE_INFINITY,
+            numericMax: Number.NEGATIVE_INFINITY,
+            numericSamples: [],
+            keyLike: matchesName(name, ACCOUNT_NAMES) || matchesName(name, DISTINCT_NAMES) || matchesName(name, TIME_NAMES)
           };
           columns.set(name, accumulator);
         }
         const value = row[name];
+        if (accumulator.keyLike) {
+          keyColumnsPresent = true;
+          if (!isMissing2(value)) keyColumnsFilled = true;
+        }
         if (isMissing2(value)) {
           accumulator.missing += 1;
           continue;
@@ -1758,7 +2238,17 @@ async function profileLocalData(input, dataSet, sourceTimezone = "Asia/Shanghai"
         } else {
           accumulator.uniqueOverflow = true;
         }
-        if (options.collectSamples) recordSample(accumulator, value);
+        if (options.collectSamples) {
+          recordSample(accumulator, value);
+          recordValueFrequency(accumulator, value);
+        }
+        if (type === "number") {
+          const numeric = Number(value);
+          recordNumeric(accumulator, numeric, options.collectSamples === true);
+          if (Number.isFinite(numeric)) (numericCells ??= []).push([name, numeric]);
+        } else if (labelColumn === void 0 && matchesSummaryLabel(value)) {
+          labelColumn = name;
+        }
         if (collectDelimitedTree && typeof value === "string") {
           const trimmed = value.trim();
           if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
@@ -1801,6 +2291,19 @@ async function profileLocalData(input, dataSet, sourceTimezone = "Asia/Shanghai"
           if (normalized) recognizedRecordTypes.add(normalized);
         }
       }
+      if (labelColumn !== void 0 || keyColumnsPresent && !keyColumnsFilled && numericCells !== void 0) {
+        if (summaryCandidates.length < SUMMARY_ROW_CANDIDATE_LIMIT) {
+          summaryCandidates.push({ row: rowNumber, labelColumn, numericCells: numericCells ?? [] });
+        } else {
+          summaryCandidatesTruncated = true;
+        }
+      }
+      if (!duplicateKeysResolved) {
+        duplicateKeysResolved = true;
+        const keyColumns = resolveDuplicateKeyColumns(Object.keys(row), options.duplicateKeyFields);
+        if (keyColumns) duplicateKeys = createDuplicateKeyTracker(keyColumns);
+      }
+      if (duplicateKeys) recordDuplicateKey(duplicateKeys, row, rowNumber);
     },
     {
       delimiter: options.delimiter,
@@ -1809,7 +2312,13 @@ async function profileLocalData(input, dataSet, sourceTimezone = "Asia/Shanghai"
       noHeader: options.noHeader,
       flattenRules: options.flattenRules,
       mergeSheets: options.mergeSheets,
-      warnRagged: options.warnRagged
+      excelDateColumns,
+      cellIssues,
+      warnRagged: options.warnRagged,
+      skipRows: options.skipRows,
+      xlsxStructure,
+      fillMergedCells: options.fillMergedCells,
+      excludeHiddenRows: options.excludeHiddenRows
     }
   );
   const delimitedNestedTree = /* @__PURE__ */ new Map();
@@ -1836,6 +2345,9 @@ async function profileLocalData(input, dataSet, sourceTimezone = "Asia/Shanghai"
     recognizedRecordTypes,
     sourceTimezone,
     headerNames: options.headerNames,
+    skipRows: options.skipRows,
+    fillMergedCells: options.fillMergedCells,
+    excludeHiddenRows: options.excludeHiddenRows,
     timeFormatByColumn,
     nestedTree
   });
@@ -1851,6 +2363,16 @@ async function profileLocalData(input, dataSet, sourceTimezone = "Asia/Shanghai"
       if (column.lanIpCount > 0) warnings.push(`${column.name}: ${column.lanIpCount} value(s) are private/LAN IP addresses; AE cannot resolve geo information for them.`);
     }
   }
+  if (excelDateColumns.size > 0) {
+    warnings.push(`${[...excelDateColumns].join(", ")}: read as date/time value(s) from the Excel number format rather than as Excel serial numbers. If these columns were uploaded to AE before, they may have been received as number properties, whose type is now locked; confirm with the user before mapping them.`);
+  }
+  warnings.push(...cellIssueWarnings(cellIssues));
+  if (xlsxStructure) warnings.push(...xlsxStructureWarnings(xlsxStructure));
+  const structureReport = xlsxStructure ? xlsxStructureReport(xlsxStructure) : void 0;
+  const summaryRows = confirmSummaryRows(summaryCandidates, columns);
+  if (summaryRows.length > 0) warnings.push(summaryRowWarning(summaryRows, summaryCandidatesTruncated));
+  const duplicateKeyReport = duplicateKeys ? buildDuplicateKeyReport(duplicateKeys) : void 0;
+  if (duplicateKeyReport) warnings.push(duplicateKeyWarning(duplicateKeyReport));
   if (rowCount === 0) warnings.push("The selected data set contains no data rows.");
   return {
     version: "ae-local-data-profile/v1",
@@ -1869,7 +2391,10 @@ async function profileLocalData(input, dataSet, sourceTimezone = "Asia/Shanghai"
       (recommendedMapping.account_id_field || recommendedMapping.distinct_id_field) && recommendedMapping.time.field
     ),
     warnings,
-    ...nestedTree ? { nested_tree: nestedTree } : {}
+    ...nestedTree ? { nested_tree: nestedTree } : {},
+    ...structureReport ? { xlsx_structure: structureReport } : {},
+    ...summaryRows.length > 0 ? { summary_rows: summaryRows } : {},
+    ...duplicateKeyReport ? { duplicate_keys: duplicateKeyReport } : {}
   };
 }
 function normalizeAeName(input, fallback) {
@@ -1964,6 +2489,9 @@ function recommendMapping(input) {
     },
     ...time ? { time_format: input.timeFormatByColumn.get(time.name) } : {},
     ...input.headerNames && input.headerNames.length > 0 ? { headers: input.headerNames } : {},
+    ...input.skipRows ? { skip_rows: input.skipRows } : {},
+    ...input.fillMergedCells ? { fill_merged_cells: true } : {},
+    ...input.excludeHiddenRows ? { exclude_hidden_rows: true } : {},
     ...recordType ? { record_type_field: recordType.name } : {},
     ...event ? { event_name_field: event.name } : {},
     ...mode !== "user_set" && !event ? { default_event_name: normalizeAeName(defaultEventSource, "local_event") } : {},
@@ -1976,7 +2504,7 @@ function formatColumnProfile(column, rowCount, includeSamples) {
   const nonNullTypes = [...column.types.entries()].filter(([type]) => type !== "null").sort((left, right) => right[1] - left[1]);
   const inferred = nonNullTypes.length === 0 ? "unknown" : nonNullTypes.length === 1 ? nonNullTypes[0][0] : compatibleTypes(nonNullTypes.map(([type]) => type)) ? nonNullTypes[0][0] : "mixed";
   const finalType = inferred === "number" && idLikeColumn(column.name) ? "string" : inferred;
-  return {
+  const profile = {
     name: column.name,
     inferred_type: finalType,
     missing_count: column.missing,
@@ -1988,6 +2516,15 @@ function formatColumnProfile(column, rowCount, includeSamples) {
     time_parse_ratio: ratio(column.timeParseCount, column.nonMissing),
     ...includeSamples ? { samples: column.samples } : {}
   };
+  if (includeSamples) {
+    const frequency = formatValueFrequency(column);
+    if (frequency) profile.value_frequency = frequency;
+    if (finalType === "number") {
+      const summary = formatNumericSummary(column);
+      if (summary) profile.numeric_summary = summary;
+    }
+  }
+  return profile;
 }
 function findCandidate(columns, names) {
   return columns.find((column) => matchesName(column.name, names));
@@ -2202,6 +2739,176 @@ function recordSample(accumulator, value) {
   accumulator.sampleSet.add(text);
   accumulator.samples.push(text);
 }
+function recordValueFrequency(accumulator, value) {
+  if (accumulator.valueCountsOverflow) return;
+  const text = truncateSample2(value);
+  const seen = accumulator.valueCounts.get(text);
+  if (seen !== void 0) {
+    accumulator.valueCounts.set(text, seen + 1);
+    return;
+  }
+  if (accumulator.valueCounts.size >= VALUE_FREQUENCY_LIMIT) {
+    accumulator.valueCountsOverflow = true;
+    accumulator.valueCounts.clear();
+    return;
+  }
+  accumulator.valueCounts.set(text, 1);
+}
+function recordNumeric(accumulator, numeric, retainForQuantiles) {
+  if (!Number.isFinite(numeric)) return;
+  accumulator.numericCount += 1;
+  accumulator.numericSum += numeric;
+  if (numeric < accumulator.numericMin) accumulator.numericMin = numeric;
+  if (numeric > accumulator.numericMax) accumulator.numericMax = numeric;
+  if (!retainForQuantiles) return;
+  if (accumulator.numericSamples.length < NUMERIC_SAMPLE_LIMIT) {
+    accumulator.numericSamples.push(numeric);
+    return;
+  }
+  const slot = randomInt(accumulator.numericCount);
+  if (slot < NUMERIC_SAMPLE_LIMIT) accumulator.numericSamples[slot] = numeric;
+}
+function formatValueFrequency(accumulator) {
+  if (accumulator.valueCountsOverflow || accumulator.valueCounts.size === 0) return void 0;
+  const ordered = [...accumulator.valueCounts.entries()].sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]));
+  if (ordered[0][1] < 2) return void 0;
+  return ordered.slice(0, VALUE_FREQUENCY_TOP).map(([value, count]) => ({ value, count, ratio: ratio(count, accumulator.nonMissing) }));
+}
+function formatNumericSummary(accumulator) {
+  if (accumulator.numericCount === 0 || accumulator.numericSamples.length === 0) return void 0;
+  const sorted = [...accumulator.numericSamples].sort((left, right) => left - right);
+  return {
+    count: accumulator.numericCount,
+    min: round(accumulator.numericMin),
+    max: round(accumulator.numericMax),
+    sum: round(accumulator.numericSum),
+    mean: round(accumulator.numericSum / accumulator.numericCount),
+    p25: round(quantile(sorted, 0.25)),
+    median: round(quantile(sorted, 0.5)),
+    p75: round(quantile(sorted, 0.75)),
+    quantiles_approximate: accumulator.numericCount > accumulator.numericSamples.length
+  };
+}
+function quantile(sorted, fraction) {
+  const position = (sorted.length - 1) * fraction;
+  const lower = Math.floor(position);
+  const upper = Math.ceil(position);
+  if (lower === upper) return sorted[lower];
+  return sorted[lower] + (sorted[upper] - sorted[lower]) * (position - lower);
+}
+function round(value) {
+  return Number.isFinite(value) ? Number(value.toFixed(6)) : value;
+}
+function matchesSummaryLabel(value) {
+  if (typeof value !== "string") return false;
+  const text = value.trim().replace(/[\s:：、,，.。]+$/u, "");
+  if (text.length === 0 || text.length > SUMMARY_LABEL_MAX_LENGTH) return false;
+  if (SUMMARY_LABELS_CJK.some((label) => text.startsWith(label))) return true;
+  return SUMMARY_LABELS_LATIN.has(text.toLowerCase());
+}
+function confirmSummaryRows(candidates, columns) {
+  const confirmed = [];
+  for (const candidate of candidates) {
+    const totalColumns = [];
+    for (const [name, value] of candidate.numericCells) {
+      const accumulator = columns.get(name);
+      if (!accumulator || accumulator.numericCount < 3 || value === 0) continue;
+      const total = accumulator.numericSum;
+      if (Math.abs(value * 2 - total) <= Math.max(1e-6, Math.abs(total) * 1e-9)) totalColumns.push(name);
+    }
+    const signals = [];
+    if (candidate.labelColumn !== void 0) signals.push("total_label");
+    if (totalColumns.length > 0) signals.push("column_total");
+    if (signals.length === 0) continue;
+    confirmed.push({
+      row: candidate.row,
+      signals,
+      ...candidate.labelColumn !== void 0 ? { label_column: candidate.labelColumn } : {},
+      ...totalColumns.length > 0 ? { total_columns: totalColumns } : {}
+    });
+  }
+  return confirmed;
+}
+function summaryRowWarning(rows, truncated) {
+  const shown = rows.slice(0, SUMMARY_ROW_WARNING_LIMIT).map((entry) => entry.row);
+  const remaining = rows.length - shown.length;
+  const labelled = rows.filter((entry) => entry.signals.includes("total_label")).length;
+  const totals = rows.filter((entry) => entry.signals.includes("column_total")).length;
+  const reasons = [
+    labelled > 0 ? `${labelled} carry a total-like label (\u5408\u8BA1 / \u603B\u8BA1 / \u5C0F\u8BA1 / \u6C47\u603B / Total / Subtotal)` : void 0,
+    totals > 0 ? `${totals} hold a number equal to the total of its column's other rows` : void 0
+  ].filter((reason) => reason !== void 0).join("; ");
+  const scope = truncated ? ` The scan stopped after ${SUMMARY_ROW_CANDIDATE_LIMIT} candidate rows, so there may be more.` : "";
+  return `${rows.length} row(s) read as a summary line rather than an observation: ${reasons}. Rows ${shown.join(", ")}${remaining > 0 ? ` and ${remaining} more` : ""} (data-row ordinals, the numbering invalid.rows.jsonl and --salvage-from use; see summary_rows).${scope} Nothing was removed and nothing changed: convert writes these rows as records, and every number reported for their columns counts them, so a real total row makes that column's sum twice its actual total and its max the total. There is no flag that drops a data row; when the user confirms a row is a total, remove it from the source file or re-export without it, then inspect again.`;
+}
+function resolveDuplicateKeyColumns(names, explicit) {
+  if (explicit && explicit.length > 0) {
+    const unique = [...new Set(explicit.filter((name) => name.length > 0))];
+    return unique.length > 1 ? unique : void 0;
+  }
+  const identity = names.find((name) => matchesName(name, ACCOUNT_NAMES)) ?? names.find((name) => matchesName(name, DISTINCT_NAMES));
+  const time = names.find((name) => matchesName(name, TIME_NAMES));
+  if (!identity || !time) return void 0;
+  const event = names.find((name) => matchesName(name, EVENT_NAMES));
+  return event ? [identity, time, event] : [identity, time];
+}
+function createDuplicateKeyTracker(columns) {
+  return { columns, firstRow: /* @__PURE__ */ new Map(), groups: /* @__PURE__ */ new Map(), checkedRows: 0, overflow: false };
+}
+function recordDuplicateKey(tracker, row, rowNumber) {
+  const parts = [];
+  for (const name of tracker.columns) {
+    const value = row[name];
+    if (isMissing2(value)) return;
+    parts.push(sampleText(value).trim());
+  }
+  tracker.checkedRows += 1;
+  const hash = createHash2("sha256").update(JSON.stringify(parts)).digest("hex");
+  const group = tracker.groups.get(hash);
+  if (group) {
+    group.count += 1;
+    if (group.rows.length < DUPLICATE_GROUP_ROW_LIMIT) group.rows.push(rowNumber);
+    else group.rowsTruncated = true;
+    return;
+  }
+  const firstRow = tracker.firstRow.get(hash);
+  if (firstRow !== void 0) {
+    tracker.groups.set(hash, { count: 2, rows: [firstRow, rowNumber], rowsTruncated: false });
+    return;
+  }
+  if (tracker.firstRow.size >= DUPLICATE_KEY_TRACK_LIMIT) {
+    tracker.overflow = true;
+    return;
+  }
+  tracker.firstRow.set(hash, rowNumber);
+}
+function buildDuplicateKeyReport(tracker) {
+  if (tracker.groups.size === 0) return void 0;
+  const ordered = [...tracker.groups.entries()].sort(([, left], [, right]) => right.count - left.count || left.rows[0] - right.rows[0]);
+  let extraRows = 0;
+  for (const [, group] of ordered) extraRows += group.count - 1;
+  const groups = ordered.slice(0, DUPLICATE_GROUP_LIMIT).map(([hash, group]) => ({
+    key_hash: hash.slice(0, 16),
+    count: group.count,
+    rows: group.rows,
+    ...group.rowsTruncated ? { rows_truncated: true } : {}
+  }));
+  return {
+    key_columns: tracker.columns,
+    checked_rows: tracker.checkedRows,
+    duplicate_groups: ordered.length,
+    extra_rows: extraRows,
+    groups,
+    ...ordered.length > DUPLICATE_GROUP_LIMIT ? { groups_truncated: true } : {},
+    ...tracker.overflow ? { tracking_truncated: true } : {}
+  };
+}
+function duplicateKeyWarning(report) {
+  const examples = report.groups.slice(0, DUPLICATE_WARNING_GROUP_LIMIT).map((group) => `rows ${group.rows.join(", ")}${group.rows_truncated ? ", \u2026" : ""} (${group.count}\xD7)`).join("; ");
+  const remaining = report.duplicate_groups - Math.min(report.groups.length, DUPLICATE_WARNING_GROUP_LIMIT);
+  const scope = report.tracking_truncated ? ` Tracking stopped after ${DUPLICATE_KEY_TRACK_LIMIT} distinct keys, so there may be more.` : "";
+  return `${report.duplicate_groups} business key(s) appear on more than one row, ${report.extra_rows} extra row(s) in total, over ${report.checked_rows} row(s) that carried a value in every key column. Key: ${report.key_columns.join(" + ")}. Examples: ${examples}${remaining > 0 ? ` and ${remaining} more group(s)` : ""} (data-row ordinals, the numbering invalid.rows.jsonl and --salvage-from use; see duplicate_keys).${scope} Nothing was removed: repeated rows are sometimes real (one order line per product), and AE appends every accepted event with no way to un-send it, so this has to be settled before upload. Ask the user whether the repeats are separate observations; if they are not, remove them from the source file and inspect again. Values are compared as written, so two spellings of the same instant are two different keys, and a source with a unique key of its own (an order id) is not compared on it unless the mapping names it.`;
+}
 function truncateSample2(value) {
   const text = sampleText(value);
   if (text.length <= SAMPLE_TRUNCATE_LENGTH) return text;
@@ -2239,9 +2946,21 @@ var dataIntegrationInspect = {
     { name: "data-set", type: "string", sensitive: true, desc: "Sheet or JSON Path ID returned by a discovery-only inspection." },
     { name: "source-timezone", type: "string", default: "Asia/Shanghai", desc: "IANA timezone used to interpret source times without an offset." },
     { name: "headers", type: "string", sensitive: true, desc: "Comma-separated explicit column names for a headerless file; the first row is data." },
-    { name: "headerless", type: "boolean", default: false, desc: "Treat the first row as data and auto-generate col_1..col_N names." }
+    { name: "headerless", type: "boolean", default: false, desc: "Treat the first row as data and auto-generate col_1..col_N names." },
+    { name: "skip-rows", type: "number", default: 0, desc: "Discard the first N rows before the header row is read, for exports with a title or banner above the header. Delimited and Excel only." },
+    { name: "fill-merged-cells", type: "boolean", default: false, desc: "Copy each merged block value into the cells its own range covers, so rows below the first row of a merged block keep the value Excel displays. XLSX only; off by default because those cells are empty in the file." },
+    { name: "exclude-hidden-rows", type: "boolean", default: false, desc: "Leave rows hidden in the source worksheet out of the profile. XLSX only; off by default because a hidden row may still be real data." }
   ],
   risk: "read",
+  validate: (ctx) => {
+    const skipRows = ctx.num("skip-rows");
+    if (!Number.isInteger(skipRows) || skipRows < 0) {
+      throw new CliValidationError("Skipped rows must be a non-negative integer.", {
+        code: "LOCAL_DATA_SKIP_ROWS_INVALID",
+        location: { field: "skip-rows" }
+      });
+    }
+  },
   // Fast size/time pre-check (stat + format/encoding sniff only — no sha256, no profile).
   // Lets agents surface the estimate before committing to a multi-minute full inspection.
   dryRun: async (ctx) => {
@@ -2272,46 +2991,69 @@ var dataIntegrationInspect = {
     const noHeader = ctx.bool("headerless");
     const sourceTimezone = ctx.str("source-timezone");
     const requested = ctx.str("data-set").trim() || void 0;
+    const skipRows = ctx.num("skip-rows");
+    const fillMergedCells = ctx.bool("fill-merged-cells");
+    const excludeHiddenRows = ctx.bool("exclude-hidden-rows");
     if (inputFiles.length === 1) {
       const input = await inspectLocalDataInput(inputFiles[0]);
       const headerConsistency = await readExcelHeaderConsistency(input);
+      const excludedSheets = summarizeExcludedSheets(input);
       if (!requested && input.dataSets.length > 1) {
         return {
           version: "ae-local-data-profile/v1",
           selection_required: true,
           source: { format: input.format, size_bytes: input.sizeBytes, sha256: input.sha256 },
           data_sets: input.dataSets,
+          ...excludedSheets,
           ...headerConsistency ?? {},
           next_step: "Run inspect again with --data-set, then review the recommended mapping."
         };
       }
       const dataSet = selectDataSet(input, requested);
-      const headerPresence = headerNames || noHeader ? void 0 : detectHeaderPresence(input);
+      const headerPresence = headerNames || noHeader ? void 0 : detectHeaderPresence(input, skipRows);
+      const headerSignal = headerNames || noHeader ? void 0 : await detectHeaderSignal(input, dataSet, skipRows);
       const profile = await profileLocalData(input, dataSet, sourceTimezone, {
         collectSamples: true,
         collectNestedTree: true,
         headerNames,
-        noHeader: noHeader || Boolean(headerPresence)
+        noHeader: noHeader || Boolean(headerPresence),
+        skipRows,
+        fillMergedCells,
+        excludeHiddenRows
       });
       const annotated = headerPresence ? annotateHeaderless(profile, headerPresence) : profile;
-      return headerConsistency ? { ...annotated, ...headerConsistency } : annotated;
+      return {
+        ...annotated,
+        ...excludedSheets,
+        ...headerConsistency ?? {},
+        ...annotateRowSkips(annotated.warnings, skipRows, headerSignal)
+      };
     }
     const files = [];
     for (const inputFile of inputFiles) {
       const input = await inspectLocalDataInput(inputFile);
       const dataSet = selectDataSet(input);
-      const headerPresence = headerNames || noHeader ? void 0 : detectHeaderPresence(input);
+      const headerPresence = headerNames || noHeader ? void 0 : detectHeaderPresence(input, skipRows);
+      const headerSignal = headerNames || noHeader ? void 0 : await detectHeaderSignal(input, dataSet, skipRows);
       const profile = await profileLocalData(input, dataSet, sourceTimezone, {
         collectSamples: true,
         collectNestedTree: true,
         headerNames,
-        noHeader: noHeader || Boolean(headerPresence)
+        noHeader: noHeader || Boolean(headerPresence),
+        skipRows,
+        fillMergedCells,
+        excludeHiddenRows
       });
       const annotated = headerPresence ? annotateHeaderless(profile, headerPresence) : profile;
       const headerConsistency = await readExcelHeaderConsistency(input);
       files.push({
         file: basename3(inputFile),
-        profile: headerConsistency ? { ...annotated, ...headerConsistency } : annotated
+        profile: {
+          ...annotated,
+          ...summarizeExcludedSheets(input),
+          ...headerConsistency ?? {},
+          ...annotateRowSkips(annotated.warnings, skipRows, headerSignal)
+        }
       });
     }
     return {
@@ -2322,6 +3064,13 @@ var dataIntegrationInspect = {
     };
   }
 };
+function summarizeExcludedSheets(input) {
+  const excluded = input.excludedDataSets ?? [];
+  if (excluded.length === 0) return {};
+  return {
+    excluded_sheets: excluded.map((dataSet) => ({ name: dataSet.label, reason: "hidden", data_set: dataSet.id }))
+  };
+}
 async function readExcelHeaderConsistency(input) {
   if (input.format !== "xls" && input.format !== "xlsx") return void 0;
   return summarizeHeaderConsistency(await readExcelSheetHeaders(input.filePath, input.format));
@@ -2332,10 +3081,11 @@ function summarizeHeaderConsistency(sheets) {
   const allSame = sheets.every((sheet) => JSON.stringify(sheet.headers) === first);
   return allSame ? { header_consistency: "all_same" } : { header_consistency: "different", header_details: sheets.map((sheet) => ({ name: sheet.name, headers: sheet.headers })) };
 }
-function detectHeaderPresence(input) {
+function detectHeaderPresence(input, skipRows = 0) {
   if (input.format !== "csv" && input.format !== "tsv") return void 0;
   const delimiter = input.delimiter ?? (input.format === "tsv" ? "	" : ",");
-  const records = peekDelimitedRecords(input.filePath, { delimiter, encoding: input.encoding, limit: 10 });
+  const peeked = peekDelimitedRecords(input.filePath, { delimiter, encoding: input.encoding, limit: 10 + skipRows });
+  const records = peeked.slice(skipRows);
   const detection = detectHeaderRow(records);
   if (detection.hasHeaders) return void 0;
   return {
@@ -2343,6 +3093,41 @@ function detectHeaderPresence(input) {
     autoHeaders: (records[0] ?? []).map((_, index) => `col_${index + 1}`)
   };
 }
+async function detectHeaderSignal(input, dataSet, skipRows) {
+  const rows = await peekHeaderRows(input, dataSet, skipRows);
+  if (!rows || rows.length === 0) return void 0;
+  const titleRows = detectLeadingTitleRows(rows).map((title) => ({ ...title, row: title.row + skipRows }));
+  if (input.format !== "xlsx") return titleRows.length > 0 ? { titleRows } : void 0;
+  const detection = detectHeaderRow(rows.map((row) => row.map((value) => isEmptyCell(value) ? "" : String(value))));
+  if (detection.hasHeaders && titleRows.length === 0) return void 0;
+  return { ...detection.hasHeaders ? {} : { detection }, titleRows };
+}
+async function peekHeaderRows(input, dataSet, skipRows) {
+  if (input.format === "csv" || input.format === "tsv") {
+    const delimiter = input.delimiter ?? (input.format === "tsv" ? "	" : ",");
+    return peekDelimitedRecords(input.filePath, { delimiter, encoding: input.encoding, limit: 10 + skipRows }).slice(skipRows);
+  }
+  if (input.format === "xlsx" && dataSet.kind === "sheet") {
+    return (await peekXlsxRows(input.filePath, dataSet.label, 10 + skipRows)).slice(skipRows);
+  }
+  return void 0;
+}
+function isEmptyCell(value) {
+  return value === null || value === void 0 || value === "";
+}
+var TITLE_ROW_WARNING = "The first rows here hold a single value each, which looks like a title or banner above the real header row; the header was still read from the first row. See leading_title_rows and re-run with --skip-rows N if that is what they are.";
+var EXCEL_HEADERLESS_WARNING = "The first row of this worksheet looks like data rather than a header, but it was still used as the header. See header_signal, and re-run with --headers or --headerless if it is data.";
+function annotateRowSkips(warnings, skipRows, signal) {
+  const extra = [];
+  if (signal?.titleRows.length) extra.push(TITLE_ROW_WARNING);
+  if (signal?.detection) extra.push(EXCEL_HEADERLESS_WARNING);
+  return {
+    warnings: extra.length > 0 ? [...warnings, ...extra] : warnings,
+    ...skipRows > 0 ? { skipped_rows: skipRows } : {},
+    ...signal?.titleRows.length ? { leading_title_rows: signal.titleRows } : {},
+    ...signal?.detection ? { header_signal: signal.detection } : {}
+  };
+}
 function annotateHeaderless(profile, presence) {
   return {
     ...profile,
@@ -2362,7 +3147,7 @@ function splitHeaders(raw) {
 // src/commands/data-integration/plan.ts
 import { writeFile } from "fs/promises";
 var VALID_LOCALES = /* @__PURE__ */ new Set(["zh", "en", "ja", "ko"]);
-var EVENT_NAME_RE = /^[a-z][a-z0-9_]*$/;
+var EVENT_NAME_RE = /^[A-Za-z][A-Za-z0-9_]*$/;
 function toPropType(type) {
   switch (type) {
     case "number":
@@ -2439,7 +3224,7 @@ function resolveEventNames(options) {
       if (!EVENT_NAME_RE.test(name)) {
         throw new CliValidationError(`The event name "${name}" is not a legal AE event name.`, {
           code: "LOCAL_DATA_PLAN_INVALID_EVENT_NAME",
-          hint: "Event names must match ^[a-z][a-z0-9_]*$.",
+          hint: "Event names must match ^[A-Za-z][A-Za-z0-9_]*$.",
           location: { field: "event-name" }
         });
       }
@@ -2567,11 +3352,24 @@ async function convertLocalData(options) {
   const dataSet = options.mergeSheets ? { id: "all-sheets", kind: "sheet", label: "all-sheets", selector: "all-sheets" } : selectDataSet(input, options.mapping.source.data_set);
   const streamOptions = {
     headerNames: options.mapping.headers,
+    skipRows: options.mapping.skip_rows,
     flattenRules: options.mapping.flatten_rules,
     mergeSheets: options.mergeSheets,
+    // Both XLSX layout decisions come from the mapping, so the rows converted here are the rows
+    // inspect profiled — the mapping is the only place the user's answer to them is recorded.
+    fillMergedCells: options.mapping.fill_merged_cells,
+    excludeHiddenRows: options.mapping.exclude_hidden_rows,
     // The profile pass inside convert is internal (it writes profile.json); the ragged-row
     // warning is surfaced by the conversion pass below instead, so suppress it here.
-    warnRagged: false
+    warnRagged: false,
+    // The mapping's own columns are the key worth checking for repeats: they are what AE will
+    // receive as identity, time, and event name. A file-wide `default_event_name` is the same on
+    // every row, so it distinguishes nothing and is left out.
+    duplicateKeyFields: [
+      options.mapping.account_id_field ?? options.mapping.distinct_id_field,
+      options.mapping.time.field,
+      options.mapping.event_name_field
+    ].filter((field) => typeof field === "string" && field.length > 0)
   };
   const salvageSet = options.salvageFrom ? readSalvageRowNumbers(options.salvageFrom) : void 0;
   let salvageMatched = 0;
@@ -2596,6 +3394,8 @@ async function convertLocalData(options) {
   const skippedFields = {};
   let lanIpRecords = 0;
   const flattenMisses = {};
+  const cellIssues = /* @__PURE__ */ new Map();
+  const xlsxStructure = input.format === "xlsx" ? createXlsxStructureCollector() : void 0;
   const rowCount = await streamLocalDataRows(
     input,
     dataSet,
@@ -2624,9 +3424,14 @@ async function convertLocalData(options) {
     },
     {
       headerNames: streamOptions.headerNames,
+      skipRows: streamOptions.skipRows,
       flattenRules: streamOptions.flattenRules,
       flattenMisses,
-      mergeSheets: streamOptions.mergeSheets
+      cellIssues,
+      mergeSheets: streamOptions.mergeSheets,
+      fillMergedCells: streamOptions.fillMergedCells,
+      excludeHiddenRows: streamOptions.excludeHiddenRows,
+      xlsxStructure
     }
   );
   if (userSetBuffer.length > 0) flushSortChunk(outputDir, userSetBuffer, sortChunks);
@@ -2635,6 +3440,17 @@ async function convertLocalData(options) {
     process.stderr.write(`Warning: flatten rule "${outColumn}" did not materialize for ${count} row(s).
 `);
   }
+  for (const warning of cellIssueWarnings(cellIssues)) {
+    process.stderr.write(`Warning: ${warning}
+`);
+  }
+  if (xlsxStructure) {
+    for (const warning of xlsxStructureWarnings(xlsxStructure, options.mapping.exclude_columns)) {
+      process.stderr.write(`Warning: ${warning}
+`);
+    }
+  }
+  const structureReport = xlsxStructure ? xlsxStructureReport(xlsxStructure) : void 0;
   if (salvageSet && salvageMatched === 0) {
     throw new CliValidationError("The salvage file lists no rows from this source.", {
       code: "LOCAL_DATA_SALVAGE_NO_MATCH",
@@ -2656,6 +3472,7 @@ async function convertLocalData(options) {
   writeSecureJson(mappingPath, options.mapping);
   writeSecureText(transformPath, createTransformScript(options.inputFile, mappingPath));
   const validBytes = statSize(validPath);
+  const sourceRows = salvageSet ? salvageMatched : rowCount;
   const blockedReasons = [
     ...rowCount === 0 ? ["The source contained no data rows."] : [],
     ...rowCount > 0 && validRecords === 0 ? ["No valid UE records were generated."] : [],
@@ -2677,13 +3494,18 @@ async function convertLocalData(options) {
       valid_file: basename4(validPath),
       valid_sha256: await sha256File(validPath),
       invalid_file: basename4(invalidPath),
+      source_rows: sourceRows,
       valid_records: validRecords,
       invalid_records: invalidRecords,
       valid_bytes: validBytes,
       record_types: recordTypes,
       ...Object.keys(skippedFields).length > 0 ? { skipped_fields: skippedFields } : {},
       ...lanIpRecords > 0 ? { lan_ip_records: lanIpRecords } : {},
-      ...Object.keys(flattenMisses).length > 0 ? { flatten_misses: flattenMisses } : {}
+      ...Object.keys(flattenMisses).length > 0 ? { flatten_misses: flattenMisses } : {},
+      ...cellIssues.size > 0 ? { unreadable_cells: cellIssueCounts(cellIssues) } : {},
+      ...structureReport ? { xlsx_structure: structureReport } : {},
+      ...profile.summary_rows ? { summary_rows: profile.summary_rows } : {},
+      ...profile.duplicate_keys ? { duplicate_keys: profile.duplicate_keys } : {}
     },
     blocked_reasons: blockedReasons
   };
@@ -2701,6 +3523,7 @@ async function convertLocalDataMulti(options) {
     const profile = await profileLocalData(input, dataSet, sourceTimezone, {
       collectSamples: true,
       headerNames: options.mapping.headers,
+      skipRows: options.mapping.skip_rows,
       flattenRules: options.mapping.flatten_rules,
       warnRagged: false
     });
@@ -2772,7 +3595,7 @@ function convertRow(row, rowNumber, mapping, now) {
   if (recordType === "track") {
     const rawEvent = String(stripQuotes(mapping.event_name_field ? row[mapping.event_name_field] ?? "" : mapping.default_event_name ?? ""));
     eventName = mapping.value_mapping?.event_name && mapping.value_mapping.event_name[rawEvent] !== void 0 ? mapping.value_mapping.event_name[rawEvent] : rawEvent;
-    if (!isValidAeName(eventName)) {
+    if (!isValidEventName(eventName)) {
       errors.push({ code: "INVALID_EVENT_NAME", field: mapping.event_name_field });
     }
   }