@thinkingai/ae-cli 6.1.17 → 6.1.19

package/dist/{data-integration-XQYB4X4F.js → data-integration-4NZGZ45E.js}

@@ -1,13 +1,27 @@
+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-QL6R6TSK.js";
+import "./chunk-B5HMQAOM.js";
+import {
+  getConfigDir
+} from "./chunk-KZ6ZHF5J.js";
 import {
   CliValidationError,
   LocalDataUploadError
-} from "./chunk-UW5UN47B.js";
-import "./chunk-QGM4M3NI.js";
+} from "./chunk-533JK3YX.js";
+import {
+  __toESM
+} from "./chunk-FR2EDAQM.js";
 
-// src/commands/data-integration/local-data/inspect.ts
+// src/commands/data-integration/inspect.ts
 import { basename as basename3 } from "path";
 
-// src/commands/data-integration/local-data/estimate.ts
+// src/commands/data-integration/estimate.ts
 var XLS_SIZE_WARN_BYTES = 100 * 1024 * 1024;
 var LARGE_FILE_WARN_BYTES = 1024 * 1024 * 1024;
 var XLS_HARD_LIMIT_BYTES = 1024 * 1024 * 1024;
@@ -95,12 +109,15 @@ function assessFileSize(fileName, format, sizeBytes, encoding) {
   return baseAssessment;
 }
 
-// src/commands/data-integration/local-data/input.ts
+// 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";
@@ -112,7 +129,7 @@ import StreamValues from "stream-json/streamers/StreamValues.js";
 import * as unzipper from "unzipper";
 import { SaxesParser } from "saxes";
 
-// src/commands/data-integration/local-data/encoding.ts
+// src/commands/data-integration/encoding.ts
 import { createReadStream } from "fs";
 import { createRequire } from "module";
 import { openSync, readSync, closeSync } from "fs";
@@ -156,7 +173,7 @@ function readSample(filePath, maxBytes) {
   }
 }
 
-// src/commands/data-integration/local-data/time.ts
+// src/commands/data-integration/time.ts
 var TIME_FORMATS = [
   // Standard AE format
   "yyyy-MM-dd HH:mm:ss.SSS",
@@ -400,7 +417,7 @@ function tokenizeFormat(format) {
   return tokens;
 }
 
-// src/commands/data-integration/local-data/flatten.ts
+// src/commands/data-integration/flatten.ts
 var NDJSON_MAX_DEPTH = 1;
 var NESTED_NODE_SAMPLE_LIMIT = 5;
 var NESTED_SAMPLE_TRUNCATE = 40;
@@ -433,7 +450,7 @@ function flattenJSON(obj, prefix = "", depth = 0, maxDepth = NDJSON_MAX_DEPTH) {
   }
   return result;
 }
-function buildRowWithFlatten(obj, flattenRules) {
+function buildRowWithFlatten(obj, flattenRules, misses) {
   const row = {};
   const coveredRoots = new Set(Object.values(flattenRules).map((path) => path.split(".")[0]));
   const base = flattenJSON(obj);
@@ -442,43 +459,77 @@ function buildRowWithFlatten(obj, flattenRules) {
   }
   for (const [outColumn, sourcePath] of Object.entries(flattenRules)) {
     const value = getNestedValue(obj, sourcePath);
-    row[outColumn] = value == null ? "" : typeof value === "object" ? JSON.stringify(value) : String(value);
+    if (value == null) {
+      recordFlattenMiss(misses, outColumn);
+      row[outColumn] = "";
+    } else {
+      row[outColumn] = typeof value === "object" ? JSON.stringify(value) : String(value);
+    }
   }
   return row;
 }
-function flattenLocalDataRow(value, flattenRules) {
+function flattenLocalDataRow(value, flattenRules, misses) {
   if (value !== null && typeof value === "object" && !Array.isArray(value)) {
     if (flattenRules && Object.keys(flattenRules).length > 0) {
-      return buildRowWithFlatten(value, flattenRules);
+      return buildRowWithFlatten(value, flattenRules, misses);
     }
     return value;
   }
   return { value };
 }
-function flattenDelimitedRow(row, flattenRules) {
+function flattenDelimitedRow(row, flattenRules, misses) {
   const result = { ...row };
   for (const [outColumn, path] of Object.entries(flattenRules)) {
     const dot = path.indexOf(".");
-    if (dot <= 0) continue;
+    if (dot <= 0) {
+      recordFlattenMiss(misses, outColumn);
+      continue;
+    }
     const column = path.slice(0, dot);
     const cell = row[column];
-    if (typeof cell !== "string") continue;
+    if (typeof cell !== "string") {
+      recordFlattenMiss(misses, outColumn);
+      continue;
+    }
     let parsed;
     try {
       parsed = JSON.parse(cell);
     } catch {
+      recordFlattenMiss(misses, outColumn);
       continue;
     }
     const value = getNestedValue(parsed, path.slice(dot + 1));
-    if (value === null || value === void 0) continue;
+    if (value === null || value === void 0) {
+      recordFlattenMiss(misses, outColumn);
+      continue;
+    }
     result[outColumn] = typeof value === "object" ? JSON.stringify(value) : String(value);
   }
   return result;
 }
+function recordFlattenMiss(misses, outColumn) {
+  if (!misses) return;
+  misses[outColumn] = (misses[outColumn] ?? 0) + 1;
+}
 function buildNestedTree(rows) {
   const objects = rows.filter((row) => row !== null && typeof row === "object" && !Array.isArray(row));
   return buildObjectChildren(objects, "");
 }
+function buildColumnNestedTree(cells) {
+  const objects = cells.filter((cell) => cell !== null && typeof cell === "object" && !Array.isArray(cell));
+  const arrays = cells.filter(Array.isArray);
+  if (objects.length >= arrays.length) {
+    return objects.length > 0 ? buildObjectChildren(objects, "") : [];
+  }
+  const elements = arrays.flat();
+  const elementObjects = elements.filter(
+    (value) => value !== null && typeof value === "object" && !Array.isArray(value)
+  );
+  const elementKind = elementObjects.length > 0 ? "object" : "primitive";
+  const node = { path: "", name: "", kind: "array", elementKind, nonEmpty: elements.length > 0 };
+  if (elementKind === "object") node.children = buildObjectChildren(elementObjects, "");
+  return [node];
+}
 function buildObjectChildren(objects, parentPath) {
   const keys = [];
   const seen = /* @__PURE__ */ new Set();
@@ -504,8 +555,18 @@ function buildNode(path, name, values, nonEmpty) {
   if (structural > 0 && structural >= values.length - structural) {
     if (arrays.length > objects.length) {
       const elementValues = arrays.flat();
-      const elementKind = elementValues.some((value) => value !== null && typeof value === "object") ? "object" : "primitive";
-      return { path, name, kind: "array", elementKind, nonEmpty };
+      const elementObjects = elementValues.filter(
+        (value) => value !== null && typeof value === "object" && !Array.isArray(value)
+      );
+      const elementKind = elementObjects.length > 0 ? "object" : "primitive";
+      return {
+        path,
+        name,
+        kind: "array",
+        elementKind,
+        nonEmpty,
+        ...elementKind === "object" ? { children: buildObjectChildren(elementObjects, path) } : {}
+      };
     }
     return { path, name, kind: "object", children: buildObjectChildren(objects, path), nonEmpty };
   }
@@ -573,10 +634,8 @@ function isStrongDateTime(value) {
   return /^\d{4}[-/]\d{1,2}[-/]\d{1,2}(?:[ T]\d{1,2}:\d{2}(?::\d{2}(?:\.\d{1,3})?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/.test(value.trim());
 }
 
-// src/commands/data-integration/local-data/input.ts
+// 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;
@@ -613,10 +672,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;
@@ -639,15 +700,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.", {
@@ -658,6 +732,24 @@ function selectDataSet(input, requested) {
   }
   return input.dataSets[0];
 }
+var LocalDataRowCallbackError = class extends Error {
+  constructor(cause) {
+    super(cause instanceof Error ? cause.message : String(cause));
+    this.cause = cause;
+    this.name = "LocalDataRowCallbackError";
+  }
+  cause;
+};
+function wrapRowCallback(onRow) {
+  return async (row, rowNumber) => {
+    try {
+      await onRow(row, rowNumber);
+    } catch (error) {
+      if (error instanceof CliValidationError) throw error;
+      throw new LocalDataRowCallbackError(error);
+    }
+  };
+}
 async function streamLocalDataRows(input, dataSet, onRow, options = {}) {
   const opts = {
     delimiter: options.delimiter ?? input.delimiter ?? (input.format === "tsv" ? "	" : ","),
@@ -665,24 +757,36 @@ async function streamLocalDataRows(input, dataSet, onRow, options = {}) {
     headerNames: options.headerNames,
     noHeader: options.noHeader,
     flattenRules: options.flattenRules,
-    mergeSheets: options.mergeSheets
+    flattenMisses: options.flattenMisses,
+    mergeSheets: options.mergeSheets,
+    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 {
     switch (input.format) {
       case "csv":
       case "tsv":
-        return await streamDelimited(input.filePath, onRow, opts);
+        return await streamDelimited(input.filePath, wrappedRow, opts);
       case "jsonl":
-        return await streamJsonLines(input.filePath, onRow, opts);
+        return await streamJsonLines(input.filePath, wrappedRow, opts);
       case "json":
-        return await streamJson(input.filePath, dataSet.selector ?? "$", onRow, opts);
+        return await streamJson(input.filePath, dataSet.selector ?? "$", wrappedRow, opts);
       case "xlsx":
-        return await streamXlsx(input.filePath, dataSet.label, onRow, opts);
+        return await streamXlsx(input.filePath, dataSet.label, wrappedRow, opts);
       case "xls":
-        return await streamXls(input.filePath, dataSet.label, onRow, opts);
+        return await streamXls(input.filePath, dataSet.label, wrappedRow, opts);
     }
   } catch (error) {
     if (error instanceof CliValidationError) throw error;
+    if (error instanceof LocalDataRowCallbackError) {
+      throw error.cause instanceof Error ? error.cause : error;
+    }
     throw localDataParseError(input.format);
   }
 }
@@ -789,6 +893,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, "\\$&");
 }
@@ -799,21 +918,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);
@@ -859,9 +986,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({
@@ -870,29 +999,41 @@ async function streamDelimited(filePath, onRow, options) {
     quote: delimiter === "	" ? null : '"',
     relax_column_count: true,
     skip_empty_lines: true,
-    trim: true,
-    columns: headerNames ? headerNames : (headers) => dedupeHeaders(headers.map((header) => String(header).trim()))
+    trim: true
   });
   decodeTextStream(filePath, encoding).pipe(parser);
   let count = 0;
-  for await (const value of parser) {
+  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;
+    }
+    if (values.length !== resolvedHeaders.length) widthMismatches += 1;
     count += 1;
-    const row = normalizeDelimitedRow(value, headerNames);
+    const row = {};
+    for (let index = 0; index < resolvedHeaders.length; index += 1) {
+      row[resolvedHeaders[index]] = values[index] ?? null;
+    }
     await onRow(
-      options.flattenRules && Object.keys(options.flattenRules).length > 0 ? flattenDelimitedRow(row, options.flattenRules) : row,
+      options.flattenRules && Object.keys(options.flattenRules).length > 0 ? flattenDelimitedRow(row, options.flattenRules, options.flattenMisses) : row,
       count
     );
   }
-  return count;
-}
-function normalizeDelimitedRow(value, headerNames) {
-  if (!headerNames || value === null || typeof value !== "object" || Array.isArray(value)) {
-    return normalizeRow(value);
+  if (widthMismatches > 0 && options.warnRagged !== false) {
+    process.stderr.write(
+      `Warning: ${widthMismatches} record(s) had a column count different from the header row; extra fields were dropped and missing fields were treated as empty.
+`
+    );
   }
-  const source = value;
-  const row = {};
-  for (const header of headerNames) row[header] = source[header] ?? null;
-  return row;
+  return count;
 }
 async function streamJsonLines(filePath, onRow, options) {
   let count = 0;
@@ -909,7 +1050,7 @@ async function streamJsonLines(filePath, onRow, options) {
         location: { record: count }
       });
     }
-    await onRow(flattenLocalDataRow(value, options.flattenRules), count);
+    await onRow(flattenLocalDataRow(value, options.flattenRules, options.flattenMisses), count);
   }
   return count;
 }
@@ -921,19 +1062,28 @@ async function streamJson(filePath, selector, onRow, options) {
   const chain = selector === "$" || selector === "$object" ? source.pipe(parser).pipe(streamer) : source.pipe(parser).pipe(Pick.pick({ filter: selector })).pipe(streamer);
   for await (const item of chain) {
     count += 1;
-    await onRow(flattenLocalDataRow(item.value, options.flattenRules), count);
+    await onRow(flattenLocalDataRow(item.value, options.flattenRules, options.flattenMisses), count);
   }
   return count;
 }
 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);
@@ -943,19 +1093,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}`);
       }
@@ -964,8 +1132,49 @@ 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;
-      await onRow(Object.fromEntries(headers.map((header, index) => [header, values[index] ?? null])), count);
+      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,
+        count
+      );
     }
   }
   return count;
@@ -980,28 +1189,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",
@@ -1024,25 +1234,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;
     }
@@ -1053,13 +1259,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 = "";
     }
@@ -1068,26 +1343,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, "&");
@@ -1099,10 +1495,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;
@@ -1117,27 +1515,136 @@ async function streamXls(filePath, sheetName, onRow, options) {
     for (const values of rows.slice(start)) {
       if (values.every(isMissing)) continue;
       count += 1;
-      await onRow(Object.fromEntries(headers.map((header, index) => [header, values[index] ?? null])), count);
+      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,
+        count
+      );
     }
   }
   return count;
 }
-function normalizeRow(value) {
-  if (value !== null && typeof value === "object" && !Array.isArray(value)) {
-    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 { value };
+  return warnings;
 }
-function normalizeExcelValue(value) {
-  if (value instanceof Date) return value;
+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();
@@ -1170,9 +1677,19 @@ async function firstNonWhitespaceCharacter(filePath, encoding) {
   return void 0;
 }
 
-// src/commands/data-integration/local-data/mapping.ts
+// src/commands/data-integration/mapping.ts
 import { readFileSync } from "fs";
+
+// src/commands/data-integration/types.ts
+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 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;
@@ -1202,8 +1719,8 @@ function readLocalDataMapping(raw, options) {
   return value;
 }
 function validateMapping(value, options) {
-  if (!isRecord(value) || value.version !== "ae-local-data-mapping/v1") {
-    throw mappingError("Mapping version must be ae-local-data-mapping/v1.");
+  if (!isRecord(value) || value.version !== MAPPING_VERSION) {
+    throw mappingError(`Mapping version must be ${MAPPING_VERSION}.`);
   }
   const sha256Valid = typeof value.source?.sha256 === "string" && (options?.sourceWildcard ? value.source.sha256 === "*" || /^[a-f0-9]{64}$/i.test(value.source.sha256) : /^[a-f0-9]{64}$/i.test(value.source.sha256));
   if (!isRecord(value.source) || !sha256Valid || !["csv", "tsv", "json", "jsonl", "xls", "xlsx"].includes(String(value.source.format)) || typeof value.source.data_set !== "string" || !value.source.data_set) {
@@ -1233,12 +1750,28 @@ function validateMapping(value, options) {
   }
   if (!Array.isArray(value.properties)) throw mappingError("Mapping properties must be an array.");
   const targets = /* @__PURE__ */ new Set();
+  const propertyTypes = /* @__PURE__ */ new Map();
   for (const property of value.properties) {
-    if (!isRecord(property) || typeof property.source !== "string" || typeof property.target !== "string" || !VALID_PROPERTY_NAME.test(property.target) || !["number", "string", "boolean", "datetime", "list", "object"].includes(String(property.type)) || property.transform !== void 0 && !["stringify", "number", "boolean", "json"].includes(String(property.transform)) || property.value_mapping !== void 0 && !isStringMap(property.value_mapping) || property.time_format !== void 0 && (typeof property.time_format !== "string" || !property.time_format.trim() || property.time_format.length > 64) || property.desc !== void 0 && (typeof property.desc !== "string" || !property.desc.trim() || property.desc.length > 200)) {
+    if (!isRecord(property) || typeof property.source !== "string" || typeof property.target !== "string" || !(VALID_PROPERTY_NAME.test(property.target) || VALID_CHILD_PROPERTY_NAME.test(property.target)) || !["number", "string", "boolean", "datetime", "list", "object", "array_row"].includes(String(property.type)) || property.transform !== void 0 && !["stringify", "number", "boolean", "json"].includes(String(property.transform)) || property.value_mapping !== void 0 && !isStringMap(property.value_mapping) || property.time_format !== void 0 && (typeof property.time_format !== "string" || !property.time_format.trim() || property.time_format.length > 64) || property.desc !== void 0 && (typeof property.desc !== "string" || !property.desc.trim() || property.desc.length > 200)) {
       throw mappingError("Every property mapping needs a source, legal AE target name, and supported type.");
     }
     if (targets.has(property.target)) throw mappingError("Property target names must be unique.");
     targets.add(property.target);
+    propertyTypes.set(property.target, { type: String(property.type), source: property.source });
+  }
+  for (const property of value.properties) {
+    if (!property.target.includes(".")) continue;
+    const parentName = property.target.split(".")[0];
+    const parent = propertyTypes.get(parentName);
+    if (!parent || parent.type !== "object" && parent.type !== "array_row") {
+      throw mappingError(`The sub-property "${property.target}" references "${parentName}", which is not an object/array_row property in this mapping.`);
+    }
+    if (property.type === "object" || property.type === "array_row") {
+      throw mappingError(`The sub-property "${property.target}" must be scalar or list, not ${property.type}.`);
+    }
+    if (property.source !== parent.source) {
+      throw mappingError(`The sub-property "${property.target}" must read from the same source column as its parent "${parentName}".`);
+    }
   }
   if (value.time_format !== void 0 && (typeof value.time_format !== "string" || !value.time_format.trim() || value.time_format.length > 64)) {
     throw mappingError("time_format must be a non-empty string of at most 64 characters.");
@@ -1280,6 +1813,9 @@ function validateMapping(value, options) {
   }
   if (value.flatten_rules !== void 0) {
     if (!isRecord(value.flatten_rules)) throw mappingError("flatten_rules must be an object of { column: dot.path }.");
+    if (!FLATTEN_SUPPORTED_FORMATS.includes(String(value.source.format))) {
+      throw mappingError(`flatten_rules are not supported for ${String(value.source.format)} input.`);
+    }
     for (const [column, path] of Object.entries(value.flatten_rules)) {
       if (!VALID_PROPERTY_NAME.test(column) || typeof path !== "string" || !path.trim()) {
         throw mappingError("flatten_rules keys must be legal AE property names and values must be non-empty dot paths.");
@@ -1289,6 +1825,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.');
   }
@@ -1323,6 +1876,31 @@ function validateMapping(value, options) {
 function isValidAeName(value) {
   return VALID_PROPERTY_NAME.test(value);
 }
+function sourceColumns(mapping) {
+  const columns = /* @__PURE__ */ new Set();
+  const flattenOut = new Set(Object.keys(mapping.flatten_rules ?? {}));
+  for (const property of mapping.properties) {
+    if (!flattenOut.has(property.source)) columns.add(property.source);
+  }
+  for (const path of Object.values(mapping.flatten_rules ?? {})) {
+    const root = path.split(".")[0];
+    if (root) columns.add(root);
+  }
+  const systemFields = [
+    mapping.account_id_field,
+    mapping.distinct_id_field,
+    mapping.record_type_field,
+    mapping.event_name_field,
+    mapping.time.field,
+    mapping.ip_field,
+    mapping.uuid_field,
+    mapping.zone_offset_field
+  ];
+  for (const field of systemFields) if (field) columns.add(field);
+  for (const column of mapping.exclude_columns ?? []) columns.add(column);
+  for (const header of mapping.headers ?? []) columns.add(header);
+  return [...columns].sort();
+}
 function mappingError(message) {
   return new CliValidationError(message, {
     code: "LOCAL_DATA_MAPPING_INVALID",
@@ -1349,7 +1927,7 @@ function isRecord(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
-// src/commands/data-integration/local-data/multi.ts
+// src/commands/data-integration/multi.ts
 var PROPERTY_TYPES = /* @__PURE__ */ new Set([
   "number",
   "string",
@@ -1494,14 +2072,63 @@ function isRecord2(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
-// src/commands/data-integration/local-data/profile.ts
+// src/commands/data-integration/profile.ts
 import { createHash as createHash2, randomInt } from "crypto";
 import { basename as basename2, extname as extname2 } from "path";
+
+// src/commands/data-integration/field-spec.ts
+import { isIP } from "net";
+function stripQuotes(value) {
+  if (typeof value !== "string") return value;
+  const text = value;
+  if (text.length >= 2 && (text.startsWith('"') && text.endsWith('"') || text.startsWith("'") && text.endsWith("'"))) {
+    return text.slice(1, -1).trim();
+  }
+  return text.trim();
+}
+var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function isValidUuid(value) {
+  if (typeof value !== "string") return false;
+  return UUID_PATTERN.test(stripQuotes(value));
+}
+function isValidIp(value) {
+  if (typeof value !== "string") return false;
+  return isIP(stripQuotes(value)) !== 0;
+}
+function isPrivateIp(value) {
+  if (typeof value !== "string") return false;
+  const text = stripQuotes(value);
+  const version = isIP(text);
+  if (version === 6) {
+    const lower = text.toLowerCase();
+    if (lower === "::1") return true;
+    const first2 = lower.split(":")[0];
+    return first2.startsWith("fc") || first2.startsWith("fd") || /^fe[89ab]/.test(lower);
+  }
+  if (version !== 4) return false;
+  const octets = text.split(".").map((part) => Number(part));
+  const [first, second] = octets;
+  return first === 10 || first === 172 && second >= 16 && second <= 31 || first === 192 && second === 168 || first === 127 || first === 169 && second === 254;
+}
+
+// src/commands/data-integration/profile.ts
 var UNIQUE_SAMPLE_LIMIT = 1e4;
 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",
@@ -1520,6 +2147,8 @@ var DISTINCT_NAMES = ["#distinct_id", "distinct_id", "distinctid", "device_id",
 var TIME_NAMES = ["#time", "time", "timestamp", "event_time", "created_at", "occurred_at", "datetime", "date", "\u65F6\u95F4", "\u4E8B\u4EF6\u65F6\u95F4", "\u53D1\u751F\u65F6\u95F4", "\u521B\u5EFA\u65F6\u95F4", "\u4E0B\u5355\u65F6\u95F4", "\u8BA2\u5355\u65F6\u95F4"];
 var EVENT_NAMES = ["#event_name", "event_name", "event", "action", "activity", "\u4E8B\u4EF6\u540D", "\u4E8B\u4EF6\u540D\u79F0", "\u4E8B\u4EF6", "\u884C\u4E3A", "\u52A8\u4F5C"];
 var TYPE_NAMES = ["#type", "record_type", "data_type", "\u64CD\u4F5C\u7C7B\u578B"];
+var IP_NAMES = ["#ip", "ip", "ip_address", "ipaddress", "client_ip", "clientip", "remote_addr", "remoteaddr", "ip\u5730\u5740", "\u5BA2\u6237\u7AEFip"];
+var UUID_NAMES = ["#uuid", "uuid", "event_uuid", "eventuuid", "request_uuid", "requestuuid", "\u552F\u4E00\u6807\u8BC6", "\u552F\u4E00id"];
 async function profileLocalData(input, dataSet, sourceTimezone = "Asia/Shanghai", options = {}) {
   const columns = /* @__PURE__ */ new Map();
   const recognizedRecordTypes = /* @__PURE__ */ new Set();
@@ -1529,15 +2158,22 @@ async function profileLocalData(input, dataSet, sourceTimezone = "Asia/Shanghai"
     options.collectNestedTree && (input.format === "json" || input.format === "jsonl")
   );
   const collectDelimitedTree = Boolean(
-    options.collectNestedTree && (input.format === "csv" || input.format === "tsv")
+    options.collectNestedTree && (input.format === "csv" || input.format === "tsv" || input.format === "xlsx" || input.format === "xls")
   );
   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;
@@ -1548,6 +2184,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) {
@@ -1560,12 +2200,27 @@ async function profileLocalData(input, dataSet, sourceTimezone = "Asia/Shanghai"
             uniqueOverflow: false,
             timeParseCount: 0,
             timeFormatCounts: /* @__PURE__ */ new Map(),
+            uuidValidCount: 0,
+            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;
@@ -1581,25 +2236,38 @@ async function profileLocalData(input, dataSet, sourceTimezone = "Asia/Shanghai"
         } else {
           accumulator.uniqueOverflow = true;
         }
-        if (options.collectSamples) recordSample(accumulator, value);
-        if (collectDelimitedTree && typeof value === "string" && value.trim().startsWith("{")) {
-          try {
-            const parsed = JSON.parse(value);
-            if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
-              let sampler = delimitedNested.get(name);
-              if (!sampler) {
-                sampler = { seen: 0, objects: [] };
-                delimitedNested.set(name, sampler);
-              }
-              sampler.seen += 1;
-              if (sampler.objects.length < NESTED_TREE_SAMPLE_LIMIT) {
-                sampler.objects.push(parsed);
-              } else {
-                const slot = randomInt(sampler.seen);
-                if (slot < NESTED_TREE_SAMPLE_LIMIT) sampler.objects[slot] = parsed;
+        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("[")) {
+            try {
+              const parsed = JSON.parse(value);
+              if (parsed !== null && typeof parsed === "object") {
+                let sampler = delimitedNested.get(name);
+                if (!sampler) {
+                  sampler = { seen: 0, values: [] };
+                  delimitedNested.set(name, sampler);
+                }
+                sampler.seen += 1;
+                if (sampler.values.length < NESTED_TREE_SAMPLE_LIMIT) {
+                  sampler.values.push(parsed);
+                } else {
+                  const slot = randomInt(sampler.seen);
+                  if (slot < NESTED_TREE_SAMPLE_LIMIT) sampler.values[slot] = parsed;
+                }
               }
+            } catch {
             }
-          } catch {
           }
         }
         if (isParseableTime(value, matchesName(name, TIME_NAMES))) {
@@ -1611,11 +2279,29 @@ async function profileLocalData(input, dataSet, sourceTimezone = "Asia/Shanghai"
             }
           }
         }
+        if (matchesName(name, UUID_NAMES) && isValidUuid(value)) accumulator.uuidValidCount += 1;
+        if (matchesName(name, IP_NAMES) && isValidIp(value)) {
+          accumulator.ipValidCount += 1;
+          if (isPrivateIp(value)) accumulator.lanIpCount += 1;
+        }
         if (matchesName(name, TYPE_NAMES)) {
           const normalized = normalizeRecordType(value);
           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,
@@ -1623,23 +2309,31 @@ async function profileLocalData(input, dataSet, sourceTimezone = "Asia/Shanghai"
       headerNames: options.headerNames,
       noHeader: options.noHeader,
       flattenRules: options.flattenRules,
-      mergeSheets: options.mergeSheets
+      mergeSheets: options.mergeSheets,
+      excelDateColumns,
+      cellIssues,
+      warnRagged: options.warnRagged,
+      skipRows: options.skipRows,
+      xlsxStructure,
+      fillMergedCells: options.fillMergedCells,
+      excludeHiddenRows: options.excludeHiddenRows
     }
   );
   const delimitedNestedTree = /* @__PURE__ */ new Map();
   for (const [columnName, sampler] of delimitedNested) {
-    if (sampler.objects.length > 0) delimitedNestedTree.set(columnName, buildNestedTree(sampler.objects));
+    if (sampler.values.length > 0) delimitedNestedTree.set(columnName, buildColumnNestedTree(sampler.values));
   }
   const columnProfiles = [];
   const timeFormatByColumn = /* @__PURE__ */ new Map();
   for (const column of columns.values()) {
     const profile = formatColumnProfile(column, rowCount, options.collectSamples ?? false);
-    const nestedTree = delimitedNestedTree.get(column.name);
-    if (nestedTree && nestedTree.length > 0) profile.nested_tree = nestedTree;
+    const nestedTree2 = delimitedNestedTree.get(column.name);
+    if (nestedTree2 && nestedTree2.length > 0) profile.nested_tree = nestedTree2;
     columnProfiles.push(profile);
     const dominantFormat = dominantTimeFormat(column);
     if (dominantFormat) timeFormatByColumn.set(column.name, dominantFormat);
   }
+  const nestedTree = collectNestedTree && nestedObjects.length > 0 ? buildNestedTree(nestedObjects) : void 0;
   const identityCandidates = findIdentityCandidates(columnProfiles);
   const recommendedMapping = recommendMapping({
     input,
@@ -1649,9 +2343,34 @@ async function profileLocalData(input, dataSet, sourceTimezone = "Asia/Shanghai"
     recognizedRecordTypes,
     sourceTimezone,
     headerNames: options.headerNames,
-    timeFormatByColumn
+    skipRows: options.skipRows,
+    fillMergedCells: options.fillMergedCells,
+    excludeHiddenRows: options.excludeHiddenRows,
+    timeFormatByColumn,
+    nestedTree
   });
   const warnings = [...recommendedMapping.warnings ?? []];
+  for (const column of columns.values()) {
+    if (matchesName(column.name, UUID_NAMES) && column.nonMissing > 0) {
+      const invalid = column.nonMissing - column.uuidValidCount;
+      if (invalid > 0) warnings.push(`${column.name}: ${invalid} non-empty value(s) are not standard 36-character UUIDs; #uuid requires the standard UUID format.`);
+    }
+    if (matchesName(column.name, IP_NAMES) && column.nonMissing > 0) {
+      const invalid = column.nonMissing - column.ipValidCount;
+      if (invalid > 0) warnings.push(`${column.name}: ${invalid} non-empty value(s) are not valid IPv4 or IPv6 addresses.`);
+      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",
@@ -1670,7 +2389,10 @@ async function profileLocalData(input, dataSet, sourceTimezone = "Asia/Shanghai"
       (recommendedMapping.account_id_field || recommendedMapping.distinct_id_field) && recommendedMapping.time.field
     ),
     warnings,
-    ...collectNestedTree && nestedObjects.length > 0 ? { nested_tree: buildNestedTree(nestedObjects) } : {}
+    ...nestedTree ? { nested_tree: nestedTree } : {},
+    ...structureReport ? { xlsx_structure: structureReport } : {},
+    ...summaryRows.length > 0 ? { summary_rows: summaryRows } : {},
+    ...duplicateKeyReport ? { duplicate_keys: duplicateKeyReport } : {}
   };
 }
 function normalizeAeName(input, fallback) {
@@ -1743,24 +2465,12 @@ function recommendMapping(input) {
     warnings.push("No event-name column was found; review the generated default event name.");
   }
   const reserved = new Set([account?.name, distinct?.name, time?.name, event?.name, recordType?.name].filter(Boolean));
-  const usedTargets = /* @__PURE__ */ new Set();
-  const properties = input.columns.filter((column) => !reserved.has(column.name)).map((column, index) => {
-    const baseTarget = normalizeAeName(column.name, `field_${index + 1}`);
-    let target = baseTarget;
-    let suffix = 2;
-    while (usedTargets.has(target)) target = `${baseTarget.slice(0, 46)}_${suffix++}`;
-    usedTargets.add(target);
-    const type = mappingType(column.inferred_type);
-    return {
-      source: column.name,
-      target,
-      type,
-      ...type === "object" || type === "list" ? { transform: "json" } : {}
-    };
-  });
+  const recordRoots = /* @__PURE__ */ new Map();
+  for (const node of input.nestedTree ?? []) recordRoots.set(node.name, node);
+  const { properties, flattenRules } = recommendProperties(input.columns, reserved, recordRoots, warnings);
   const defaultEventSource = input.dataSet.kind === "sheet" ? input.dataSet.label : basename2(input.input.filePath, extname2(input.input.filePath));
   return {
-    version: "ae-local-data-mapping/v1",
+    version: MAPPING_VERSION,
     source: {
       sha256: input.input.sha256,
       format: input.input.format,
@@ -1777,9 +2487,13 @@ 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") } : {},
+    ...Object.keys(flattenRules).length > 0 ? { flatten_rules: flattenRules } : {},
     properties,
     ...warnings.length > 0 ? { warnings } : {}
   };
@@ -1788,7 +2502,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,
@@ -1800,6 +2514,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));
@@ -1863,9 +2586,120 @@ function normalizeRecordType(value) {
   };
   return aliases[normalized];
 }
+function recommendProperties(columns, reserved, recordRoots, warnings) {
+  const properties = [];
+  const flattenRules = {};
+  const usedTargets = /* @__PURE__ */ new Set();
+  const claim = (desired) => {
+    let target = desired;
+    let suffix = 2;
+    while (usedTargets.has(target)) target = `${desired.slice(0, 46)}_${suffix++}`;
+    usedTargets.add(target);
+    return target;
+  };
+  const state = { properties, flattenRules, usedTargets, warnings, claim };
+  columns.filter((column) => !reserved.has(column.name)).forEach((column, index) => {
+    const baseName = normalizeAeName(column.name, `field_${index + 1}`);
+    const valueNode = columnValueNode(column, recordRoots);
+    if (!valueNode) {
+      const type = mappingType(column.inferred_type);
+      const target = claim(baseName);
+      properties.push({ source: column.name, target, type, ...isContainerType(type) ? { transform: "json" } : {} });
+      return;
+    }
+    if (valueNode.kind === "primitive") {
+      const type = mappingType(valueNode.inferredType ?? column.inferred_type);
+      const target = claim(baseName);
+      properties.push({ source: column.name, target, type });
+      return;
+    }
+    if (valueNode.kind === "object") {
+      recommendObject(state, baseName, column.name, valueNode.children ?? [], column.name);
+      return;
+    }
+    recommendArray(state, baseName, column.name, valueNode, column.name);
+  });
+  return { properties, flattenRules };
+}
+function columnValueNode(column, recordRoots) {
+  const recordNode = recordRoots.get(column.name);
+  if (recordNode) return recordNode;
+  const tree = column.nested_tree;
+  if (!tree || tree.length === 0) return void 0;
+  if (tree.length === 1 && tree[0].kind === "array") return tree[0];
+  return { path: "", name: column.name, kind: "object", children: tree, nonEmpty: true };
+}
+function isScalarNode(node) {
+  return node.kind === "primitive" || node.kind === "array" && node.elementKind === "primitive";
+}
+function isContainerType(type) {
+  return type === "object" || type === "list" || type === "array_row";
+}
+function scalarPropType(node) {
+  if (node.kind === "array") return "list";
+  switch (node.inferredType) {
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "datetime":
+      return "datetime";
+    default:
+      return "string";
+  }
+}
+function snakeSegment(name) {
+  return normalizeAeName(name, "field");
+}
+function recommendObject(state, prefix, dotPath, children, columnName) {
+  const hasComposite = children.some((child) => child.kind === "object" || child.kind === "array" && child.elementKind === "object");
+  if (!hasComposite) {
+    const parentTarget = state.claim(prefix);
+    const source = dotPath === columnName ? columnName : parentTarget;
+    if (source !== columnName) state.flattenRules[parentTarget] = dotPath;
+    state.properties.push({ source, target: parentTarget, type: "object", transform: "json" });
+    for (const child of children) {
+      state.properties.push({ source: parentTarget, target: `${parentTarget}.${snakeSegment(child.name)}`, type: scalarPropType(child) });
+    }
+    return;
+  }
+  for (const child of children) {
+    const childPrefix = `${prefix}_${snakeSegment(child.name)}`;
+    const childDotPath = `${dotPath}.${child.name}`;
+    if (isScalarNode(child)) {
+      const target = state.claim(childPrefix);
+      state.flattenRules[target] = childDotPath;
+      state.properties.push({ source: target, target, type: scalarPropType(child) });
+    } else if (child.kind === "object") {
+      recommendObject(state, childPrefix, childDotPath, child.children ?? [], columnName);
+    } else {
+      recommendArray(state, childPrefix, childDotPath, child, columnName);
+    }
+  }
+}
+function recommendArray(state, prefix, dotPath, node, columnName) {
+  if (node.elementKind !== "object") {
+    const target = state.claim(prefix);
+    const source2 = dotPath === columnName ? columnName : target;
+    if (source2 !== columnName) state.flattenRules[target] = dotPath;
+    state.properties.push({ source: source2, target, type: "list", transform: "json" });
+    return;
+  }
+  const parentTarget = state.claim(prefix);
+  const source = dotPath === columnName ? columnName : parentTarget;
+  if (source !== columnName) state.flattenRules[parentTarget] = dotPath;
+  state.properties.push({ source, target: parentTarget, type: "array_row", transform: "json" });
+  for (const field of node.children ?? []) {
+    if (isScalarNode(field)) {
+      state.properties.push({ source: parentTarget, target: `${parentTarget}.${snakeSegment(field.name)}`, type: scalarPropType(field) });
+    } else {
+      state.warnings.push(`${dotPath} element field "${field.name}" is nested; it stays inside the ${parentTarget} array data and is not declared as a sub-property (array-element flattening is not yet supported).`);
+    }
+  }
+}
 function mappingType(type) {
   if (type === "datetime") return "datetime";
-  if (type === "number" || type === "boolean" || type === "list" || type === "object") return type;
+  if (type === "number" || type === "boolean" || type === "object" || type === "list") return type;
   return "string";
 }
 function compatibleTypes(types) {
@@ -1903,6 +2737,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;
@@ -1928,7 +2932,7 @@ function dominantTimeFormat(column) {
   return best && bestCount >= total * 0.9 ? best : void 0;
 }
 
-// src/commands/data-integration/local-data/inspect.ts
+// src/commands/data-integration/inspect.ts
 var HEADERLESS_WARNING = "The first row appears to be data, not a header; columns were auto-named col_1..col_N. Re-run with --headers to supply explicit names.";
 var dataIntegrationInspect = {
   service: "data-integration",
@@ -1940,9 +2944,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) => {
@@ -1973,46 +2989,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 {
@@ -2023,6 +3062,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));
@@ -2033,10 +3079,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 {
@@ -2044,6 +3091,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,
@@ -2060,7 +3142,7 @@ function splitHeaders(raw) {
   return headers.length > 0 ? headers : void 0;
 }
 
-// src/commands/data-integration/local-data/plan.ts
+// 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_]*$/;
@@ -2076,6 +3158,8 @@ function toPropType(type) {
       return "array_string";
     case "object":
       return "object";
+    case "array_row":
+      return "array_row";
     case "string":
       return "string";
   }
@@ -2083,13 +3167,16 @@ function toPropType(type) {
 function buildDraftFromMapping(options) {
   const { mapping } = options;
   const excluded = new Set(mapping.exclude_columns ?? []);
-  const properties = mapping.properties.filter((property) => !excluded.has(property.source)).map((property) => ({
-    name: property.target,
-    display_name: property.source,
-    desc: property.desc ?? property.source,
-    type: toPropType(property.type),
-    source: "data"
-  }));
+  const properties = mapping.properties.filter((property) => !excluded.has(property.source)).map((property) => {
+    const leaf = property.target.includes(".") ? property.target.split(".").pop() : void 0;
+    return {
+      name: property.target,
+      display_name: leaf ?? property.source,
+      desc: property.desc ?? leaf ?? property.source,
+      type: toPropType(property.type),
+      source: "data"
+    };
+  });
   const propNames = properties.map((property) => property.name);
   const eventNames = resolveEventNames(options);
   const events = eventNames.map((eventName) => {
@@ -2167,7 +3254,7 @@ function buildPlanDraft(ctx) {
       location: { field: "lang" }
     });
   }
-  return buildDraftFromMapping({
+  const draft = buildDraftFromMapping({
     mapping,
     planName: ctx.str("plan-name").trim() || mapping.default_event_name || "local-data",
     eventNames: ctx.list("event-name"),
@@ -2175,6 +3262,17 @@ function buildPlanDraft(ctx) {
     lang,
     projectId: ctx.optionalNum("project-id")
   });
+  validateAndFix(draft);
+  try {
+    validateDraft(draft);
+  } catch (error) {
+    throw new CliValidationError("The tracking-plan draft is invalid.", {
+      code: "LOCAL_DATA_PLAN_INVALID_DRAFT",
+      hint: error instanceof Error ? error.message : String(error),
+      location: { field: "mapping" }
+    });
+  }
+  return draft;
 }
 var dataIntegrationPlan = {
   service: "data-integration",
@@ -2182,7 +3280,7 @@ var dataIntegrationPlan = {
   usesAeHost: false,
   description: "Convert a confirmed local-data mapping into a tracking-plan draft.json (source_type=data, sdk_integration_mode=none).",
   flags: [
-    { name: "mapping", type: "string", required: true, sensitive: true, desc: "Confirmed ae-local-data-mapping/v1 JSON, file path, or @file." },
+    { name: "mapping", type: "string", required: true, sensitive: true, desc: `Confirmed ${MAPPING_VERSION} JSON, file path, or @file.` },
     { name: "event-name", type: "string", variadic: true, desc: "Concrete event name (track/mixed without default_event_name). Repeat for multiple events." },
     { name: "plan-name", type: "string", desc: 'Plan name. Default: the mapping default_event_name, else "local-data".' },
     { name: "app-type", type: "string", default: "unknown", desc: "Application type recorded in draft meta (informational)." },
@@ -2213,7 +3311,7 @@ var dataIntegrationPlan = {
   }
 };
 
-// src/commands/data-integration/local-data/conversion.ts
+// src/commands/data-integration/conversion.ts
 import { randomInt as randomInt2, randomUUID } from "crypto";
 import {
   chmodSync,
@@ -2234,14 +3332,6 @@ import { createInterface as createInterface2 } from "readline";
 var SORT_CHUNK_SIZE = 1e4;
 var THREE_YEARS_MS = 3 * 365 * 24 * 60 * 60 * 1e3;
 var THREE_DAYS_MS = 3 * 24 * 60 * 60 * 1e3;
-function stripQuotes(value) {
-  if (typeof value !== "string") return value;
-  const text = value;
-  if (text.length >= 2 && (text.startsWith('"') && text.endsWith('"') || text.startsWith("'") && text.endsWith("'"))) {
-    return text.slice(1, -1).trim();
-  }
-  return text.trim();
-}
 async function convertLocalData(options) {
   const input = await inspectLocalDataInput(options.inputFile);
   if (input.format !== options.mapping.source.format) {
@@ -2260,13 +3350,29 @@ 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
+    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,
+    // 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;
   const runId = `${formatRunTimestamp(/* @__PURE__ */ new Date())}-${randomUUID().slice(0, 8)}`;
-  const outputDir = resolve(options.outputDir || join(".ae-cli", "data-integration", runId));
+  const outputDir = resolve(options.outputDir || join(".ae-cli", "data-integration", "runs", runId));
   prepareOutputDirectory(outputDir);
   const profile = await profileLocalData(input, dataSet, options.mapping.time.source_timezone, streamOptions);
   const profilePath = join(outputDir, "profile.json");
@@ -2283,7 +3389,12 @@ async function convertLocalData(options) {
   let validRecords = 0;
   let invalidRecords = 0;
   const recordTypes = {};
-  await streamLocalDataRows(
+  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,
     async (row, rowNumber) => {
@@ -2297,6 +3408,10 @@ async function convertLocalData(options) {
       }
       validRecords += 1;
       recordTypes[result.recordType] = (recordTypes[result.recordType] ?? 0) + 1;
+      if (result.lanIp) lanIpRecords += 1;
+      for (const skip of result.skips) {
+        skippedFields[skip.code] = (skippedFields[skip.code] ?? 0) + 1;
+      }
       const line = JSON.stringify(result.record);
       if (isUserProfileType(result.recordType)) {
         userSetBuffer.push({ key: result.sortKey, line });
@@ -2307,14 +3422,33 @@ async function convertLocalData(options) {
     },
     {
       headerNames: streamOptions.headerNames,
+      skipRows: streamOptions.skipRows,
       flattenRules: streamOptions.flattenRules,
-      mergeSheets: streamOptions.mergeSheets
+      flattenMisses,
+      cellIssues,
+      mergeSheets: streamOptions.mergeSheets,
+      fillMergedCells: streamOptions.fillMergedCells,
+      excludeHiddenRows: streamOptions.excludeHiddenRows,
+      xlsxStructure
     }
   );
   if (userSetBuffer.length > 0) flushSortChunk(outputDir, userSetBuffer, sortChunks);
-  trackStream.end();
-  invalidStream.end();
-  await Promise.all([once(trackStream, "finish"), once(invalidStream, "finish")]);
+  await Promise.all([finishStream(trackStream), finishStream(invalidStream)]);
+  for (const [outColumn, count] of Object.entries(flattenMisses)) {
+    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",
@@ -2325,21 +3459,22 @@ async function convertLocalData(options) {
   const validStream = secureWriteStream(validPath);
   if (existsSync(trackTempPath)) {
     for await (const chunk of createReadStream3(trackTempPath)) {
-      if (!validStream.write(chunk)) await once(validStream, "drain");
+      await writeRaw(validStream, chunk);
     }
   }
   await mergeSortChunks(sortChunks, validStream);
-  validStream.end();
-  await once(validStream, "finish");
+  await finishStream(validStream);
   if (existsSync(trackTempPath)) unlinkSync(trackTempPath);
   for (const path of sortChunks) if (existsSync(path)) unlinkSync(path);
   writeSecureJson(profilePath, profile);
   writeSecureJson(mappingPath, options.mapping);
   writeSecureText(transformPath, createTransformScript(options.inputFile, mappingPath));
   const validBytes = statSize(validPath);
+  const sourceRows = salvageSet ? salvageMatched : rowCount;
   const blockedReasons = [
-    ...invalidRecords > 0 ? ["Some source rows failed UE validation."] : [],
-    ...validRecords === 0 ? ["No valid UE records were generated."] : []
+    ...rowCount === 0 ? ["The source contained no data rows."] : [],
+    ...rowCount > 0 && validRecords === 0 ? ["No valid UE records were generated."] : [],
+    ...invalidRecords > 0 ? ["Some source rows failed UE validation."] : []
   ];
   const manifest = {
     version: "ae-local-data-manifest/v1",
@@ -2357,10 +3492,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
+      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 } : {},
+      ...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
   };
@@ -2378,7 +3521,9 @@ async function convertLocalDataMulti(options) {
     const profile = await profileLocalData(input, dataSet, sourceTimezone, {
       collectSamples: true,
       headerNames: options.mapping.headers,
-      flattenRules: options.mapping.flatten_rules
+      skipRows: options.mapping.skip_rows,
+      flattenRules: options.mapping.flatten_rules,
+      warnRagged: false
     });
     profiled.push({ file: basename4(inputFile), profile });
   }
@@ -2394,7 +3539,7 @@ async function convertLocalDataMulti(options) {
   validateTypeResolutions(resolutions, profiled.map((entry) => entry.file));
   const overrides = applyTypeResolutions(resolutions, profiled);
   const parent = resolve(
-    options.outputDir || join(".ae-cli", "data-integration", `${formatRunTimestamp(/* @__PURE__ */ new Date())}-${randomUUID().slice(0, 8)}`)
+    options.outputDir || join(".ae-cli", "data-integration", "runs", `${formatRunTimestamp(/* @__PURE__ */ new Date())}-${randomUUID().slice(0, 8)}`)
   );
   prepareOutputDirectory(parent);
   const files = [];
@@ -2452,11 +3597,32 @@ function convertRow(row, rowNumber, mapping, now) {
       errors.push({ code: "INVALID_EVENT_NAME", field: mapping.event_name_field });
     }
   }
-  const ip = readOptionalField(row, mapping.ip_field);
-  const uuid = readOptionalField(row, mapping.uuid_field);
+  const skips = [];
+  let lanIp = false;
+  let ip;
+  if (recordType === "track") {
+    const rawIp = readOptionalField(row, mapping.ip_field);
+    if (rawIp) {
+      if (isValidIp(rawIp)) {
+        ip = rawIp;
+        lanIp = isPrivateIp(rawIp);
+      } else {
+        skips.push({ code: "INVALID_IP", field: mapping.ip_field });
+      }
+    }
+  }
+  let uuid;
+  {
+    const rawUuid = readOptionalField(row, mapping.uuid_field);
+    if (rawUuid) {
+      if (isValidUuid(rawUuid)) uuid = rawUuid;
+      else skips.push({ code: "INVALID_UUID", field: mapping.uuid_field });
+    }
+  }
   const excluded = new Set(mapping.exclude_columns ?? []);
   const properties = {};
   for (const property of mapping.properties) {
+    if (property.target.includes(".")) continue;
     if (excluded.has(property.source)) continue;
     let value = stripQuotes(row[property.source]);
     if (isMissing2(value)) continue;
@@ -2470,8 +3636,8 @@ function convertRow(row, rowNumber, mapping, now) {
       properties[property.target] = converted.value;
     }
   }
-  const zoneOffset = mapping.zone_offset_value !== void 0 ? resolveZoneOffsetValue(mapping.zone_offset_value, now) : mapping.zone_offset_field ? readZoneOffset(row, mapping.zone_offset_field) : void 0;
-  if (mapping.zone_offset_field && zoneOffset === void 0) {
+  const zoneOffset = recordType === "track" && mapping.zone_offset_value !== void 0 ? resolveZoneOffsetValue(mapping.zone_offset_value, now) : recordType === "track" && mapping.zone_offset_field ? readZoneOffset(row, mapping.zone_offset_field) : void 0;
+  if (recordType === "track" && mapping.zone_offset_field && zoneOffset === void 0) {
     errors.push({ code: "INVALID_ZONE_OFFSET", field: mapping.zone_offset_field });
   }
   if (errors.length > 0 || !recordType || !normalizedTime) return { ok: false, errors };
@@ -2489,7 +3655,9 @@ function convertRow(row, rowNumber, mapping, now) {
     ok: true,
     recordType,
     record,
-    sortKey: `${accountId ?? distinctId ?? ""}\0${normalizedTime.instant.toISOString()}\0${String(rowNumber).padStart(12, "0")}`
+    sortKey: `${accountId ?? distinctId ?? ""}\0${normalizedTime.instant.toISOString()}\0${String(rowNumber).padStart(12, "0")}`,
+    skips,
+    lanIp
   };
 }
 function readOptionalField(row, field) {
@@ -2597,7 +3765,7 @@ function convertProperty(value, type, transform, timeZone = "UTC", timeFormat) {
       const normalized = normalizeTime(value, timeZone, timeFormat);
       return normalized ? { ok: true, value: normalized.formatted } : { ok: false, code: "PROPERTY_TYPE_CONFLICT" };
     }
-    if (type === "list") {
+    if (type === "list" || type === "array_row") {
       if (!Array.isArray(value)) return { ok: false, code: "PROPERTY_TYPE_CONFLICT" };
       return isPropertyWithinLimits(value, type) ? { ok: true, value } : { ok: false, code: "PROPERTY_LIMIT_EXCEEDED" };
     }
@@ -2799,11 +3967,40 @@ function prepareOutputDirectory(path) {
   chmodSync(path, 448);
 }
 function secureWriteStream(path) {
-  return createWriteStream(path, { encoding: "utf8", mode: 384, flags: "wx" });
+  const stream = createWriteStream(path, { encoding: "utf8", mode: 384, flags: "wx" });
+  let fail;
+  const errorPromise = new Promise((_, reject) => {
+    fail = reject;
+  });
+  errorPromise.catch(() => {
+  });
+  stream.on("error", (error) => fail?.(error));
+  return { stream, path, errorPromise };
+}
+function writeFailure(path, error) {
+  const detail = error instanceof Error ? error.message : String(error);
+  return new Error(`Failed to write "${path}": ${detail}. Check available disk space and directory permissions.`, { cause: error });
 }
-async function writeLine(stream, line) {
-  if (!stream.write(`${line}
-`)) await once(stream, "drain");
+async function writeRaw(target, data) {
+  try {
+    if (!target.stream.write(data)) {
+      await Promise.race([once(target.stream, "drain"), target.errorPromise]);
+    }
+  } catch (error) {
+    throw writeFailure(target.path, error);
+  }
+}
+async function writeLine(target, line) {
+  await writeRaw(target, `${line}
+`);
+}
+async function finishStream(target) {
+  try {
+    target.stream.end();
+    await Promise.race([once(target.stream, "finish"), target.errorPromise]);
+  } catch (error) {
+    throw writeFailure(target.path, error);
+  }
 }
 function writeSecureJson(path, value) {
   writeSecureText(path, `${JSON.stringify(value, null, 2)}
@@ -2830,7 +4027,7 @@ function formatRunTimestamp(value) {
   return value.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
 }
 
-// src/commands/data-integration/local-data/convert.ts
+// src/commands/data-integration/convert.ts
 var dataIntegrationConvert = {
   service: "data-integration",
   command: "convert",
@@ -2838,8 +4035,8 @@ var dataIntegrationConvert = {
   description: "Convert one or more local data sets into validated UE JSONL and quarantine invalid rows.",
   flags: [
     { name: "input-file", type: "string", required: true, sensitive: true, variadic: true, desc: "Source local data file. Repeat for multiple files (requires a wildcard mapping). The source is never modified." },
-    { name: "mapping", type: "string", required: true, sensitive: true, desc: "ae-local-data-mapping/v1 JSON, file path, or @file." },
-    { name: "output-dir", type: "string", sensitive: true, desc: "New or empty output directory. Default: .ae-cli/data-integration/<run-id>." },
+    { name: "mapping", type: "string", required: true, sensitive: true, desc: `${MAPPING_VERSION} JSON, file path, or @file.` },
+    { name: "output-dir", type: "string", sensitive: true, desc: "New or empty output directory. Default: .ae-cli/data-integration/runs/<run-id>." },
     { name: "type-resolutions", type: "json", sensitive: true, desc: "JSON object resolving cross-file column type conflicts (unify, split, or skip)." },
     { name: "merge-sheets", type: "boolean", default: false, desc: "Stream every worksheet in file order instead of a single selected sheet." },
     { name: "salvage-from", type: "string", sensitive: true, desc: "Re-process only the rows listed in a previous run's invalid.rows.jsonl, against the current (fixed) mapping. Single-file only." }
@@ -2891,7 +4088,7 @@ var dataIntegrationConvert = {
   }
 };
 
-// src/commands/data-integration/local-data/upload.ts
+// src/commands/data-integration/upload.ts
 import { createReadStream as createReadStream4, readFileSync as readFileSync3, statSync as statSync3 } from "fs";
 import { basename as basename5, dirname, resolve as resolve2 } from "path";
 import { createInterface as createInterface3 } from "readline";
@@ -3236,22 +4433,900 @@ function isRecord3(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
-// src/commands/data-integration/local-data/handoff.ts
+// src/commands/data-integration/handoff.ts
 import { createHash as createHash3 } from "crypto";
-import { chmodSync as chmodSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync4, renameSync as renameSync2, writeFileSync as writeFileSync2 } from "fs";
-import { join as join2, resolve as resolve3 } from "path";
+import { chmodSync as chmodSync2, mkdirSync as mkdirSync2, mkdtempSync, readFileSync as readFileSync4, renameSync as renameSync2, rmSync, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname2, join as join3, resolve as resolve3 } from "path";
+import { tmpdir } from "os";
+
+// src/commands/data-integration/archive.ts
+import { ZipArchive } from "archiver";
+import { createWriteStream as createWriteStream2, readdirSync as readdirSync2, statSync as statSync4 } from "fs";
+import { join as join2, relative, sep } from "path";
+async function zipPackage(dir, zipPath) {
+  await new Promise((resolvePromise, rejectPromise) => {
+    const output = createWriteStream2(zipPath, { mode: 384 });
+    const zip = new ZipArchive({ zlib: { level: 9 } });
+    output.on("close", resolvePromise);
+    output.on("error", rejectPromise);
+    zip.on("error", rejectPromise);
+    zip.on("warning", (error) => {
+      if (error.code !== "ENOENT") rejectPromise(error);
+    });
+    zip.pipe(output);
+    const walk = (current) => {
+      for (const name of readdirSync2(current)) {
+        if (name === ".DS_Store") continue;
+        const full = join2(current, name);
+        const stats = statSync4(full);
+        if (stats.isDirectory()) {
+          walk(full);
+        } else {
+          const rel = relative(dir, full).split(sep).join("/");
+          zip.file(full, { name: rel, mode: stats.mode & 511 });
+        }
+      }
+    };
+    walk(dir);
+    void zip.finalize();
+  });
+}
+
+// src/commands/data-integration/relay.ts
+var PIPELINE_VERSION = "ae-data-integration-pipeline/v1";
+var SHAPE_VERSION = "ae-data-integration-shape/v1";
+var DEFAULT_BATCH_SIZE2 = 500;
+var ENV_FILE = ".local/target.env";
+function buildPipelineDescriptor(entries, target = {}) {
+  const first = entries[0];
+  return {
+    version: PIPELINE_VERSION,
+    created_at: first?.created_at ?? (/* @__PURE__ */ new Date()).toISOString(),
+    source: { type: "local_file", params: { format: first?.format ?? "csv" } },
+    transform: { type: MAPPING_VERSION, refs: entries.map((entry) => entry.mapping_file) },
+    sink: {
+      type: "restful_sync_json",
+      params: {
+        batch_size: DEFAULT_BATCH_SIZE2,
+        env_file: ENV_FILE,
+        ...target.pushurl ? { pushurl: target.pushurl } : {},
+        ...target.project_id ? { project_id: target.project_id } : {}
+      }
+    }
+  };
+}
+function buildShapeBaseline(items) {
+  return {
+    version: SHAPE_VERSION,
+    entries: items.map(({ mapping, fingerprint }) => ({
+      fingerprint,
+      mode: mapping.mode,
+      data_set: mapping.source.data_set,
+      format: mapping.source.format,
+      columns: sourceColumns(mapping)
+    }))
+  };
+}
+function sh(...lines) {
+  return `${lines.join("\n")}
+`;
+}
+function generateBinScripts() {
+  return [
+    { relPath: "bin/run.sh", content: runSh(), mode: 448 },
+    { relPath: "bin/upload.sh", content: uploadSh(), mode: 448 },
+    { relPath: "bin/bind_mapping.py", content: bindMappingPy(), mode: 448 },
+    { relPath: "bin/summarize.py", content: summarizePy(), mode: 448 },
+    { relPath: "bin/plan_check.py", content: planCheckPy(), mode: 448 },
+    { relPath: "bin/verify.py", content: verifyPy(), mode: 448 },
+    { relPath: "bin/resolve_appid.py", content: resolveAppidPy(), mode: 448 }
+  ];
+}
+function runSh() {
+  return sh(
+    "#!/usr/bin/env bash",
+    "# Generic pipeline executor: source -> transform -> plan. Never uploads (see upload.sh).",
+    "# Reads pipeline.json and dispatches each stage by its `type` to ae-cli subcommands.",
+    "set -euo pipefail",
+    'SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"',
+    'PKG_ROOT="$(dirname "$SCRIPT_DIR")"',
+    'cd "$PKG_ROOT"',
+    "",
+    `SRC_TYPE="$(python3 -c 'import json; print(json.load(open("pipeline.json"))["source"]["type"])')"`,
+    'case "$SRC_TYPE" in',
+    "  local_file) ;;",
+    "  *)",
+    '    echo "unsupported source type: $SRC_TYPE" >&2',
+    '    echo "re-run the full ae-data-integration pipeline (or upgrade ae-cli) for this source." >&2',
+    "    exit 64",
+    "    ;;",
+    "esac",
+    "",
+    'INPUT="${1:-}"',
+    'if [ -z "$INPUT" ]; then',
+    "  shopt -s nullglob; FILES=(inbox/*); shopt -u nullglob",
+    '  if [ "${#FILES[@]}" -ne 1 ]; then',
+    '    echo "usage: bin/run.sh <input-file>" >&2',
+    '    echo "       (or put exactly one file in inbox/)" >&2',
+    "    exit 2",
+    "  fi",
+    '  INPUT="${FILES[0]}"',
+    "fi",
+    "",
+    'RUN_DIR="runs/$(date +%Y%m%d-%H%M%S)"',
+    'mkdir -p "$RUN_DIR"',
+    'echo "run: $RUN_DIR"',
+    "",
+    'python3 bin/bind_mapping.py "$INPUT" "$RUN_DIR"',
+    "",
+    "while IFS= read -r ref; do",
+    '  ref_dir="$(dirname "$ref")"',
+    '  echo "convert: $ref_dir"',
+    "  ae-cli data-integration convert \\",
+    '    --input-file "$INPUT" \\',
+    '    --mapping "$RUN_DIR/bound/$ref_dir/mapping.json" \\',
+    '    --output-dir "$RUN_DIR/$ref_dir" || exit $?',
+    `done < <(python3 -c 'import json,sys; print("\\n".join(json.load(open("pipeline.json"))["transform"]["refs"]))')`,
+    "",
+    'python3 bin/summarize.py "$RUN_DIR"',
+    'python3 bin/plan_check.py "$RUN_DIR"',
+    "",
+    "# Salvage hint: quarantined rows are never silently dropped. Re-process only",
+    "# them against the fixed mapping instead of re-uploading the whole file.",
+    "while IFS= read -r ref; do",
+    '  ref_dir="$(dirname "$ref")"',
+    '  inv="$RUN_DIR/$ref_dir/invalid.rows.jsonl"',
+    '  if [ -s "$inv" ]; then',
+    '    echo "note: $inv has quarantined rows \u2014 salvage them with:"',
+    '    echo "  ae-cli data-integration convert --input-file "$INPUT" --mapping "$RUN_DIR/bound/$ref_dir/mapping.json" --salvage-from "$inv" --output-dir "$RUN_DIR-salvage""',
+    "  fi",
+    `done < <(python3 -c 'import json,sys; print("\\n".join(json.load(open("pipeline.json"))["transform"]["refs"]))')`,
+    "",
+    'echo "done. review the summary and plan check, then run: bin/upload.sh $RUN_DIR"'
+  );
+}
+function uploadSh() {
+  return sh(
+    "#!/usr/bin/env bash",
+    "# Sink executor. Dry-run by default; --confirm actually uploads.",
+    "# Resolves the recorded target from pipeline.json (pushurl + project_id), derives",
+    "# the APPID via `ae-cli project info get` (bin/resolve_appid.py), and falls back to",
+    "# .local/target.env for explicit APPID / endpoint / project-id overrides.",
+    "set -euo pipefail",
+    'SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"',
+    'PKG_ROOT="$(dirname "$SCRIPT_DIR")"',
+    'cd "$PKG_ROOT"',
+    "",
+    `SINK_TYPE="$(python3 -c 'import json; print(json.load(open("pipeline.json"))["sink"]["type"])')"`,
+    'case "$SINK_TYPE" in',
+    "  restful_sync_json) ;;",
+    "  *)",
+    '    echo "unsupported sink type: $SINK_TYPE" >&2',
+    '    echo "re-run the full ae-data-integration pipeline (or upgrade ae-cli) for this sink." >&2',
+    "    exit 64",
+    "    ;;",
+    "esac",
+    "",
+    `SINK_PARAMS="$(python3 -c 'import json; print(json.dumps(json.load(open("pipeline.json"))["sink"]["params"]))')"`,
+    `BATCH_SIZE="$(python3 -c 'import json,sys; print(json.loads(sys.argv[1]).get("batch_size", 500))' "$SINK_PARAMS")"`,
+    `ENV_FILE="$(python3 -c 'import json,sys; print(json.loads(sys.argv[1]).get("env_file", ".local/target.env"))' "$SINK_PARAMS")"`,
+    `PUSHURL="$(python3 -c 'import json,sys; print(json.loads(sys.argv[1]).get("pushurl") or "")' "$SINK_PARAMS")"`,
+    `PROJECT_ID="$(python3 -c 'import json,sys; print(json.loads(sys.argv[1]).get("project_id") or "")' "$SINK_PARAMS")"`,
+    "",
+    "CONFIRM=0",
+    'RUN_DIR=""',
+    'for arg in "$@"; do',
+    '  case "$arg" in',
+    "    --confirm) CONFIRM=1 ;;",
+    '    -*) echo "unknown flag: $arg" >&2; exit 2 ;;',
+    '    *) RUN_DIR="$arg" ;;',
+    "  esac",
+    "done",
+    "",
+    'if [ -z "$RUN_DIR" ]; then',
+    '  echo "usage: bin/upload.sh [--confirm] <runs/<run-id>>" >&2',
+    "  exit 2",
+    "fi",
+    "",
+    "# .local/target.env is optional: the package may record the target itself.",
+    "# Env values still win as explicit overrides (the documented fallback).",
+    'if [ -f "$ENV_FILE" ]; then set -a; . "$ENV_FILE"; set +a; fi',
+    '[ -z "$PROJECT_ID" ] && PROJECT_ID="${AE_PROJECT_ID:-}"',
+    "",
+    "# Endpoint: the recorded pushurl (a receiver base URL; append /sync_json), else AE_ENDPOINT.",
+    'if [ -n "$PUSHURL" ]; then',
+    '  case "$PUSHURL" in',
+    '    */sync_json) ENDPOINT="$PUSHURL" ;;',
+    '    *) ENDPOINT="${PUSHURL%/}/sync_json" ;;',
+    "  esac",
+    "else",
+    '  : "${AE_ENDPOINT:?set AE_ENDPOINT in .local/target.env (or record pushurl at handoff)}"',
+    '  ENDPOINT="$AE_ENDPOINT"',
+    "fi",
+    "",
+    "# APPID: explicit env wins, else derive from the recorded project via project info get.",
+    'APPID="${AE_APPID:-}"',
+    'if [ -z "$APPID" ] && [ -n "$PROJECT_ID" ]; then',
+    '  APPID="$(python3 bin/resolve_appid.py "$PROJECT_ID")"',
+    "fi",
+    ': "${APPID:?set AE_APPID in .local/target.env (or record project_id at handoff)}"',
+    "",
+    "# Mask the APPID in anything this script prints \u2014 it must never land in logs.",
+    "mask() {",
+    '  local a="$1"',
+    '  if [ "${#a}" -le 4 ]; then printf "%s" "****"; return; fi',
+    '  printf "%s%s" "$(printf "%*s" "$(( ${#a} - 4 ))" "" | tr " " "*")" "${a: -4}"',
+    "}",
+    "display_args() {",
+    '  local args=("$@") out=() i',
+    "  for ((i=0; i<${#args[@]}; i++)); do",
+    '    if [ "${args[$i]}" = "--appid" ] && [ -n "${args[$((i+1))]:-}" ]; then',
+    '      out+=("--appid" "$(mask "${args[$((i+1))]}")")',
+    "      i=$((i+1))",
+    "    else",
+    '      out+=("${args[$i]}")',
+    "    fi",
+    "  done",
+    '  printf "%s\\n" "${out[*]}"',
+    "}",
+    "",
+    'echo "target: project_id=${PROJECT_ID:-<unset>}"',
+    'echo "        endpoint=$ENDPOINT"',
+    'echo "        appid=$(mask "$APPID")"',
+    'if [ "$CONFIRM" -eq 0 ]; then',
+    '  echo "dry-run \u2014 re-run with --confirm to upload to this address and project."',
+    "else",
+    '  echo "confirmed: uploading to the address and project shown above."',
+    "fi",
+    "",
+    'FLAGS=(--endpoint "$ENDPOINT" --appid "$APPID" --batch-size "$BATCH_SIZE")',
+    'if [ "$CONFIRM" -eq 0 ]; then FLAGS+=(--dry-run); fi',
+    "",
+    "while IFS= read -r ref; do",
+    '  ref_dir="$(dirname "$ref")"',
+    '  ue="$RUN_DIR/$ref_dir/valid.ue.jsonl"',
+    '  manifest="$RUN_DIR/$ref_dir/manifest.json"',
+    '  if [ ! -f "$ue" ]; then',
+    '    echo "missing $ue (run bin/run.sh first)" >&2',
+    "    exit 2",
+    "  fi",
+    `  status="$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1]))["status"])' "$manifest")"`,
+    '  args=("${FLAGS[@]}" --ue-file "$ue" --manifest "$manifest")',
+    '  if [ "$status" = "blocked" ]; then',
+    '    echo "manifest $manifest is blocked (rows were quarantined)."',
+    '    echo "Uploading passes only the valid subset (--allow-clean-subset); quarantined rows stay in invalid.rows.jsonl."',
+    '    if [ "$CONFIRM" -eq 1 ]; then args+=(--allow-clean-subset); else echo "  (dry-run) re-run with --confirm to accept the clean subset."; fi',
+    "  fi",
+    '  echo "> ae-cli data-integration upload $(display_args "${args[@]}")"',
+    '  ae-cli data-integration upload "${args[@]}" || exit $?',
+    `done < <(python3 -c 'import json,sys; print("\\n".join(json.load(open("pipeline.json"))["transform"]["refs"]))')`
+  );
+}
+function bindMappingPy() {
+  return `#!/usr/bin/env python3
+"""Source stage: rebind the frozen mappings to a new same-shape file.
+
+Runs \`ae-cli data-integration inspect\` once, then for every mapping the
+pipeline references (pipeline.json's transform.refs) re-binds the frozen
+mapping's \`source.sha256\` and \`source.data_set\` to the new file (identity
+fields only \u2014 business logic is untouched), after checking the column set
+against shape.json. Historical index entries the pipeline does not run are
+left alone \u2014 the index accumulates across handoffs in the same directory.
+
+Usage: bin/bind_mapping.py <input-file> <run-dir>
+"""
+import json
+import os
+import subprocess
+import sys
+
+
+def fail(message):
+    print(f"bind_mapping: {message}", file=sys.stderr)
+    sys.exit(1)
+
+
+def pkg_root():
+    return os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+
+def load_json(path):
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def write_json(path, value):
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(value, f, ensure_ascii=False, indent=2)
+        f.write("\\n")
+
+
+def dataset_key(dataset):
+    return dataset.get("id") or dataset.get("label") or ""
+
+
+def main():
+    if len(sys.argv) != 3:
+        fail("usage: bind_mapping.py <input-file> <run-dir>")
+    input_file, run_dir = sys.argv[1], sys.argv[2]
+    root = pkg_root()
+
+    pipeline = load_json(os.path.join(root, "pipeline.json"))
+    if pipeline["source"]["type"] != "local_file":
+        fail(f"unsupported source type: {pipeline['source']['type']}")
+
+    index = load_json(os.path.join(root, "index.json"))
+    shape = load_json(os.path.join(root, "shape.json"))
+    shape_by_fp = {entry["fingerprint"]: entry for entry in shape["entries"]}
+    index_by_ref = {entry["mapping_file"]: entry for entry in index["entries"]}
+
+    inspect = run_inspect(input_file)
+    datasets = extract_datasets(inspect)
+    headers_by_dataset = extract_headers(inspect, datasets)
+    sha = (inspect.get("source") or {}).get("sha256")
+
+    # Rebind only the mappings this pipeline runs (transform.refs). The index
+    # accumulates entries across handoffs in the same directory; earlier entries
+    # may have no shape baseline here and are never converted by run.sh, so
+    # walking the whole index would fail on them.
+    for ref in pipeline["transform"]["refs"]:
+        entry = index_by_ref.get(ref)
+        if entry is None:
+            fail(f"index entry missing for {ref}; re-run the full pipeline")
+        fingerprint = entry["fingerprint"]
+        baseline = shape_by_fp.get(fingerprint)
+        if baseline is None:
+            fail(f"shape baseline missing for {fingerprint}; re-run the full pipeline")
+        frozen = load_json(os.path.join(root, ref))
+        data_set_id = match_dataset(frozen, baseline, datasets, headers_by_dataset)
+        validate_headers(data_set_id, baseline, headers_by_dataset)
+        frozen["source"]["sha256"] = sha
+        frozen["source"]["data_set"] = data_set_id
+        out = os.path.join(root, run_dir, "bound", os.path.dirname(ref), "mapping.json")
+        write_json(out, frozen)
+        print(f"rebound {os.path.dirname(ref)} -> data_set {data_set_id!r}")
+    print("shape check passed")
+
+
+def run_inspect(input_file):
+    proc = subprocess.run(
+        ["ae-cli", "data-integration", "inspect", "--input-file", input_file],
+        capture_output=True, text=True,
+    )
+    if proc.returncode != 0:
+        fail(f"inspect failed: {proc.stderr.strip()}")
+    try:
+        parsed = json.loads(proc.stdout)
+    except json.JSONDecodeError:
+        fail("inspect returned non-JSON output")
+    # ae-cli wraps every command result in { ok, data, error }; unwrap it.
+    data = parsed.get("data") if isinstance(parsed, dict) else None
+    if not isinstance(data, dict):
+        fail("inspect returned no data payload")
+    return data
+
+
+def extract_datasets(inspect):
+    if inspect.get("selection_required"):
+        return inspect.get("data_sets") or []
+    data_set = inspect.get("data_set")
+    return [data_set] if data_set else []
+
+
+def extract_headers(inspect, datasets):
+    result = {}
+    details = inspect.get("header_details")
+    if details:
+        for dataset in datasets:
+            names = (dataset.get("label"), dataset.get("id"), dataset.get("selector"))
+            for sheet in details:
+                if sheet.get("name") in names:
+                    result[dataset_key(dataset)] = sheet.get("headers") or []
+                    break
+        return result
+    columns = inspect.get("columns")
+    if columns and datasets:
+        result[dataset_key(datasets[0])] = [column["name"] for column in columns]
+    return result
+
+
+def match_dataset(frozen, baseline, datasets, headers_by_dataset):
+    if not datasets:
+        fail("inspect reported no data sets")
+    wanted = frozen["source"]["data_set"]
+    for dataset in datasets:
+        if dataset.get("id") == wanted:
+            return dataset.get("id")
+    for dataset in datasets:
+        if dataset.get("label") == wanted:
+            return dataset.get("id")
+    baseline_cols = set(baseline.get("columns") or [])
+    if baseline_cols:
+        for dataset in datasets:
+            headers = headers_by_dataset.get(dataset_key(dataset))
+            if headers and set(headers) == baseline_cols:
+                return dataset.get("id")
+    if len(datasets) == 1:
+        return datasets[0].get("id")
+    fail(f"cannot rebind data_set {wanted!r}: no exact or header match; re-run the full pipeline")
+
+
+def validate_headers(data_set_id, baseline, headers_by_dataset):
+    baseline_cols = set(baseline.get("columns") or [])
+    if not baseline_cols:
+        return
+    headers = headers_by_dataset.get(data_set_id)
+    if headers is None:
+        return
+    if set(headers) != baseline_cols:
+        missing = sorted(baseline_cols - set(headers))
+        extra = sorted(set(headers) - baseline_cols)
+        fail(
+            f"shape mismatch for {data_set_id!r}: missing={missing} extra={extra} \u2014 "
+            "re-run the full pipeline; do not edit the frozen mapping"
+        )
+
+
+if __name__ == "__main__":
+    main()
+`;
+}
+function summarizePy() {
+  return `#!/usr/bin/env python3
+"""Transform stage summary: print valid/quarantined counts per data set."""
+import json
+import os
+import sys
+
+
+def pkg_root():
+    return os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+
+def main():
+    if len(sys.argv) != 2:
+        print("usage: summarize.py <run-dir>", file=sys.stderr)
+        sys.exit(2)
+    run_dir = sys.argv[1]
+    root = pkg_root()
+    with open(os.path.join(root, "pipeline.json"), "r", encoding="utf-8") as f:
+        pipeline = json.load(f)
+    total_valid = 0
+    total_invalid = 0
+    for ref in pipeline["transform"]["refs"]:
+        ref_dir = os.path.dirname(ref)
+        manifest_path = os.path.join(root, run_dir, ref_dir, "manifest.json")
+        if not os.path.exists(manifest_path):
+            continue
+        with open(manifest_path, "r", encoding="utf-8") as f:
+            manifest = json.load(f)
+        output = manifest["output"]
+        total_valid += output["valid_records"]
+        total_invalid += output["invalid_records"]
+        print(f"{ref_dir}: {output['valid_records']} valid / {output['invalid_records']} quarantined")
+        for reason in manifest.get("blocked_reasons") or []:
+            print(f"  - {reason}")
+    print(f"total: {total_valid} valid / {total_invalid} quarantined")
+
+
+if __name__ == "__main__":
+    main()
+`;
+}
+function planCheckPy() {
+  return `#!/usr/bin/env python3
+"""Plan gate: every event and property produced must already exist in the frozen tracking plan."""
+import json
+import os
+import sys
+
+
+def pkg_root():
+    return os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+
+def load_json(path):
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def main():
+    if len(sys.argv) != 2:
+        print("usage: plan_check.py <run-dir>", file=sys.stderr)
+        sys.exit(2)
+    run_dir = sys.argv[1]
+    root = pkg_root()
+    pipeline = load_json(os.path.join(root, "pipeline.json"))
+    new_events = []
+    new_properties = []
+    missing_plans = []
+    for ref in pipeline["transform"]["refs"]:
+        ref_dir = os.path.dirname(ref)
+        plan_path = os.path.join(root, ref_dir, "plan.json")
+        ue_path = os.path.join(root, run_dir, ref_dir, "valid.ue.jsonl")
+        if not os.path.exists(plan_path):
+            missing_plans.append(ref_dir)
+            continue
+        plan = load_json(plan_path)
+        plan_events = {event["event_name"] for event in plan.get("events", [])}
+        plan_properties = {prop["name"] for prop in plan.get("event_properties", [])}
+        plan_properties |= {prop["name"] for prop in plan.get("common_event_properties", [])}
+        plan_properties |= {prop["name"] for prop in plan.get("user_properties", [])}
+        produced_events = set()
+        produced_properties = set()
+        if os.path.exists(ue_path):
+            with open(ue_path, "r", encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    record = json.loads(line)
+                    if record.get("#event_name"):
+                        produced_events.add(record["#event_name"])
+                    props = record.get("properties")
+                    if isinstance(props, dict):
+                        for key in props:
+                            if key.startswith("#"):
+                                continue
+                            produced_properties.add(key)
+        new_events.extend(sorted(produced_events - plan_events))
+        new_properties.extend(sorted(produced_properties - plan_properties))
+    if missing_plans:
+        print("no plan.json in package for: " + ", ".join(missing_plans), file=sys.stderr)
+        print("run the Tracking plan step first \u2014 the plan gate cannot be skipped", file=sys.stderr)
+        sys.exit(3)
+    if new_events:
+        print("new events not in the plan: " + ", ".join(new_events), file=sys.stderr)
+        sys.exit(3)
+    if new_properties:
+        print("new properties not in the plan: " + ", ".join(new_properties), file=sys.stderr)
+        sys.exit(3)
+    print("plan coverage ok")
+
+
+if __name__ == "__main__":
+    main()
+`;
+}
+function verifyPy() {
+  return `#!/usr/bin/env python3
+"""Persistence consistency check: submit-window counts vs the platform summary.
+
+A soft check, not a hard gate. It computes what this run submitted from the local
+UE output (knowable), snapshots \`ae-cli tracking ingest summary\` over the submit
+window before and after upload, and prints both next to the expected counts. It
+does NOT parse the summary payload into per-event numbers: the capability's data
+shape is server-defined and not a stable CLI contract, and a shared project cannot
+attribute the window delta to this import alone. For a hard per-event SQL judge,
+overlay a project custom layer (see custom-layer.md in the ae-data-integration skill).
+
+  verify.py <run-dir> --baseline    snapshot the summary before upload
+  verify.py <run-dir> --check       snapshot again and diff against the baseline
+"""
+import json
+import os
+import subprocess
+import sys
+
+
+def pkg_root():
+    return os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+
+def load_json(path):
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def visit_window(record, lo, hi):
+    raw = record.get("#time")
+    if not isinstance(raw, str) or len(raw) < 19:
+        return lo, hi
+    stamp = raw[:19]  # YYYY-MM-DD HH:mm:ss
+    if lo is None or stamp < lo:
+        lo = stamp
+    if hi is None or stamp > hi:
+        hi = stamp
+    return lo, hi
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("usage: verify.py <run-dir> [--baseline|--check]", file=sys.stderr)
+        sys.exit(2)
+    run_dir = sys.argv[1]
+    mode = sys.argv[2] if len(sys.argv) > 2 else "--check"
+    if mode not in ("--baseline", "--check"):
+        print("usage: verify.py <run-dir> [--baseline|--check]", file=sys.stderr)
+        sys.exit(2)
+    root = pkg_root()
+    pipeline = load_json(os.path.join(root, "pipeline.json"))
+    project_id = pipeline["sink"]["params"].get("project_id") or os.environ.get("AE_PROJECT_ID") or "1"
+
+    expected_events = {}
+    expected_users = 0
+    lo = hi = None
+    for ref in pipeline["transform"]["refs"]:
+        ue = os.path.join(root, run_dir, os.path.dirname(ref), "valid.ue.jsonl")
+        if not os.path.exists(ue):
+            continue
+        with open(ue, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                record = json.loads(line)
+                if record.get("#type") == "track" and record.get("#event_name"):
+                    expected_events[record["#event_name"]] = expected_events.get(record["#event_name"], 0) + 1
+                else:
+                    expected_users += 1
+                lo, hi = visit_window(record, lo, hi)
+
+    if lo is None:
+        print("verify: no UE records found in " + run_dir, file=sys.stderr)
+        sys.exit(2)
+
+    def run_summary():
+        proc = subprocess.run(
+            ["ae-cli", "tracking", "ingest", "summary",
+             "-p", str(project_id), "--start-time", lo, "--end-time", hi],
+            capture_output=True, text=True,
+        )
+        if proc.returncode != 0:
+            return {"error": (proc.stderr or proc.stdout).strip()[:500]}
+        try:
+            return json.loads(proc.stdout)
+        except json.JSONDecodeError:
+            return {"raw": proc.stdout.strip()[:500]}
+
+    print("window " + lo + " .. " + hi + "  project_id=" + str(project_id))
+    print("expected (this run):")
+    for event, count in sorted(expected_events.items()):
+        print("  {:<20}{:>10,}".format(event, count))
+    print("  {:<20}{:>10,}".format("<user rows>", expected_users))
+    print()
+
+    baseline_path = os.path.join(root, run_dir, "baseline.json")
+    if mode == "--baseline":
+        payload = run_summary()
+        with open(baseline_path, "w", encoding="utf-8") as f:
+            json.dump(payload, f, ensure_ascii=False, indent=2)
+        print("baseline recorded: " + baseline_path)
+        print("platform summary (before):")
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+        sys.exit(0)
+
+    if not os.path.exists(baseline_path):
+        print("no baseline.json \u2014 run \`verify.py <run-dir> --baseline\` before upload.", file=sys.stderr)
+        print("falling back to a single after-upload summary:", file=sys.stderr)
+        print(json.dumps(run_summary(), ensure_ascii=False, indent=2))
+        sys.exit(1)
+
+    with open(baseline_path, "r", encoding="utf-8") as f:
+        baseline = json.load(f)
+    after = run_summary()
+    print("platform summary before vs after:")
+    print(json.dumps(baseline, ensure_ascii=False, indent=2))
+    print("---")
+    print(json.dumps(after, ensure_ascii=False, indent=2))
+    print()
+    print("summary changed: " + ("yes" if baseline != after else "no"))
+    print()
+    print("Boundary: the summary payload is server-defined and may under-report even")
+    print("landed data; this check surfaces it for comparison, it does not auto-verify")
+    print("per-event counts, and a shared project's window delta is not attributed to")
+    print("this import. Cross-check with:")
+    print("  ae-cli tracking live-data list -p " + str(project_id))
+    print("For a hard SQL judge, add a project custom layer (custom-layer.md).")
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()
+`;
+}
+function resolveAppidPy() {
+  return `#!/usr/bin/env python3
+"""Derive the destination APPID from \`ae-cli project info get --project-id <id>\`.
+
+\`project info get\` returns \`data.appid\` at the top level (verified against the
+AE demo host), so this helper reads that exact field and prints it to stdout. It
+prints nothing to stdout and reports the payload when the field is absent or not
+a non-empty string \u2014 the caller then falls back to AE_APPID.
+
+Usage: bin/resolve_appid.py <project-id>
+"""
+import json
+import subprocess
+import sys
+
+
+def main():
+    if len(sys.argv) != 2:
+        print("usage: resolve_appid.py <project-id>", file=sys.stderr)
+        sys.exit(2)
+    project_id = sys.argv[1]
+    proc = subprocess.run(
+        ["ae-cli", "project", "info", "get", "--project-id", project_id],
+        capture_output=True, text=True,
+    )
+    if proc.returncode != 0:
+        print("resolve_appid: project info get failed: " + (proc.stderr or proc.stdout).strip()[:300], file=sys.stderr)
+        sys.exit(0)
+    try:
+        parsed = json.loads(proc.stdout)
+    except json.JSONDecodeError:
+        print("resolve_appid: project info get returned non-JSON output", file=sys.stderr)
+        sys.exit(0)
+    data = parsed.get("data") if isinstance(parsed, dict) else None
+    appid = data.get("appid") if isinstance(data, dict) else None
+    if not isinstance(appid, str) or not appid:
+        print("resolve_appid: project info get returned no appid; set AE_APPID", file=sys.stderr)
+        print(json.dumps(data, ensure_ascii=False, indent=2) if data is not None else "{}", file=sys.stderr)
+        sys.exit(0)
+    masked = appid if len(appid) <= 4 else ("*" * (len(appid) - 4)) + appid[-4:]
+    print("resolve_appid: resolved APPID data.appid = " + masked, file=sys.stderr)
+    print(appid)
+
+
+if __name__ == "__main__":
+    main()
+`;
+}
+function generateReadme() {
+  return `# AE Data Integration \u2014 handoff package
+
+A frozen, reusable pipeline for importing a **same-shape** local file into AE,
+generated by \`ae-cli data-integration handoff\`. Source and Transform are frozen
+(the confirmed business logic); only the Tracking-plan and Sink gates still
+require human confirmation.
+
+## Quick start
+
+\`\`\`bash
+cp <today's file> inbox/
+bin/run.sh                    # shape check -> convert -> plan check (no upload)
+bin/upload.sh runs/<latest>   # dry-run
+bin/upload.sh runs/<latest> --confirm
+\`\`\`
+
+Read [RUNBOOK.md](RUNBOOK.md) for the full flow, the four confirmation gates,
+and how to verify persistence.
+
+## Handing off to an agent
+
+Import \`inbox/<today's file>\` through the ae-data-integration skill using this
+package. Tell it to follow RUNBOOK.md and stop for confirmation before uploading.
+
+## Package layout
+
+| Path | Purpose |
+| --- | --- |
+| \`pipeline.json\` | Declarative source -> transform -> sink descriptor |
+| \`index.json\` | Structure-fingerprint index (reuse matching) |
+| \`shape.json\` | Column baseline used by the shape gate |
+| \`<fingerprint16>/\` | Frozen mapping + tracking plan + transform wrapper |
+| \`bin/run.sh\` | Source + Transform + Plan executor (never uploads) |
+| \`bin/upload.sh\` | Sink executor (dry-run by default; resolves the recorded target) |
+| \`bin/verify.py\` | Soft persistence check (submit window vs ingest summary) |
+| \`bin/resolve_appid.py\` | APPID derivation helper (project info get) |
+| \`.local/target.env\` | Upload target overrides (APPID / endpoint); only the template ships |
+| \`inbox/\` \`runs/\` | Daily input / per-run outputs |
+
+## Safety
+
+The package records at most a destination \`pushurl\` and \`project_id\` (no APPID,
+tokens, or raw data values). \`bin/upload.sh\` always requires \`--confirm\` before
+sending, so the operator re-confirms the address and project on every reuse. Copy
+\`.local/target.env.example\` to \`.local/target.env\` for explicit overrides and
+never commit it.
+`;
+}
+function generateRunbook() {
+  return `# RUNBOOK \u2014 same-shape file import
+
+Run this when a file of the **same shape** arrives again (same sheets and
+headers as \`shape.json\`). If the headers changed, stop: re-run the full
+ae-data-integration pipeline instead of editing the frozen mapping.
+
+## Gates
+
+1. **Shape gate** \u2014 \`bin/run.sh\` rebinds the frozen mappings to the new file
+   and compares the column set against \`shape.json\`. A mismatch fails fast on
+   purpose: a different shape means the frozen business logic was never reviewed
+   for it.
+2. **Transform** \u2014 each frozen mapping runs through
+   \`ae-cli data-integration convert\`. Quarantined rows land in
+   \`invalid.rows.jsonl\`; they are never silently dropped.
+3. **Tracking-plan gate** \u2014 \`bin/run.sh\` verifies every produced event and
+   property already exists in the frozen \`plan.json\`. New events or properties
+   make it exit with code 3: merge them into the project tracking plan first,
+   then return here to upload.
+4. **Sink gate** \u2014 \`bin/upload.sh\` is dry-run by default. Read
+   \`record_count\`, \`batch_count\`, and \`manifest_status\` before adding
+   \`--confirm\`. A \`blocked\` manifest means rows were quarantined;
+   \`--confirm\` then uploads only the valid subset (\`--allow-clean-subset\`).
+
+## Destination
+
+The package records the destination it was handed off for when \`handoff\` was run
+with \`--pushurl\` / \`--project-id\` (see \`pipeline.json\` \u2192 \`sink.params\`). Reuse
+defaults to that target, but \`bin/upload.sh\` never sends without \`--confirm\`, so
+the operator re-confirms the address and project every time.
+
+Resolution order at upload time:
+
+- endpoint: recorded \`pushurl\` (+ \`/sync_json\`), else \`AE_ENDPOINT\`.
+- APPID: \`AE_APPID\`, else derived via \`ae-cli project info get --project-id <id>\`
+  (see \`bin/resolve_appid.py\`; it reads the \`data.appid\` field \u2014 set \`AE_APPID\`
+  when that field is absent).
+- project id: recorded \`project_id\`, else \`AE_PROJECT_ID\`.
+
+\`.local/target.env\` remains the explicit override for all three:
+\`AE_ENDPOINT\` (full receiver URL ending in \`/sync_json\`), \`AE_APPID\`, \`AE_PROJECT_ID\`.
+
+## Verify persistence
+
+\`receiver_accepted\` is not persistence. About a minute after upload, confirm
+the data landed with ae-cli. The package ships a soft check that automates the
+before/after comparison:
+
+\`\`\`bash
+bin/verify.py runs/<run-id> --baseline   # before upload
+bin/upload.sh runs/<run-id> --confirm
+bin/verify.py runs/<run-id> --check      # after upload
+\`\`\`
+
+\`bin/verify.py\` prints the submit window and expected counts, then shows the
+\`tracking ingest summary\` payload before and after for comparison. It does not
+auto-verify per-event counts \u2014 the summary shape is server-defined, and a shared
+project's window delta is not attributed to this import. Cross-check with:
+
+\`\`\`bash
+ae-cli tracking live-data list -p <AE_PROJECT_ID>
+ae-cli tracking ingest-error list -p <AE_PROJECT_ID> --data-name <name>
+\`\`\`
+
+For a hard per-event SQL judge, overlay a project custom layer instead of editing
+this package (see \`custom-layer.md\` in the ae-data-integration skill).
+
+## Interrupted uploads
+
+If a batch times out or loses the network, that batch's state is unknown. Stop:
+verify what actually landed, then follow the ae-data-integration skill to resume
+from the verified offset. Never re-run the whole upload blindly.
+
+## Files
+
+See \`README.md\` for the package layout.
+`;
+}
+function generateEnvTemplate() {
+  return [
+    "# Upload target overrides. Copy this file to .local/target.env and fill only",
+    "# what the package does not already record (pipeline.json sink.params).",
+    "# AE_ENDPOINT: a full receiver URL ending in /sync_json (used when no pushurl is recorded).",
+    "# AE_APPID: the destination project APPID (overrides the project info get derivation).",
+    "# AE_PROJECT_ID: the destination project ID, used when no project_id is recorded.",
+    "AE_ENDPOINT=",
+    "AE_APPID=",
+    "AE_PROJECT_ID=",
+    ""
+  ].join("\n");
+}
+function generateGitignore() {
+  return ["inbox/", "runs/", ".local/target.env", ""].join("\n");
+}
+
+// src/commands/data-integration/handoff.ts
 var HANDOFF_INDEX_VERSION = "ae-data-integration-index/v1";
 var HANDOFF_DIR_LEN = 16;
 function structureFingerprint(mapping) {
   const canonical = {
     mode: mapping.mode,
-    time_field: mapping.time.field,
-    account_id_field: mapping.account_id_field ?? null,
-    distinct_id_field: mapping.distinct_id_field ?? null,
-    record_type_field: mapping.record_type_field ?? null,
-    event_name_field: mapping.event_name_field ?? null,
-    columns: mapping.properties.map((property) => ({ source: property.source, type: property.type })).sort((left, right) => left.source.localeCompare(right.source)),
-    excluded: [...mapping.exclude_columns ?? []].sort()
+    format: mapping.source.format,
+    columns: sourceColumns(mapping)
   };
   return createHash3("sha256").update(JSON.stringify(canonical)).digest("hex");
 }
@@ -3262,17 +5337,17 @@ function upsertIndexEntry(index, entry) {
 function buildHandoffPackage(outDir, mapping, planFile) {
   const fingerprint = structureFingerprint(mapping);
   const dirName = fingerprint.slice(0, HANDOFF_DIR_LEN);
-  const handoffDir = join2(outDir, dirName);
-  const indexPath = join2(outDir, "index.json");
+  const handoffDir = join3(outDir, dirName);
+  const indexPath = join3(outDir, "index.json");
   const index = readHandoffIndex(indexPath);
   const reusedExisting = index.entries.some((item) => item.fingerprint === fingerprint);
   mkdirSync2(handoffDir, { recursive: true, mode: 448 });
   chmodSync2(handoffDir, 448);
-  writeSecureJson2(join2(handoffDir, "mapping.json"), mapping);
-  writeSecureText2(join2(handoffDir, "transform.mjs"), createHandoffScript());
+  writeSecureJson2(join3(handoffDir, "mapping.json"), mapping);
+  writeSecureText2(join3(handoffDir, "transform.mjs"), createHandoffScript());
   let planFileRel;
   if (planFile) {
-    writeSecureJson2(join2(handoffDir, "plan.json"), readPlanFile(planFile));
+    writeSecureJson2(join3(handoffDir, "plan.json"), readPlanFile(planFile));
     planFileRel = `${dirName}/plan.json`;
   }
   const entry = {
@@ -3287,7 +5362,7 @@ function buildHandoffPackage(outDir, mapping, planFile) {
     ...planFileRel ? { plan_file: planFileRel } : {}
   };
   writeAtomicJson(indexPath, upsertIndexEntry(index, entry));
-  return { outDir, handoffDir, dirName, fingerprint, reusedExisting, planFile: planFileRel };
+  return { outDir, handoffDir, dirName, fingerprint, reusedExisting, planFile: planFileRel, entry };
 }
 function readHandoffIndex(path) {
   let raw;
@@ -3382,56 +5457,199 @@ var dataIntegrationHandoff = {
   service: "data-integration",
   command: "handoff",
   usesAeHost: false,
-  description: "Export a reusable handoff package (frozen mapping + transform script + plan reference) under .ae-data-integration/.",
+  description: "Export a reusable handoff package (pipeline descriptor + frozen mappings + stage executors + docs) and a shareable zip.",
   flags: [
-    { name: "mapping", type: "string", required: true, sensitive: true, desc: "Confirmed ae-local-data-mapping/v1 JSON, file path, or @file." },
+    { name: "mapping", type: "string", required: true, variadic: true, sensitive: true, desc: `Confirmed ${MAPPING_VERSION} JSON, file path, or @file. Repeat for multiple data sets (one sheet each).` },
     { name: "plan-file", type: "string", sensitive: true, desc: "Tracking-plan draft.json to reference inside the handoff package." },
-    { name: "out-dir", type: "string", sensitive: true, desc: "Handoff root directory. Default: .ae-data-integration." }
+    { name: "out-dir", type: "string", sensitive: true, desc: "Handoff root directory. Default: .ae-cli/data-integration (project workspace)." },
+    { name: "pushurl", type: "string", sensitive: true, desc: "Receiver base URL to record as the reuse upload target (sink endpoint = pushurl + /sync_json). Reuse still requires --confirm." },
+    { name: "project-id", type: "string", sensitive: true, desc: "Numeric destination project ID to record; upload derives the APPID from it via project info get." }
   ],
   risk: "write",
   dryRun: async (ctx) => {
-    const mapping = readLocalDataMapping(ctx.str("mapping"));
-    const outDir = resolve3(ctx.str("out-dir").trim() || ".ae-data-integration");
+    const mappings = ctx.list("mapping").map((source) => readLocalDataMapping(source));
+    const outDir = resolve3(ctx.str("out-dir").trim() || join3(".ae-cli", "data-integration"));
     const planFile = ctx.str("plan-file").trim() || void 0;
+    const pushurl = ctx.str("pushurl").trim() || void 0;
+    const projectId = ctx.str("project-id").trim() || void 0;
+    const fingerprints = mappings.map(structureFingerprint);
     return {
       action: "handoff_local_data",
       out_dir: outDir,
-      fingerprint: structureFingerprint(mapping),
-      source_sha256: mapping.source.sha256,
-      mode: mapping.mode,
-      property_count: mapping.properties.length,
-      files: ["mapping.json", "transform.mjs", ...planFile ? ["plan.json"] : []],
-      index_file: join2(outDir, "index.json")
+      mapping_count: mappings.length,
+      fingerprints,
+      target: { pushurl, project_id: projectId },
+      files: handoffFileList(fingerprints, planFile),
+      index_file: join3(outDir, "index.json"),
+      pipeline_file: join3(outDir, "pipeline.json"),
+      shape_file: join3(outDir, "shape.json"),
+      zip_path: zipPathFor(outDir, fingerprints[0])
     };
   },
   execute: async (ctx) => {
-    const mapping = readLocalDataMapping(ctx.str("mapping"));
-    const outDir = resolve3(ctx.str("out-dir").trim() || ".ae-data-integration");
+    const mappings = ctx.list("mapping").map((source) => readLocalDataMapping(source));
+    const outDir = resolve3(ctx.str("out-dir").trim() || join3(".ae-cli", "data-integration"));
     const planFile = ctx.str("plan-file").trim() || void 0;
-    const build = buildHandoffPackage(outDir, mapping, planFile);
+    const target = {
+      pushurl: ctx.str("pushurl").trim() || void 0,
+      project_id: ctx.str("project-id").trim() || void 0
+    };
+    const items = mappings.map((mapping) => ({
+      mapping,
+      build: buildHandoffPackage(outDir, mapping, planFile)
+    }));
+    const entries = items.map((item) => item.build.entry);
+    const relayFiles = [
+      { relPath: "pipeline.json", content: `${JSON.stringify(buildPipelineDescriptor(entries, target), null, 2)}
+`, mode: 384 },
+      { relPath: "shape.json", content: `${JSON.stringify(buildShapeBaseline(items.map((item) => ({ mapping: item.mapping, fingerprint: item.build.fingerprint }))), null, 2)}
+`, mode: 384 },
+      ...generateBinScripts(),
+      { relPath: "README.md", content: generateReadme(), mode: 384 },
+      { relPath: "RUNBOOK.md", content: generateRunbook(), mode: 384 },
+      { relPath: ".local/target.env.example", content: generateEnvTemplate(), mode: 384 },
+      { relPath: ".gitignore", content: generateGitignore(), mode: 384 },
+      { relPath: "inbox/.gitkeep", content: "", mode: 384 },
+      { relPath: "runs/.gitkeep", content: "", mode: 384 }
+    ];
+    for (const file of relayFiles) writeRelayFile(outDir, file);
+    const zipPath = zipPathFor(outDir, entries[0].fingerprint);
+    const stagingDir = stageScopedPackage(outDir, items.map((item) => item.build), entries, relayFiles);
+    try {
+      await zipPackage(stagingDir, zipPath);
+      chmodSync2(zipPath, 384);
+    } finally {
+      rmSync(stagingDir, { recursive: true, force: true });
+    }
     return {
-      out_dir: build.outDir,
-      handoff_dir: build.handoffDir,
-      fingerprint: build.fingerprint,
-      mapping_file: `${build.dirName}/mapping.json`,
-      ...build.planFile ? { plan_file: build.planFile } : {},
-      run: `node ${join2(build.handoffDir, "transform.mjs")} <new-input-file> [<output-dir>]`,
-      index_file: join2(outDir, "index.json"),
-      reused_existing: build.reusedExisting
+      out_dir: outDir,
+      zip_path: zipPath,
+      pipeline_file: join3(outDir, "pipeline.json"),
+      shape_file: join3(outDir, "shape.json"),
+      index_file: join3(outDir, "index.json"),
+      handoff_dirs: items.map((item) => item.build.dirName),
+      deliverables: buildDeliverables(outDir, relayFiles, items),
+      next_steps: [
+        `Review the pipeline descriptor and four confirmation gates: ${join3(outDir, "RUNBOOK.md")}.`,
+        `Share the archive: ${zipPath}.`,
+        `Next same-shape file: cd ${outDir} && bin/run.sh <new-file>, then bin/upload.sh runs/<run-id> --confirm.`
+      ],
+      reused_existing: items.some((item) => item.build.reusedExisting)
     };
   }
 };
+function zipPathFor(outDir, fingerprint) {
+  if (!fingerprint) return void 0;
+  return join3(dirname2(resolve3(outDir)), `ae-data-integration-handoff-${fingerprint.slice(0, 8)}.zip`);
+}
+var RELAY_FILE_PATHS = [
+  "pipeline.json",
+  "shape.json",
+  "index.json",
+  "README.md",
+  "RUNBOOK.md",
+  ".local/target.env.example",
+  ".gitignore",
+  "bin/run.sh",
+  "bin/upload.sh",
+  "bin/bind_mapping.py",
+  "bin/summarize.py",
+  "bin/plan_check.py",
+  "bin/verify.py",
+  "bin/resolve_appid.py",
+  "inbox/.gitkeep",
+  "runs/.gitkeep"
+];
+function mappingDirFiles(dirName, planFile) {
+  return [
+    `${dirName}/mapping.json`,
+    `${dirName}/transform.mjs`,
+    ...planFile ? [`${dirName}/plan.json`] : []
+  ];
+}
+function handoffFileList(fingerprints, planFile) {
+  const perMapping = fingerprints.flatMap(
+    (fingerprint) => mappingDirFiles(fingerprint.slice(0, HANDOFF_DIR_LEN), planFile)
+  );
+  return [...RELAY_FILE_PATHS, ...perMapping];
+}
+function buildDeliverables(outDir, relayFiles, items) {
+  const relay = [
+    { rel_path: "index.json", abs_path: join3(outDir, "index.json") },
+    ...relayFiles.map((file) => ({ rel_path: file.relPath, abs_path: join3(outDir, file.relPath) }))
+  ];
+  const mappings = items.flatMap(
+    (item) => mappingDirFiles(item.build.dirName, item.build.planFile).map((rel) => ({
+      rel_path: rel,
+      abs_path: join3(outDir, rel)
+    }))
+  );
+  return [...relay, ...mappings];
+}
+function writeRelayFile(outDir, file) {
+  const abs = join3(outDir, file.relPath);
+  mkdirSync2(dirname2(abs), { recursive: true, mode: 448 });
+  writeFileSync2(abs, file.content, { encoding: "utf8", mode: file.mode });
+  chmodSync2(abs, file.mode);
+}
+function stageScopedPackage(outDir, mappingDirs, entries, relayFiles) {
+  const staging = mkdtempSync(join3(tmpdir(), "ae-handoff-"));
+  writeSecureJson2(join3(staging, "index.json"), { version: HANDOFF_INDEX_VERSION, entries });
+  for (const file of relayFiles) writeRelayFile(staging, file);
+  for (const { dirName, planFile } of mappingDirs) {
+    for (const rel of mappingDirFiles(dirName, planFile)) {
+      const dest = join3(staging, rel);
+      mkdirSync2(dirname2(dest), { recursive: true, mode: 448 });
+      writeFileSync2(dest, readFileSync4(join3(outDir, rel), "utf8"), { encoding: "utf8", mode: 384 });
+      chmodSync2(dest, 384);
+    }
+  }
+  return staging;
+}
 
-// src/commands/data-integration/local-data/reuse.ts
+// src/commands/data-integration/reuse.ts
 import { readFileSync as readFileSync5 } from "fs";
-import { dirname as dirname2, join as join3, resolve as resolve4 } from "path";
+import { dirname as dirname4, join as join5, resolve as resolve5 } from "path";
+
+// src/commands/data-integration/handoff-root.ts
+import { existsSync as existsSync2 } from "fs";
+import { dirname as dirname3, join as join4, resolve as resolve4 } from "path";
+function globalHandoffDir() {
+  const home = process.env.HOME;
+  if (!home) return void 0;
+  return join4(getConfigDir(), "data-integration");
+}
+function upwardHandoffDirs(startDir) {
+  const dirs = [];
+  let current = resolve4(startDir);
+  for (; ; ) {
+    const candidate = join4(current, ".ae-cli", "data-integration");
+    if (!dirs.includes(candidate)) dirs.push(candidate);
+    const parent = dirname3(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return dirs;
+}
+function reuseSearchPaths(startDir = process.cwd()) {
+  const globalDir = globalHandoffDir();
+  return globalDir ? [...upwardHandoffDirs(startDir), globalDir] : upwardHandoffDirs(startDir);
+}
+function findReuseRoot(startDir = process.cwd()) {
+  for (const dir of upwardHandoffDirs(startDir)) {
+    if (existsSync2(join4(dir, "index.json"))) return dir;
+  }
+  return globalHandoffDir();
+}
+
+// src/commands/data-integration/reuse.ts
 function detectReuse(mapping, outDir) {
   const fingerprint = structureFingerprint(mapping);
-  const indexPath = join3(outDir, "index.json");
+  const indexPath = join5(outDir, "index.json");
   const index = readHandoffIndex(indexPath);
   const entry = index.entries.find((item) => item.fingerprint === fingerprint);
   if (!entry) return { matched: false, fingerprint, index_file: indexPath };
-  const mappingPath = join3(outDir, entry.mapping_file);
+  const mappingPath = join5(outDir, entry.mapping_file);
   const match = {
     fingerprint: entry.fingerprint,
     created_at: entry.created_at,
@@ -3442,7 +5660,7 @@ function detectReuse(mapping, outDir) {
     mapping_file: entry.mapping_file,
     ...entry.plan_file ? { plan_file: entry.plan_file } : {},
     ...readFrozenEventName(mappingPath),
-    run: `node ${join3(outDir, dirname2(entry.mapping_file), "transform.mjs")} <new-input-file> [<output-dir>]`
+    run: `node ${join5(outDir, dirname4(entry.mapping_file), "transform.mjs")} <new-input-file> [<output-dir>]`
   };
   return { matched: true, fingerprint, index_file: indexPath, match };
 }
@@ -3465,29 +5683,41 @@ var dataIntegrationReuse = {
   service: "data-integration",
   command: "reuse",
   usesAeHost: false,
-  description: "Match a candidate mapping against the .ae-data-integration/ handoff index and propose a reusable package.",
+  description: "Match a candidate mapping against the .ae-cli/data-integration/ handoff index and propose a reusable package.",
   flags: [
-    { name: "mapping", type: "string", required: true, sensitive: true, desc: "Candidate ae-local-data-mapping/v1 JSON, file path, or @file (typically inspect recommended_mapping)." },
-    { name: "out-dir", type: "string", sensitive: true, desc: "Handoff root directory. Default: .ae-data-integration." }
+    { name: "mapping", type: "string", required: true, sensitive: true, desc: `Candidate ${MAPPING_VERSION} JSON, file path, or @file (typically inspect recommended_mapping).` },
+    { name: "out-dir", type: "string", sensitive: true, desc: "Handoff root directory. Default: nearest .ae-cli/data-integration/ upward from cwd, then ~/.ae-cli/data-integration/." }
   ],
   risk: "read",
   dryRun: async (ctx) => {
     const mapping = readLocalDataMapping(ctx.str("mapping"));
-    const outDir = resolve4(ctx.str("out-dir").trim() || ".ae-data-integration");
+    const outDir = resolveReuseOutDir(ctx);
     const result = detectReuse(mapping, outDir);
     return {
       action: "reuse_detect",
       fingerprint: result.fingerprint,
       matched: result.matched,
-      index_file: result.index_file
+      index_file: result.index_file,
+      searched_paths: searchedIndexPaths(ctx)
     };
   },
   execute: async (ctx) => {
     const mapping = readLocalDataMapping(ctx.str("mapping"));
-    const outDir = resolve4(ctx.str("out-dir").trim() || ".ae-data-integration");
-    return detectReuse(mapping, outDir);
+    const outDir = resolveReuseOutDir(ctx);
+    const result = detectReuse(mapping, outDir);
+    return { ...result, searched_paths: searchedIndexPaths(ctx) };
   }
 };
+function resolveReuseOutDir(ctx) {
+  const explicit = ctx.str("out-dir").trim();
+  if (explicit) return resolve5(explicit);
+  return findReuseRoot() ?? resolve5(join5(".ae-cli", "data-integration"));
+}
+function searchedIndexPaths(ctx) {
+  const explicit = ctx.str("out-dir").trim();
+  const dirs = explicit ? [resolve5(explicit)] : reuseSearchPaths();
+  return dirs.map((dir) => join5(dir, "index.json"));
+}
 
 // src/commands/data-integration/index.ts
 var commands = [dataIntegrationInspect, dataIntegrationPlan, dataIntegrationConvert, dataIntegrationUpload, dataIntegrationHandoff, dataIntegrationReuse];