@oxygen-agent/cli 1.1014.136 → 1.1014.619

package/dist/commands/tables.js

@@ -0,0 +1,3505 @@
+import { asPayloadRecord, emitCliFailure, emitSuccess, writeJson } from "../cli-output.js";
+import { parseJsonObject, readJsonObjectOption, readNonNegativeInt, readPositiveInt, readRecordString } from "../cli-values.js";
+import { CADENCE_FLAG_DESCRIPTION, ansi, collectRepeatable, formatRows, normalizeExportRowsFormat, parseJsonArray, parseJsonValue, readCount, readCsvOption, readFileIfPresent, readFilterJsonOption, readFormulaValuesOption, readPositiveNumber, readRecord, splitCommaList, tableWebhookDeliveriesPath, writeListCapNotice } from "../command-support.js";
+import { addContractFlags, readContractFlags } from "../contract-flags.js";
+import { defaultApiUrl } from "../credentials.js";
+import { oxygenAppUrl } from "../help.js";
+import { requestOxygen } from "../http-client.js";
+import { writeExclusiveJson } from "../json-output.js";
+import { STREAMED_FILE_IMPORT_MIN_BYTES, putImportFileStream, rowsForStreamedImportTarget, scanStreamedImportFile, shouldStreamFileImport } from "../streamed-file-import.js";
+import { isRecord, readOption } from "../util.js";
+import { chunk } from "@oxygen/shared/array-utils";
+import { OxygenError, success } from "@oxygen/shared/cli-result";
+import { PIPEDRIVE_CATALOG_QUERY_CONTRACT, pipedriveCatalogQueryParams } from "@oxygen/shared/contracts/pipedrive-catalog";
+import { TABLE_LIST_QUERY_CONTRACT, tableListQueryParams } from "@oxygen/shared/contracts/table-list";
+import { TABLE_QUERY_GRID_CONTRACT } from "@oxygen/shared/contracts/table-query-grid";
+import { TABLE_QUERY_CLI_DEFAULT_LIMIT, TABLE_QUERY_CLI_DEFAULT_MAX_CHARS, tableQueryRawResultFits, tableQueryRawRecovery } from "@oxygen/shared/contracts/table-query-raw";
+import { MAX_BUFFERED_IMPORT_PARSE_BYTES, assertImportFormatWithinBufferedLimit, dropBlankImportCells, inferImportColumnLabels, inferRowsFileFormat, normalizeImportColumnKey, normalizeRowsForNewTable, normalizeRowsFormat, parseRowsFileBuffer } from "@oxygen/shared/file-import";
+import { PUBLIC_WEBHOOK_INGRESS_PER_TARGET_PER_MINUTE } from "@oxygen/shared/plan-band";
+import { MAX_CLI_JSON_BODY_BYTES, PLAN_LIMITS } from "@oxygen/shared/plan-limits";
+import { FILTER_TREE_OPERATORS } from "@oxygen/shared/table-filter-operators";
+import { Command, Option } from "commander";
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, createReadStream, createWriteStream, existsSync, openSync, readFileSync, readSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { stdout as output } from "node:process";
+import { createInterface } from "node:readline/promises";
+const LARGE_IMPORT_BACKGROUND_ROW_THRESHOLD = 500;
+const SAFE_IMPORT_WRITE_BATCH_SIZE = 500;
+// The only numbers on `tables import --help` used to be --batch-size (a
+// per-request chunk) and the background threshold, so users read 500 as a
+// per-file cap. Echo the shared row ceiling and the tiered byte ceilings instead
+// of restating either as a chunk-size constraint.
+// Webhook ingress scales with plan size (repricing 2026-09, decision L4.4).
+const TABLE_WEBHOOK_RATE_HELP = `${PUBLIC_WEBHOOK_INGRESS_PER_TARGET_PER_MINUTE.free.toLocaleString("en-US")}–${PUBLIC_WEBHOOK_INGRESS_PER_TARGET_PER_MINUTE["1999"].toLocaleString("en-US")} requests a minute by plan size, per endpoint and sender IP; 429 returns Retry-After; \`oxygen limits show\` lists yours`;
+const IMPORT_FILE_LIMIT_HELP = `Per-file row limit: your plan's rows-per-Table limit, since one file can fill an empty Table (\`oxygen limits show\` lists it for every plan size). File-size limit: ${formatImportFileSizeLimit("free")} on free, ${formatImportFileSizeLimit("starter")} on $49-$99, ${formatImportFileSizeLimit("pro")} on $199-$499, ${formatImportFileSizeLimit("scale")} on $999 and up. JSON and XLSX are read whole, so they stop at ${formatImportByteSize(MAX_BUFFERED_IMPORT_PARSE_BYTES)}; save a larger file as CSV or JSONL. Files over ${formatImportByteSize(STREAMED_FILE_IMPORT_MIN_BYTES)} upload straight from disk and always load in the background.`;
+function linkBar(coverage, width = 36) {
+    const filled = Math.max(0, Math.min(width, Math.round(coverage * width)));
+    return `[${"#".repeat(filled)}${"-".repeat(width - filled)}]`;
+}
+function writeTableLinkPreview(table, data, options) {
+    const out = (line = "") => process.stdout.write(`${line}\n`);
+    // Undo has no plan to render — just the count and what it touched.
+    if (typeof data.edges_to_archive === "number" || typeof data.archived_edge_count === "number") {
+        if (typeof data.archived_edge_count === "number") {
+            out(`Undone — ${data.archived_edge_count.toLocaleString()} links archived.`);
+            out("Links are archived, not deleted, and only the ones that run created were touched.");
+        }
+        else {
+            out(`This will archive ${(data.edges_to_archive ?? 0).toLocaleString()} links created by that run.`);
+            out(`Apply:  oxygen tables link ${table} --undo ${readOption(options.undo) ?? "<run_id>"} --approved`);
+        }
+        if (data.web_url)
+            out(data.web_url);
+        return;
+    }
+    const blockers = data.blockers ?? [];
+    if (blockers.length > 0) {
+        for (const blocker of blockers)
+            out(blocker.message ?? blocker.code ?? "This link cannot run yet.");
+        if (data.web_url)
+            out(data.web_url);
+        return;
+    }
+    // Approved run: it is queued, so print how to watch it, not the plan again.
+    // The two follow-ups take DIFFERENT ids and that is not cosmetic — undo
+    // archives by edge run_id, which is the parent workspace run.
+    const watchId = data.action_run_id ?? data.workspace_run_id;
+    const undoId = data.workspace_run_id;
+    if (!data.dry_run && watchId) {
+        out(`Linking rows in the background.`);
+        if (data.web_url)
+            out(`Run:    ${data.web_url}`);
+        out(`Watch:  oxygen table-runs wait ${watchId}`);
+        if (undoId)
+            out(`Undo:   oxygen tables link ${table} --undo ${undoId}`);
+        return;
+    }
+    const chosen = data.chosen ?? null;
+    const sourceLabel = data.source?.tableLabel ?? table;
+    const targetLabel = data.target?.tableLabel ?? readOption(options.to) ?? "the other table";
+    out(`Linking "${sourceLabel}" -> "${targetLabel}"`);
+    out();
+    if (!chosen) {
+        out("  No column in these two tables matches well enough to link them.");
+        out("  Add a shared value to both — a website, a domain, a LinkedIn URL, or an email.");
+        if (data.web_url)
+            out(data.web_url);
+        return;
+    }
+    const pad = (label) => label.padEnd(14);
+    out(`  ${pad("Matching on")}${chosen.source?.columnLabel ?? "?"} -> ${chosen.target?.columnLabel ?? "?"}`);
+    if (chosen.matchExplanation)
+        out(`  ${pad("")}(${chosen.matchExplanation})`);
+    if (data.cardinalitySentence)
+        out(`  ${pad("Direction")}${data.cardinalitySentence}`);
+    const scanned = data.source?.scannedRows ?? 0;
+    const total = data.source?.rowCount ?? scanned;
+    // Always name the sample. `sampled` means the scan hit its bound, so these are
+    // estimates over a prefix of the table, not the whole thing.
+    if (data.sampled && scanned < total) {
+        out(`  ${pad("Measured on")}${scanned.toLocaleString()} of ${total.toLocaleString()} rows`);
+    }
+    else {
+        out(`  ${pad("Measured on")}all ${total.toLocaleString()} rows`);
+    }
+    out();
+    const coverage = chosen.coverage ?? 0;
+    out(`  ${linkBar(coverage)}  ${(chosen.matchedRows ?? 0).toLocaleString()} will link   ${Math.round(coverage * 100)}%`);
+    if ((chosen.ambiguousRows ?? 0) > 0) {
+        out(`  ${" ".repeat(38)}${(chosen.ambiguousRows ?? 0).toLocaleString()} ambiguous (skipped)`);
+    }
+    if ((chosen.unmatchedRows ?? 0) > 0) {
+        out(`  ${" ".repeat(38)}${(chosen.unmatchedRows ?? 0).toLocaleString()} with no match yet`);
+    }
+    out();
+    const samples = chosen.samplePairs ?? [];
+    if (samples.length > 0) {
+        for (const sample of samples.slice(0, 3))
+            out(`  matched on "${sample.key ?? ""}"`);
+        if (samples.length > 3)
+            out(`  ... ${samples.length - 3} more`);
+        out();
+    }
+    if ((chosen.ambiguousRows ?? 0) > 0) {
+        out(`  Ambiguous rows match more than one row on the other side, so they are left`);
+        out(`  unlinked rather than guessed. Fix the duplicates first:`);
+        out(`      oxygen tables dedupe ${targetLabel} --on <column>`);
+        out();
+    }
+    if ((chosen.unmatchedRows ?? 0) > 0 && !options.createMissing) {
+        out(`  Add --create-missing to create the missing target rows too (free).`);
+        out();
+    }
+    const alternatives = data.alternatives ?? [];
+    if (alternatives.length > 0) {
+        const best = alternatives[0];
+        if (best?.source?.columnLabel) {
+            out(`  Also measured: ${best.source.columnLabel} -> ${best.target?.columnLabel ?? "?"}  ${Math.round((best.coverage ?? 0) * 100)}%`);
+            out(`      retry with --on "${best.source.columnLabel}"`);
+            out();
+        }
+    }
+    if (data.relationStorage === "tables") {
+        out(`  Stored in Tables — neither table is registered as a CRM object.`);
+        out();
+    }
+    out("  Free — 0 credits. Nothing has been written.");
+    const applyFlags = [`--to ${readOption(options.to) ?? "<table>"}`];
+    if (readOption(options.on))
+        applyFlags.push(`--on "${readOption(options.on)}"`);
+    if (options.createMissing)
+        applyFlags.push("--create-missing");
+    out(`  Apply:  oxygen tables link ${table} ${applyFlags.join(" ")} --approved`);
+    if (data.web_url)
+        out(`  ${data.web_url}`);
+}
+async function readDeleteRowIdsOption(options) {
+    const rowIdsJson = readOption(options.rowIdsJson);
+    const rowIdsFile = readOption(options.rowIdsFile);
+    if (rowIdsJson && rowIdsFile) {
+        throw new OxygenError("invalid_request", "Pass either --row-ids-json or --row-ids-file, not both.", {
+            exitCode: 1,
+        });
+    }
+    if (!rowIdsJson && !rowIdsFile) {
+        throw new OxygenError("invalid_request", "Pass --row-ids-json or --row-ids-file.", {
+            exitCode: 1,
+        });
+    }
+    if (rowIdsJson)
+        return normalizeDeleteRowIds(parseJsonArray(rowIdsJson));
+    const filePath = resolve(rowIdsFile ?? "");
+    const buffer = readFileSync(filePath);
+    const format = normalizeRowsFormat(options.format, inferRowsFileFormat(filePath));
+    if (format === "json") {
+        const text = buffer.toString("utf8");
+        const inlineIds = tryParseJsonStringArray(text);
+        if (inlineIds)
+            return normalizeDeleteRowIds(inlineIds);
+        if (!options.format && !text.trimStart().startsWith("[")) {
+            return normalizeDeleteRowIds(parsePlainRowIdList(text));
+        }
+    }
+    const sheet = readOption(options.sheet);
+    const rows = await parseRowsFileBuffer(buffer, format, sheet ? { sheet } : {});
+    const rowIdColumn = readOption(options.rowIdColumn) ?? "_row_id";
+    return normalizeDeleteRowIds(rows.map((row, index) => {
+        const value = row[rowIdColumn];
+        if (typeof value !== "string" || !value.trim()) {
+            throw new OxygenError("invalid_request", `Row id column "${rowIdColumn}" must contain row UUID strings.`, {
+                details: { row_number: index + 1, column: rowIdColumn },
+                exitCode: 1,
+            });
+        }
+        return value.trim();
+    }));
+}
+function tryParseJsonStringArray(value) {
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(parsed) || !parsed.every((entry) => typeof entry === "string"))
+        return null;
+    return parsed;
+}
+function parsePlainRowIdList(value) {
+    return value
+        .split(/[\n,]/)
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+}
+function normalizeDeleteRowIds(values) {
+    const rowIds = values.map((value, index) => {
+        if (typeof value !== "string" || !value.trim()) {
+            throw new OxygenError("invalid_request", "Row IDs must be non-empty strings.", {
+                details: { index },
+                exitCode: 1,
+            });
+        }
+        return value.trim();
+    });
+    if (rowIds.length === 0) {
+        throw new OxygenError("invalid_request", "Row ID list cannot be empty.", {
+            exitCode: 1,
+        });
+    }
+    return rowIds;
+}
+function tableWebhookListPath(options) {
+    const params = new URLSearchParams();
+    const table = readOption(options.table);
+    const status = readOption(options.status);
+    const limit = readPositiveInt(options.limit);
+    if (table)
+        params.set("table", table);
+    if (status)
+        params.set("status", status);
+    if (limit)
+        params.set("limit", String(limit));
+    const query = params.toString();
+    return `/api/cli/tables/webhooks${query ? `?${query}` : ""}`;
+}
+function readTableWebhookAutoRunOptions(options) {
+    const columns = readCsvOption(options.autoRunColumns);
+    const requested = columns.length > 0
+        || options.autoRunMaxCredits !== undefined
+        || options.autoRunMaxConcurrency !== undefined
+        || Boolean(options.autoRunForce)
+        || options.autoRunConnectionId !== undefined
+        || Boolean(options.autoRunApproved);
+    if (!requested)
+        return null;
+    if (columns.length === 0) {
+        throw new OxygenError("invalid_table_webhook", "Pass --auto-run-columns when configuring webhook auto-runs.", {
+            exitCode: 1,
+        });
+    }
+    const maxCredits = readPositiveNumber(options.autoRunMaxCredits);
+    const maxConcurrency = readPositiveInt(options.autoRunMaxConcurrency);
+    return {
+        columns,
+        ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+        ...(maxConcurrency ? { max_concurrency: maxConcurrency } : {}),
+        ...(options.autoRunForce ? { force: true } : {}),
+        ...(readOption(options.autoRunConnectionId) ? { connection_id: readOption(options.autoRunConnectionId) } : {}),
+    };
+}
+// Parse a `tables promote --map` value into the wire mappings [{column, attribute}].
+// Accepts the CSV pair form `column=attribute,column2=attribute2` (LHS is the working
+// column, RHS the CRM attribute — the reverse of --bind-map's identity=column), a
+// JSON array of {column, attribute}, or a JSON object { column: attribute }.
+function parsePromoteMapOption(value) {
+    const trimmed = readOption(value);
+    if (!trimmed) {
+        throw new OxygenError("invalid_promote_map", "--map is required: column=attribute pairs or a JSON array/object.", { exitCode: 1 });
+    }
+    if (trimmed.startsWith("[") || trimmed.startsWith("{")) {
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            throw new OxygenError("invalid_promote_map", "--map JSON is not valid JSON.", { details: { value: trimmed }, exitCode: 1 });
+        }
+        const entries = Array.isArray(parsed)
+            ? parsed.map((entry) => {
+                const record = isRecord(entry) ? entry : {};
+                return {
+                    column: typeof record.column === "string" ? record.column.trim() : "",
+                    attribute: typeof record.attribute === "string" ? record.attribute.trim() : "",
+                };
+            })
+            : isRecord(parsed)
+                ? Object.entries(parsed).map(([column, attribute]) => ({ column: column.trim(), attribute: String(attribute).trim() }))
+                : [];
+        const mappings = entries.filter((mapping) => mapping.column && mapping.attribute);
+        if (mappings.length === 0) {
+            throw new OxygenError("invalid_promote_map", "--map must contain at least one column-to-attribute mapping.", { exitCode: 1 });
+        }
+        return mappings;
+    }
+    const mappings = [];
+    for (const entry of readCsvOption(value)) {
+        const separator = entry.indexOf("=");
+        if (separator <= 0 || separator === entry.length - 1) {
+            throw new OxygenError("invalid_promote_map", "--map entries must be column=attribute pairs, e.g. job_title=job_title,seniority=seniority.", { details: { entry }, exitCode: 1 });
+        }
+        mappings.push({ column: entry.slice(0, separator).trim(), attribute: entry.slice(separator + 1).trim() });
+    }
+    if (mappings.length === 0) {
+        throw new OxygenError("invalid_promote_map", "--map must contain at least one column-to-attribute mapping.", { exitCode: 1 });
+    }
+    return mappings;
+}
+// Map the hyphenated CLI policy flag to the wire enum.
+function normalizePromotePolicy(value) {
+    const normalized = (readOption(value) ?? "fill-empty-only").replace(/-/g, "_");
+    if (normalized === "fill_empty_only" || normalized === "overwrite" || normalized === "skip_conflicts") {
+        return normalized;
+    }
+    throw new OxygenError("invalid_promote_policy", "--policy must be fill-empty-only, overwrite, or skip-conflicts.", {
+        details: { policy: value },
+        exitCode: 1,
+    });
+}
+// Assemble the `tables send` request: --map pairs (headline sugar) become
+// column-copy mapping entries; --mapping JSON is the literal/path escape hatch;
+// --automap asks the server to resolve the mapping (echoed back). Exactly one
+// mapping source must be chosen, locally, so the error names CLI flags instead
+// of API fields.
+function buildTablesSendRequest(source, target, options) {
+    const mapping = parseTablesSendMapping(options);
+    if (mapping && options.automap) {
+        throw new OxygenError("invalid_send", "Pass either a mapping (--map/--mapping) or --automap, not both.", { exitCode: 1 });
+    }
+    if (!mapping && !options.automap) {
+        throw new OxygenError("invalid_send", "Pass --map target=source pairs, --mapping <json>, or --automap.", { exitCode: 1 });
+    }
+    const mode = normalizeTablesSendMode(options.mode);
+    const upsertKey = readOption(options.upsertKey);
+    if (mode === "upsert" && !upsertKey) {
+        throw new OxygenError("invalid_send", "--mode upsert requires --upsert-key <target column>.", { exitCode: 1 });
+    }
+    if (mode === "insert" && upsertKey) {
+        throw new OxygenError("invalid_send", "--upsert-key is only valid with --mode upsert.", { exitCode: 1 });
+    }
+    const flattenColumn = readOption(options.flatten);
+    const flattenPath = readOption(options.flattenPath);
+    if (flattenPath && !flattenColumn) {
+        throw new OxygenError("invalid_send", "--flatten-path requires --flatten <column>.", { exitCode: 1 });
+    }
+    const filters = parseTablesSendFilters(options.filter);
+    const pageSize = readPositiveInt(options.pageSize);
+    return {
+        source,
+        target,
+        ...(mapping ? { mapping } : {}),
+        ...(options.automap ? { automap: true } : {}),
+        ...(flattenColumn ? { flatten: { column: flattenColumn, ...(flattenPath ? { path: flattenPath } : {}) } } : {}),
+        ...(filters ? { filters } : {}),
+        mode,
+        ...(upsertKey ? { upsert_key: upsertKey } : {}),
+        ...(pageSize ? { page_size: pageSize } : {}),
+        ...(options.dryRun ? { dry_run: true } : {}),
+    };
+}
+function parseTablesSendMapping(options) {
+    const pairs = (options.map ?? []).flatMap((entry) => readCsvOption(entry));
+    const mappingJson = readOption(options.mapping);
+    if (pairs.length > 0 && mappingJson) {
+        throw new OxygenError("invalid_send", "Pass either --map pairs or --mapping <json>, not both.", { exitCode: 1 });
+    }
+    if (mappingJson) {
+        let parsed;
+        try {
+            parsed = JSON.parse(mappingJson);
+        }
+        catch {
+            throw new OxygenError("invalid_send", "--mapping is not valid JSON.", { details: { mapping: mappingJson }, exitCode: 1 });
+        }
+        if (!Array.isArray(parsed) || parsed.length === 0 || !parsed.every(isRecord)) {
+            throw new OxygenError("invalid_send", "--mapping must be a non-empty JSON array of { target, source, path? } entries.", { exitCode: 1 });
+        }
+        return parsed;
+    }
+    if (pairs.length === 0)
+        return null;
+    return pairs.map((entry) => {
+        const separator = entry.indexOf("=");
+        if (separator <= 0 || separator === entry.length - 1) {
+            throw new OxygenError("invalid_send", "--map entries must be target=source column pairs, e.g. company=company_name,website=domain.", { details: { entry }, exitCode: 1 });
+        }
+        return {
+            target: entry.slice(0, separator).trim(),
+            source: { type: "column", key: entry.slice(separator + 1).trim() },
+        };
+    });
+}
+function parseTablesSendFilters(value) {
+    const raw = readOption(value);
+    if (!raw)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new OxygenError("invalid_send", "--filter is not valid JSON.", { details: { filter: raw }, exitCode: 1 });
+    }
+    const entries = Array.isArray(parsed) ? parsed : [parsed];
+    if (entries.length === 0 || !entries.every(isRecord)) {
+        throw new OxygenError("invalid_send", "--filter must be a JSON array of { column, op, value? } objects.", { exitCode: 1 });
+    }
+    return entries;
+}
+function normalizeTablesSendMode(value) {
+    const normalized = (readOption(value) ?? "insert").toLowerCase();
+    if (normalized === "insert" || normalized === "upsert")
+        return normalized;
+    throw new OxygenError("invalid_send", "--mode must be insert or upsert.", {
+        details: { mode: value },
+        exitCode: 1,
+    });
+}
+// After a live send starts, point the terminal at the durable run's inspection
+// surfaces (stderr, so the machine-read stdout envelope stays clean).
+function writeTablesSendHint(data) {
+    if (!isRecord(data) || typeof data.ingestion_run_id !== "string")
+        return;
+    const runUrl = typeof data.run_web_url === "string" ? ` (or open ${data.run_web_url})` : "";
+    process.stderr.write(`hint: watch the copy with oxygen table-ingestions wait ${data.ingestion_run_id}${runUrl}\n`);
+}
+// Route `tables dedupe` to the preview / apply / cross-check API by flag: --against
+// switches to the read-only cross-table check (rejecting --apply); --apply targets
+// the destructive delete (approved only when --approved is set); otherwise preview.
+function buildDedupeRequest(table, options) {
+    const onColumns = readCsvOption(options.on);
+    if (onColumns.length === 0) {
+        throw new OxygenError("invalid_dedupe", "--on requires at least one column.", { exitCode: 1 });
+    }
+    const normalizer = normalizeDedupeNormalizer(options.normalize);
+    const scanLimit = readPositiveInt(options.scanLimit);
+    const against = readOption(options.against);
+    if (against) {
+        if (options.apply) {
+            throw new OxygenError("invalid_dedupe", "--apply cannot be combined with --against; the cross-table check is read-only.", { exitCode: 1 });
+        }
+        const againstColumn = readOption(options.againstColumn);
+        if (!againstColumn) {
+            throw new OxygenError("invalid_dedupe", "--against-column is required with --against.", { exitCode: 1 });
+        }
+        if (onColumns.length > 1) {
+            throw new OxygenError("invalid_dedupe", "The cross-table check matches on a single --on column.", { exitCode: 1 });
+        }
+        return {
+            endpoint: "/api/cli/tables/dedupe/cross-check",
+            body: {
+                table,
+                column: onColumns[0],
+                against_table: against,
+                against_column: againstColumn,
+                normalizer,
+                ...(scanLimit ? { scan_limit: scanLimit } : {}),
+            },
+        };
+    }
+    const keys = onColumns.map((column) => ({ column, normalizer }));
+    const keep = normalizeDedupeKeep(options.keep);
+    if (options.apply) {
+        const mergeValues = normalizeDedupeMergeValues(options.mergeValues);
+        return {
+            endpoint: "/api/cli/tables/dedupe/apply",
+            body: {
+                table,
+                keys,
+                keep,
+                ...(mergeValues ? { merge_values: mergeValues } : {}),
+                ...(scanLimit ? { scan_limit: scanLimit } : {}),
+                // --approved is the only path that deletes; without it the API 409s with the preview.
+                ...(options.approved ? { approved: true } : {}),
+            },
+        };
+    }
+    return {
+        endpoint: "/api/cli/tables/dedupe/preview",
+        body: { table, keys, keep, ...(scanLimit ? { scan_limit: scanLimit } : {}) },
+    };
+}
+// Build the standing auto-dedupe `set` body: --on columns paired positionally
+// with --normalize modes (unpaired columns default to exact). fuzzy-label maps
+// through so the API rejects it with the on-demand pointer — one source of
+// truth for the hot-path restriction.
+function buildTablesAutoDedupeSetBody(table, options) {
+    const onColumns = readCsvOption(options.on);
+    if (onColumns.length === 0) {
+        throw new OxygenError("invalid_auto_dedupe", "--on requires at least one column.", { exitCode: 1 });
+    }
+    const normalizers = readCsvOption(options.normalize);
+    const keys = onColumns.map((column, index) => ({
+        column,
+        normalizer: normalizeDedupeNormalizer(normalizers[index]),
+    }));
+    const keep = normalizeDedupeKeep(options.keep);
+    const mergeValues = normalizeDedupeMergeValues(options.mergeValues);
+    return {
+        table,
+        keys,
+        keep,
+        ...(mergeValues ? { merge_values: mergeValues } : {}),
+    };
+}
+// Map the CLI --normalize flag to the wire normalizer vocabulary.
+function normalizeDedupeNormalizer(value) {
+    const normalized = (readOption(value) ?? "exact").toLowerCase();
+    switch (normalized) {
+        case "exact":
+            return "exact";
+        case "email":
+            return "email";
+        case "domain":
+            return "domain";
+        case "linkedin":
+        case "linkedin-url":
+        case "linkedin_url":
+            return "linkedin_url";
+        case "fuzzy":
+        case "fuzzy-label":
+        case "fuzzy_label":
+            return "fuzzy_label";
+        default:
+            throw new OxygenError("invalid_dedupe_normalize", "--normalize must be exact, email, domain, linkedin, or fuzzy-label.", {
+                details: { normalize: value },
+                exitCode: 1,
+            });
+    }
+}
+function normalizeDedupeKeep(value) {
+    const normalized = (readOption(value) ?? "oldest").replace(/-/g, "_");
+    if (normalized === "oldest" || normalized === "newest" || normalized === "most_complete") {
+        return normalized;
+    }
+    throw new OxygenError("invalid_dedupe_keep", "--keep must be oldest, newest, or most-complete.", {
+        details: { keep: value },
+        exitCode: 1,
+    });
+}
+function normalizeDedupeMergeValues(value) {
+    const raw = readOption(value);
+    if (!raw)
+        return null;
+    const normalized = raw.replace(/-/g, "_");
+    if (normalized === "fill_empty")
+        return "fill_empty";
+    if (normalized === "none")
+        return null;
+    throw new OxygenError("invalid_dedupe_merge", "--merge-values must be fill-empty.", {
+        details: { merge_values: value },
+        exitCode: 1,
+    });
+}
+function readSortJsonOption(value) {
+    const raw = readOption(value);
+    if (!raw)
+        return undefined;
+    const parsed = parseJsonArray(raw);
+    if (parsed.length === 0)
+        return undefined;
+    if (parsed.some((entry) => !entry || typeof entry !== "object" || Array.isArray(entry))) {
+        throw new OxygenError("invalid_sort", "--sort-json must be an array of sort-rule objects.", {
+            exitCode: 1,
+        });
+    }
+    return parsed;
+}
+/**
+ * `--url` hands the fetch to the server: the same durable import the file path
+ * enqueues, with the bytes read by OXYGEN behind SSRF, size and content guards,
+ * so the CLI never downloads anything and a 0-credit preview is one flag away.
+ */
+async function importRowsFromUrl(table, options) {
+    if (options.create && table) {
+        throw new OxygenError("invalid_import_target", "Pass either a table argument or --create, not both.", { exitCode: 1 });
+    }
+    if (!options.preview && !options.create && !table) {
+        throw new OxygenError("invalid_import_target", "Pass a table argument or --create <name>, or add --preview to look first.", { exitCode: 1 });
+    }
+    const result = await requestOxygen("/api/cli/tables/import-from-url", {
+        method: "POST",
+        timeoutMs: 120_000,
+        body: {
+            url: options.url,
+            mode: options.preview ? "preview" : "import",
+            ...(table ? { table } : {}),
+            ...(options.create ? { create_name: options.create } : {}),
+            ...(readOption(options.project) ? { project: readOption(options.project) } : {}),
+            ...(readOption(options.upsertKey) ? { upsert_key: readOption(options.upsertKey) } : {}),
+            ...(readOption(options.format) ? { format: readOption(options.format) } : {}),
+            ...(readOption(options.sheet) ? { sheet: readOption(options.sheet) } : {}),
+        },
+    });
+    if (options.preview)
+        return result;
+    emitQueueWaitStderrNote(readRecord(result, "queue_wait"));
+    return withImportWaitNextStep({ ...result, background: true, autoBackground: true });
+}
+async function importRows(table, options) {
+    if (options.url && options.skipBlankCells) {
+        throw new OxygenError("invalid_request", "--skip-blank-cells works on --file imports. Download the link and import the file.", { exitCode: 1 });
+    }
+    if (options.url)
+        return importRowsFromUrl(table, { ...options, url: options.url });
+    if (!options.file) {
+        throw new OxygenError("invalid_request", "Pass --file <path> or --url <https-link>.", { exitCode: 1 });
+    }
+    if (options.preview) {
+        throw new OxygenError("invalid_request", "--preview only applies to --url imports.", { exitCode: 1 });
+    }
+    return importRowsFromFile(table, { ...options, file: options.file });
+}
+async function importRowsFromFile(table, options) {
+    const format = normalizeRowsFormat(options.format, inferRowsFileFormat(options.file));
+    // Refuse a JSON or XLSX file too large to hold in memory before reading it,
+    // and send a large CSV or JSONL file down the streamed path, which never does.
+    const fileBytes = statSync(options.file).size;
+    assertImportFormatWithinBufferedLimit(format, fileBytes);
+    if (shouldStreamFileImport(format, fileBytes)) {
+        return withImportWaitNextStep(await importLargeFileStreamed(table, options, format, fileBytes));
+    }
+    const parsedRows = await readRowsFile(options.file, format, options.sheet);
+    if (parsedRows.length === 0) {
+        throw new OxygenError("invalid_rows", "Import file did not contain any rows.", {
+            exitCode: 1,
+        });
+    }
+    const batchSize = normalizeImportBatchSize(options.batchSize);
+    const effectiveBatchSize = Math.min(batchSize, SAFE_IMPORT_WRITE_BATCH_SIZE);
+    const sourceHash = hashImportFile(options.file);
+    const shouldUseBackground = options.background
+        || (!options.sync && parsedRows.length > LARGE_IMPORT_BACKGROUND_ROW_THRESHOLD);
+    const preparedBackgroundTarget = shouldUseBackground && table && !options.create
+        ? await prepareImportTarget(table, options, parsedRows)
+        : null;
+    if (shouldUseBackground) {
+        // Prefer the object-storage fast path: upload the raw file once via a
+        // presigned URL (no request-body limit) so the worker COPY-loads it.
+        // Falls back to the inline multipart import when storage is unconfigured.
+        const fileBuffer = readFileSync(options.file);
+        const staged = await tryEnqueueStagedFileImport(table, options, format, {
+            byteLength: fileBuffer.byteLength,
+            read: () => Promise.resolve({ targetRows: parsedRows, rowCount: parsedRows.length, sha256: sourceHash }),
+            put: (uploadUrl, contentType) => putImportFile(uploadUrl, fileBuffer, contentType),
+        }, {
+            autoBackground: !options.background,
+            batchSize,
+        }, preparedBackgroundTarget);
+        if (staged)
+            return withImportWaitNextStep(staged);
+        return withImportWaitNextStep(await enqueueImportFile(table, options, format, batchSize, {
+            autoBackground: !options.background,
+            sourceHash,
+        }, preparedBackgroundTarget));
+    }
+    const prepared = await prepareImportTarget(table, options, parsedRows);
+    // The foreground writes rows itself: a row without a key leaves that value alone.
+    const target = options.skipBlankCells
+        ? { ...prepared, rows: prepared.rows.map((row) => dropBlankImportCells(row, prepared.upsertKey)) }
+        : prepared;
+    let rowCount = 0;
+    let insertedCount = 0;
+    let updatedCount = 0;
+    let warningCount = 0;
+    const warnings = [];
+    let warningsTruncated = false;
+    let lastResult = null;
+    let writeRequestCount = 0;
+    let requestTooLargeRetries = 0;
+    let byteSplits = 0;
+    let minimumBatchSizeUsed = null;
+    for (const [batchIndex, batch] of chunk(target.rows, effectiveBatchSize).entries()) {
+        const result = await writeImportBatchWithAutoSplit({
+            tableRef: target.tableRef,
+            upsertKey: target.upsertKey,
+            rows: batch,
+            ...(!target.upsertKey
+                ? { requestId: `tables-import:${sourceHash}:${batchIndex}` }
+                : {}),
+        });
+        rowCount += result.rowCount;
+        insertedCount += result.insertedCount;
+        updatedCount += result.updatedCount;
+        warningCount += result.warningCount;
+        for (const warning of result.warnings) {
+            if (warnings.length < 20)
+                warnings.push(warning);
+        }
+        warningsTruncated = warningsTruncated || result.warningsTruncated || warningCount > warnings.length;
+        writeRequestCount += result.writeRequestCount;
+        requestTooLargeRetries += result.requestTooLargeRetries;
+        byteSplits += result.byteSplits;
+        minimumBatchSizeUsed = minimumBatchSizeUsed === null
+            ? result.minimumBatchSizeUsed
+            : Math.min(minimumBatchSizeUsed, result.minimumBatchSizeUsed);
+        lastResult = result.lastResult;
+    }
+    return {
+        table: lastResult?.table ?? null,
+        ...(target.createdTable ? { createdTable: target.createdTable } : {}),
+        rowCount,
+        insertedCount,
+        updatedCount,
+        ...(warningCount > 0 ? {
+            warnings,
+            warningCount,
+            ...(warningsTruncated ? { warningsTruncated: true } : {}),
+        } : {}),
+        batchCount: writeRequestCount,
+        batchSize: effectiveBatchSize,
+        ...(effectiveBatchSize !== batchSize ? { requestedBatchSize: batchSize } : {}),
+        // Two separate counters: a byte pre-split cost nothing, a server 413 cost a
+        // wasted upload — reporting them as one number would hide which happened.
+        ...(requestTooLargeRetries > 0 ? { requestTooLargeRetries } : {}),
+        ...(byteSplits > 0 ? { byteSplits } : {}),
+        ...(requestTooLargeRetries > 0 || byteSplits > 0 ? { minimumBatchSizeUsed } : {}),
+        ...(target.tableWebUrl ? { table_web_url: target.tableWebUrl } : {}),
+        ...(readRecordString(lastResult, "web_url") ? { web_url: readRecordString(lastResult, "web_url") } : {}),
+    };
+}
+async function prepareImportTarget(table, options, parsedRows) {
+    if (options.create && table) {
+        throw new OxygenError("invalid_import_target", "Pass either a table argument or --create, not both.", {
+            exitCode: 1,
+        });
+    }
+    if (!options.create && !table) {
+        throw new OxygenError("invalid_import_target", "Pass a table argument or --create <name>.", {
+            exitCode: 1,
+        });
+    }
+    if (!options.create) {
+        const keyMapping = await resolveExistingTableImportKeyMapping(table, parsedRows, readOption(options.upsertKey) ?? undefined);
+        return {
+            tableRef: table,
+            rows: remapImportRows(parsedRows, keyMapping.sourceKeyMap),
+            createdTable: null,
+            tableWebUrl: null,
+            upsertKey: keyMapping.upsertKey,
+            sourceKeyMap: keyMapping.sourceKeyMap,
+        };
+    }
+    const normalized = normalizeRowsForNewTable(parsedRows);
+    const created = await requestOxygen("/api/cli/tables", {
+        method: "POST",
+        body: {
+            name: options.create,
+            columns: normalized.columns,
+            ...(readOption(options.project) ? { project: readOption(options.project) } : {}),
+        },
+    });
+    const tableRecord = readRecord(created, "table");
+    const createdSlug = readRecordString(tableRecord, "slug") ?? readRecordString(tableRecord, "id");
+    if (!createdSlug) {
+        throw new OxygenError("invalid_response", "Oxygen API response is missing the created table slug.", {
+            exitCode: 1,
+        });
+    }
+    const createdWebUrl = readRecordString(created, "web_url")
+        ?? readRecordString(created, "deepLink");
+    return {
+        tableRef: createdSlug,
+        rows: normalized.rows,
+        createdTable: created,
+        tableWebUrl: createdWebUrl ?? tableWebUrl(createdSlug),
+        upsertKey: normalizeCreatedTableUpsertKey(options.upsertKey, normalized.keyBySource),
+        sourceKeyMap: normalized.keyBySource,
+    };
+}
+async function resolveExistingTableImportKeyMapping(table, rows, upsertKey) {
+    const describe = await requestOxygen("/api/cli/tables/describe", { method: "POST", body: { table } });
+    const resolver = buildExistingTableColumnResolver(describe.columns ?? []);
+    const resolvedByHeader = new Map();
+    const targetCounts = new Map();
+    for (const sourceKey of inferImportColumnLabels(rows)) {
+        const resolved = resolveImportSourceKey(sourceKey, resolver);
+        if (!resolved)
+            continue;
+        resolvedByHeader.set(sourceKey, resolved);
+        targetCounts.set(resolved, (targetCounts.get(resolved) ?? 0) + 1);
+    }
+    const sourceKeyMap = {};
+    for (const [sourceKey, resolved] of resolvedByHeader) {
+        if ((targetCounts.get(resolved) ?? 0) > 1)
+            continue;
+        if (resolved !== sourceKey)
+            sourceKeyMap[sourceKey] = resolved;
+    }
+    return {
+        sourceKeyMap: Object.keys(sourceKeyMap).length > 0 ? sourceKeyMap : null,
+        upsertKey: upsertKey
+            ? resolveImportSourceKey(upsertKey, resolver) ?? upsertKey
+            : undefined,
+    };
+}
+function buildExistingTableColumnResolver(columns) {
+    const exact = new Map();
+    const aliases = new Map();
+    for (const column of columns) {
+        if (!column.key)
+            continue;
+        exact.set(column.key, column.key);
+        addImportColumnAlias(aliases, column.label, column.key);
+        addImportColumnAlias(aliases, normalizeImportColumnKey(column.key), column.key);
+        if (column.label)
+            addImportColumnAlias(aliases, normalizeImportColumnKey(column.label), column.key);
+    }
+    return { exact, aliases };
+}
+function addImportColumnAlias(aliases, alias, key) {
+    const normalizedAlias = alias?.trim();
+    if (!normalizedAlias)
+        return;
+    const existing = aliases.get(normalizedAlias);
+    if (existing === undefined) {
+        aliases.set(normalizedAlias, key);
+        return;
+    }
+    if (existing !== key)
+        aliases.set(normalizedAlias, null);
+}
+function resolveImportSourceKey(sourceKey, resolver) {
+    const trimmed = sourceKey.trim();
+    return resolver.exact.get(sourceKey)
+        ?? resolver.exact.get(trimmed)
+        ?? readImportColumnAlias(resolver.aliases, sourceKey)
+        ?? readImportColumnAlias(resolver.aliases, trimmed)
+        ?? readImportColumnAlias(resolver.aliases, normalizeImportColumnKey(sourceKey));
+}
+function readImportColumnAlias(aliases, alias) {
+    return aliases.get(alias) ?? null;
+}
+function remapImportRows(rows, sourceKeyMap) {
+    if (!sourceKeyMap)
+        return rows;
+    return rows.map((row) => {
+        const remapped = {};
+        for (const [key, value] of Object.entries(row)) {
+            remapped[sourceKeyMap[key] ?? key] = value;
+        }
+        return remapped;
+    });
+}
+async function writeImportBatchWithAutoSplit(input) {
+    const body = {
+        table: input.tableRef,
+        rows: input.rows,
+        ...(input.upsertKey ? { key: input.upsertKey } : {}),
+        ...(!input.upsertKey && input.requestId ? { request_id: input.requestId } : {}),
+    };
+    // The server checks content-length against MAX_CLI_JSON_BODY_BYTES and the
+    // client sends exactly JSON.stringify(body), so measuring it here is the same
+    // test — a wide batch (large text cells) splits before it costs an upload and a
+    // 413. Same halving and request_id suffixes as the reactive path below, so a
+    // re-run replays the identical batch ids either way.
+    const bodyBytes = Buffer.byteLength(JSON.stringify(body));
+    if (bodyBytes > MAX_CLI_JSON_BODY_BYTES && input.rows.length > 1) {
+        const midpoint = Math.ceil(input.rows.length / 2);
+        process.stderr.write(`note: import batch of ${input.rows.length} rows serializes to ${bodyBytes} bytes, `
+            + `over the ${MAX_CLI_JSON_BODY_BYTES} byte request limit; `
+            + `sending as ${midpoint} and ${input.rows.length - midpoint} row batches.\n`);
+        const [first, second] = await writeImportBatchHalves(input, midpoint);
+        return combineImportBatchWriteSummaries(first, second, { byteSplits: 1 });
+    }
+    try {
+        const result = await requestOxygen(input.upsertKey ? "/api/cli/tables/rows/upsert" : "/api/cli/tables/rows", {
+            method: "POST",
+            timeoutMs: 300_000,
+            body,
+        });
+        return summarizeImportBatchWrite(result, input.rows.length);
+    }
+    catch (error) {
+        if (!isRequestTooLargeError(error) || input.rows.length <= 1)
+            throw error;
+        // Fallback for a server whose ceiling is tighter than the shared constant.
+        const midpoint = Math.ceil(input.rows.length / 2);
+        process.stderr.write(`note: import batch of ${input.rows.length} rows exceeded the request limit; `
+            + `retrying as ${midpoint} and ${input.rows.length - midpoint} row batches.\n`);
+        const [first, second] = await writeImportBatchHalves(input, midpoint);
+        return combineImportBatchWriteSummaries(first, second, { requestTooLargeRetries: 1 });
+    }
+}
+async function writeImportBatchHalves(input, midpoint) {
+    const first = await writeImportBatchWithAutoSplit({
+        ...input,
+        rows: input.rows.slice(0, midpoint),
+        ...(input.requestId ? { requestId: `${input.requestId}:0` } : {}),
+    });
+    const second = await writeImportBatchWithAutoSplit({
+        ...input,
+        rows: input.rows.slice(midpoint),
+        ...(input.requestId ? { requestId: `${input.requestId}:1` } : {}),
+    });
+    return [first, second];
+}
+function summarizeImportBatchWrite(result, batchSize) {
+    const warningCount = readCount(result.warningCount);
+    const batchWarnings = Array.isArray(result.warnings) ? result.warnings : [];
+    return {
+        rowCount: readCount(result.rowCount),
+        insertedCount: readCount(result.insertedCount),
+        updatedCount: readCount(result.updatedCount),
+        warningCount,
+        warnings: batchWarnings.slice(0, 20),
+        warningsTruncated: result.warningsTruncated === true || warningCount > batchWarnings.length,
+        writeRequestCount: 1,
+        requestTooLargeRetries: 0,
+        byteSplits: 0,
+        minimumBatchSizeUsed: batchSize,
+        lastResult: result,
+    };
+}
+function combineImportBatchWriteSummaries(first, second, extra) {
+    const warnings = [...first.warnings, ...second.warnings].slice(0, 20);
+    const warningCount = first.warningCount + second.warningCount;
+    return {
+        rowCount: first.rowCount + second.rowCount,
+        insertedCount: first.insertedCount + second.insertedCount,
+        updatedCount: first.updatedCount + second.updatedCount,
+        warningCount,
+        warnings,
+        warningsTruncated: first.warningsTruncated || second.warningsTruncated || warningCount > warnings.length,
+        writeRequestCount: first.writeRequestCount + second.writeRequestCount,
+        requestTooLargeRetries: first.requestTooLargeRetries + second.requestTooLargeRetries + (extra.requestTooLargeRetries ?? 0),
+        byteSplits: first.byteSplits + second.byteSplits + (extra.byteSplits ?? 0),
+        minimumBatchSizeUsed: Math.min(first.minimumBatchSizeUsed, second.minimumBatchSizeUsed),
+        lastResult: second.lastResult ?? first.lastResult,
+    };
+}
+function isRequestTooLargeError(error) {
+    return error instanceof OxygenError && error.code === "request_too_large";
+}
+async function tryEnqueueStagedFileImport(// skipcq: JS-R1005
+table, options, format, file, context, preparedTarget = null) {
+    if (options.create && table) {
+        throw new OxygenError("invalid_import_target", "Pass either a table argument or --create, not both.", {
+            exitCode: 1,
+        });
+    }
+    if (!options.create && !table) {
+        throw new OxygenError("invalid_import_target", "Pass a table argument or --create <name>.", {
+            exitCode: 1,
+        });
+    }
+    const filename = basename(options.file);
+    const contentType = importFileContentType(format);
+    const traceId = randomUUID();
+    // Probe for a presigned upload URL. If object storage isn't configured the
+    // server returns object_storage_not_configured; signal the caller to fall
+    // back to the inline multipart import by returning null.
+    const requestPresign = async () => {
+        try {
+            return await requestOxygen("/api/cli/tables/import-url", {
+                method: "POST",
+                body: {
+                    file_name: filename,
+                    content_type: contentType,
+                    byte_length: file.byteLength,
+                    format,
+                    trace_id: traceId,
+                },
+            });
+        }
+        catch (error) {
+            if (error instanceof OxygenError && error.code === "object_storage_not_configured") {
+                return null;
+            }
+            throw error;
+        }
+    };
+    let presigned = await requestPresign();
+    if (!presigned)
+        return null;
+    const contents = await file.read();
+    // Create the table for --create (or resolve the existing ref) before the
+    // upload so a presign success always pairs with a real target.
+    const target = preparedTarget ?? await prepareImportTarget(table, options, contents.targetRows);
+    const put = (current) => {
+        const uploadUrl = readRecordString(current, "upload_url");
+        return uploadUrl ? file.put(uploadUrl, contentType) : Promise.resolve(new Response(null, { status: 500 }));
+    };
+    let putResponse = await put(presigned);
+    // A direct-upload 403 most commonly means a stale/mismatched signature.
+    // Refresh once under the same client trace so a transient presign never
+    // strands a durable import, while persistent policy failures stay explicit.
+    if (putResponse.status === 403) {
+        const refreshed = await requestPresign();
+        if (refreshed) {
+            presigned = refreshed;
+            putResponse = await put(presigned);
+        }
+    }
+    if (!putResponse.ok) {
+        throw new OxygenError("import_upload_failed", `Uploading the import file to object storage failed (HTTP ${putResponse.status}).`, { details: { status: putResponse.status, trace_id: traceId }, exitCode: 1 });
+    }
+    const storageKey = readRecordString(presigned, "storage_key");
+    const storageBucket = readRecordString(presigned, "storage_bucket");
+    const storageProvider = readRecordString(presigned, "storage_provider") ?? "s3";
+    if (!storageKey)
+        return null;
+    const result = await requestOxygen("/api/cli/tables/import-staged", {
+        method: "POST",
+        timeoutMs: 120_000,
+        body: {
+            table: target.tableRef,
+            storage_provider: storageProvider,
+            storage_bucket: storageBucket,
+            storage_key: storageKey,
+            format,
+            file_name: filename,
+            byte_length: file.byteLength,
+            sha256: contents.sha256,
+            row_count: contents.rowCount,
+            batch_size: context.batchSize,
+            ...(readPositiveInt(options.maxConcurrency)
+                ? { max_concurrency: readPositiveInt(options.maxConcurrency) }
+                : {}),
+            ...(target.upsertKey ? { upsert_key: target.upsertKey } : {}),
+            ...(target.sourceKeyMap ? { source_key_map: target.sourceKeyMap } : {}),
+            ...(options.skipBlankCells ? { skip_blank_cells: true } : {}),
+        },
+    });
+    emitQueueWaitStderrNote(readRecord(result, "queue_wait"));
+    return {
+        ...result,
+        ...(target.createdTable ? { createdTable: target.createdTable } : {}),
+        ...(target.tableWebUrl ? { table_web_url: target.tableWebUrl } : {}),
+        background: true,
+        autoBackground: context.autoBackground,
+        import_engine: "chunked_file_v2",
+        storage_provider: storageProvider,
+    };
+}
+/**
+ * A CSV or JSONL file over STREAMED_FILE_IMPORT_MIN_BYTES: never read whole.
+ * One streaming pass counts, hashes and collects its columns, the upload streams
+ * from disk, and the import always runs in the background. There is no inline
+ * fallback: a file this large cannot travel in one API request.
+ */
+async function importLargeFileStreamed(table, options, format, fileBytes) {
+    if (options.sync) {
+        process.stderr.write(`note: files over ${Math.round(STREAMED_FILE_IMPORT_MIN_BYTES / (1024 * 1024))} MiB always import in the background; --sync is ignored\n`);
+    }
+    const staged = await tryEnqueueStagedFileImport(table, options, format, {
+        byteLength: fileBytes,
+        read: async () => {
+            process.stderr.write(`note: reading ${basename(options.file)} (${formatMebibytes(fileBytes)}) to count its rows before uploading\n`);
+            const scan = await scanStreamedImportFile(options.file, format);
+            if (scan.rowCount === 0) {
+                throw new OxygenError("invalid_rows", "Import file did not contain any rows.", { exitCode: 1 });
+            }
+            return { targetRows: rowsForStreamedImportTarget(scan), rowCount: scan.rowCount, sha256: scan.sha256 };
+        },
+        put: (uploadUrl, contentType) => putImportFileStream({ uploadUrl, path: options.file, byteLength: fileBytes, contentType }),
+    }, {
+        autoBackground: !options.background,
+        batchSize: normalizeImportBatchSize(options.batchSize),
+    });
+    if (staged)
+        return { ...staged, streamed_upload: true };
+    throw new OxygenError("object_storage_not_configured", `Files over ${Math.round(STREAMED_FILE_IMPORT_MIN_BYTES / (1024 * 1024))} MiB upload straight to file storage, which this OXYGEN server has not configured.`, {
+        details: { file_bytes: fileBytes, streamed_import_min_bytes: STREAMED_FILE_IMPORT_MIN_BYTES },
+        exitCode: 1,
+    });
+}
+function formatMebibytes(bytes) {
+    return `${Math.round(bytes / (1024 * 1024)).toLocaleString("en-US")} MiB`;
+}
+async function putImportFile(uploadUrl, fileBuffer, contentType) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 300_000);
+    try {
+        return await fetch(uploadUrl, {
+            method: "PUT",
+            headers: {
+                "content-type": contentType,
+                "content-length": String(fileBuffer.byteLength),
+            },
+            body: new Uint8Array(fileBuffer),
+            signal: controller.signal,
+        });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function importFileContentType(format) {
+    if (format === "csv")
+        return "text/csv";
+    if (format === "xlsx")
+        return "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+    if (format === "jsonl")
+        return "application/x-ndjson";
+    return "application/json";
+}
+async function enqueueImportFile(table, options, format, batchSize, context, preparedTarget = null) {
+    if (options.create && table) {
+        throw new OxygenError("invalid_import_target", "Pass either a table argument or --create, not both.", {
+            exitCode: 1,
+        });
+    }
+    if (!options.create && !table) {
+        throw new OxygenError("invalid_import_target", "Pass a table argument or --create <name>.", {
+            exitCode: 1,
+        });
+    }
+    if (options.skipBlankCells) {
+        // The multipart import cannot leave blank cells out; failing beats clearing them.
+        throw new OxygenError("skip_blank_cells_unavailable", "--skip-blank-cells needs the staged file upload, which this OXYGEN server has not configured. Add --sync to write the rows from this machine instead.", { exitCode: 1 });
+    }
+    const fileBuffer = readFileSync(options.file);
+    const filename = basename(options.file);
+    const form = new FormData();
+    const file = new File([fileBuffer], filename);
+    form.append("file", file, filename);
+    form.append("filename", filename);
+    form.append("format", format);
+    form.append("batch_size", String(batchSize));
+    form.append("auto_background", String(context.autoBackground));
+    form.append("source_hash", context.sourceHash);
+    const targetTable = preparedTarget?.tableRef ?? table;
+    if (targetTable)
+        form.append("table", targetTable);
+    if (!preparedTarget && options.create)
+        form.append("table_name", options.create);
+    const project = readOption(options.project);
+    if (project)
+        form.append("project", project);
+    const upsertKey = preparedTarget?.upsertKey ?? readOption(options.upsertKey);
+    if (upsertKey)
+        form.append("upsert_key", upsertKey);
+    if (preparedTarget?.sourceKeyMap) {
+        form.append("source_key_map", JSON.stringify(preparedTarget.sourceKeyMap));
+    }
+    if (options.sheet)
+        form.append("sheet", options.sheet);
+    const maxConcurrency = readPositiveInt(options.maxConcurrency);
+    if (maxConcurrency)
+        form.append("max_concurrency", String(maxConcurrency));
+    const result = await requestOxygen("/api/cli/tables/import-file", {
+        method: "POST",
+        timeoutMs: 300_000,
+        formData: form,
+    });
+    emitQueueWaitStderrNote(readRecord(result, "queue_wait"));
+    return {
+        ...result,
+        background: true,
+        autoBackground: context.autoBackground,
+    };
+}
+function emitQueueWaitStderrNote(queueWait) {
+    if (!queueWait)
+        return;
+    const note = readRecordString(queueWait, "note");
+    if (note)
+        process.stderr.write(`note: ${note}\n`);
+}
+async function exportRows(table, options) {
+    const format = normalizeExportRowsFormat(options.format);
+    const limit = readPositiveInt(options.limit);
+    const result = await requestOxygen("/api/cli/tables/query", {
+        method: "POST",
+        body: {
+            table,
+            ...(limit ? { limit } : {}),
+        },
+    });
+    const formatted = formatRows(result.rows, format, result.columns);
+    if (options.output) {
+        writeFileSync(options.output, formatted.content);
+    }
+    return {
+        table: result.table ?? null,
+        format,
+        rowCount: result.rows.length,
+        output: options.output ?? null,
+        ...(options.output ? {} : { content: formatted.content }),
+        ...(formatted.rescuedCount > 0 ? { rescuedNumericCells: formatted.rescuedCount } : {}),
+    };
+}
+// Bundle formats. Version 2 is line-delimited: a header line carrying the
+// schema, then one `{"row":…}` line per row, then a `{"totals":…}` trailer.
+// It exists because the version-1 single-document bundle is assembled in memory
+// and serialized once, and a 52k-row table carrying LinkedIn profile text pushed
+// that one string past V8's limit ("Invalid string length") on 2026-09-14: the
+// export died after twelve minutes with nothing on disk, and a 96-column table
+// on the other side of the same copy could never have been read back into
+// memory by the importer either. `--output` now streams version 2; import reads
+// both versions, streaming version 2 so file size no longer matters.
+const TABLE_BUNDLE_SCHEMA_VERSION = 2;
+const TABLE_BUNDLE_LEGACY_SCHEMA_VERSION = 1;
+const TABLE_BUNDLE_SUPPORTED_SCHEMA_VERSIONS = [TABLE_BUNDLE_LEGACY_SCHEMA_VERSION, TABLE_BUNDLE_SCHEMA_VERSION];
+const TABLE_BUNDLE_MAX_PAGE_SIZE = 1000;
+const TABLE_BUNDLE_DEFAULT_PAGE_SIZE = 500;
+// How much of a bundle file is read to find its header line and totals trailer
+// without loading the whole file: 8 MiB comfortably holds a header for a
+// 100-column table with long AI prompts, and the trailer is one short line.
+const TABLE_BUNDLE_HEADER_SCAN_BYTES = 8 * 1024 * 1024;
+const TABLE_BUNDLE_TRAILER_SCAN_BYTES = 1024 * 1024;
+// skipcq: JS-R1005 — intentional branching across describe/query pagination, column-definition normalization, and output sink (stdout/file)
+async function exportTableBundle(table, options) {
+    const pageSize = Math.min(readPositiveInt(options.pageSize) ?? TABLE_BUNDLE_DEFAULT_PAGE_SIZE, TABLE_BUNDLE_MAX_PAGE_SIZE);
+    // Pull the canonical schema (incl. enrichment/tool definitions and
+    // semantic types) from `describe`; the paginated query response only
+    // surfaces the user-visible projection.
+    const describe = await requestOxygen("/api/cli/tables/describe", { method: "POST", body: { table } });
+    const tableMeta = describe.table ?? null;
+    const columns = (describe.columns ?? []).map(toBundleColumn);
+    const tableId = readRecordString(tableMeta, "id");
+    const tableSlug = readRecordString(tableMeta, "slug");
+    const projectSlug = readRecordString(tableMeta, "projectSlug");
+    const tableSummary = {
+        id: tableId ?? null,
+        slug: tableSlug ?? null,
+        name: readRecordString(tableMeta, "displayName") ?? readRecordString(tableMeta, "name") ?? null,
+        projectSlug: projectSlug ?? null,
+    };
+    const exportedAt = new Date().toISOString();
+    // With --output the bundle streams to disk one row per line, so memory stays
+    // flat however many rows the table has. The file is written under a .partial
+    // name and renamed only after the totals trailer lands, so an interrupted
+    // export can never be mistaken for a complete bundle.
+    const outputPath = options.output ? resolve(options.output) : null;
+    const partialPath = outputPath ? `${outputPath}.partial` : null;
+    const stream = partialPath ? createWriteStream(partialPath, { encoding: "utf8" }) : null;
+    const rows = [];
+    let cursor = null;
+    let expectedTotal = null;
+    let pageCount = 0;
+    let rowCount = 0;
+    let hasMoreFlag = false;
+    try {
+        if (stream) {
+            await writeBundleLine(stream, JSON.stringify({
+                schemaVersion: TABLE_BUNDLE_SCHEMA_VERSION,
+                exportedAt,
+                table: tableSummary,
+                columns,
+            }));
+        }
+        do {
+            const requestBody = { table, limit: pageSize };
+            if (cursor)
+                requestBody.cursor = cursor;
+            const page = await requestOxygen("/api/cli/tables/query", { method: "POST", body: requestBody });
+            pageCount += 1;
+            if (expectedTotal === null) {
+                expectedTotal = readBundleNumber(page.totalCount) ?? readBundleNumber(page.total_count) ?? null;
+            }
+            for (const row of page.rows ?? []) {
+                rowCount += 1;
+                if (stream)
+                    await writeBundleLine(stream, JSON.stringify({ row }));
+                else
+                    rows.push(row);
+            }
+            cursor = typeof page.nextCursor === "string" && page.nextCursor.length > 0 ? page.nextCursor : null;
+            hasMoreFlag = Boolean(page.hasMore);
+            // Defensive: hasMore=false should always mean cursor=null. If a future
+            // server change ever sets one without the other, stop iterating on
+            // hasMore=false so we don't loop forever.
+            if (!hasMoreFlag)
+                cursor = null;
+        } while (cursor);
+        if (expectedTotal !== null && rowCount !== expectedTotal) {
+            throw new OxygenError("bundle_export_incomplete", "Cursor pagination ended before every row was written. The bundle would be a silent under-export.", {
+                details: {
+                    table,
+                    totalCount: expectedTotal,
+                    exportedCount: rowCount,
+                    missing: expectedTotal - rowCount,
+                    pages: pageCount,
+                },
+                exitCode: 1,
+            });
+        }
+        const totals = {
+            rowCount,
+            ...(expectedTotal !== null ? { sourceTotalCount: expectedTotal } : {}),
+            pages: pageCount,
+            pageSize,
+        };
+        if (stream && partialPath && outputPath) {
+            await writeBundleLine(stream, JSON.stringify({ totals }));
+            await finishBundleStream(stream);
+            renameSync(partialPath, outputPath);
+        }
+        const summary = {
+            table_id: tableId ?? null,
+            table_slug: tableSlug ?? null,
+            schema_version: stream ? TABLE_BUNDLE_SCHEMA_VERSION : TABLE_BUNDLE_LEGACY_SCHEMA_VERSION,
+            format: stream ? "jsonl" : "json",
+            column_count: columns.length,
+            row_count: rowCount,
+            pages: pageCount,
+            page_size: pageSize,
+            output: options.output ?? null,
+            ...(tableId ? { web_url: tableWebUrl(tableId) } : tableSlug ? { web_url: tableWebUrl(tableSlug) } : {}),
+        };
+        // With --output, the file is the source of truth; keep the stdout response
+        // a small summary so it's readable.
+        if (stream)
+            return summary;
+        // When piping to stdout, emit the full single-document bundle so it can be
+        // redirected into a file. That document has to fit in one string, so say
+        // so — with the fix — instead of dying on a bare RangeError.
+        const bundle = {
+            schemaVersion: TABLE_BUNDLE_LEGACY_SCHEMA_VERSION,
+            exportedAt,
+            table: tableSummary,
+            columns,
+            rows,
+            totals,
+        };
+        assertBundleSerializable(bundle, rowCount);
+        return { ...summary, bundle };
+    }
+    catch (error) {
+        if (stream) {
+            stream.destroy();
+            if (partialPath) {
+                try {
+                    unlinkSync(partialPath);
+                }
+                catch {
+                    // The partial file may never have been created; nothing to clean.
+                }
+            }
+        }
+        throw error;
+    }
+}
+// Writes one bundle line and honors the stream's backpressure, so a 50k-row
+// export never accumulates the file in memory while the disk catches up.
+function writeBundleLine(stream, line) {
+    return new Promise((resolveLine, rejectLine) => {
+        const onError = (error) => rejectLine(error);
+        if (stream.write(`${line}\n`, "utf8")) {
+            resolveLine();
+            return;
+        }
+        stream.once("error", onError);
+        stream.once("drain", () => {
+            stream.off("error", onError);
+            resolveLine();
+        });
+    });
+}
+function finishBundleStream(stream) {
+    return new Promise((resolveStream, rejectStream) => {
+        stream.once("error", rejectStream);
+        stream.end(() => resolveStream());
+    });
+}
+function assertBundleSerializable(bundle, rowCount) {
+    try {
+        JSON.stringify(bundle);
+    }
+    catch (error) {
+        if (error instanceof RangeError) {
+            throw new OxygenError("bundle_too_large", `This table's ${rowCount} rows do not fit in one JSON document. Re-run with --output <path>: the bundle then streams to the file one row per line, with no size limit.`, { details: { row_count: rowCount }, exitCode: 1 });
+        }
+        throw error;
+    }
+}
+async function importTableBundle(// skipcq: JS-R1005
+options, binaryName) {
+    const path = options.file;
+    if (!path || !path.trim()) {
+        throw new OxygenError("invalid_input", "--file is required.", { exitCode: 1 });
+    }
+    const batchSize = normalizeImportBatchSize(options.batchSize);
+    const effectiveBatchSize = Math.min(batchSize, SAFE_IMPORT_WRITE_BATCH_SIZE);
+    const bundle = await openTableBundle(resolve(path));
+    // A native `relation` column is only half of a relation: the other half is a
+    // row in ox_tables.relation_definitions that ONLY `tables relate` writes. A
+    // bundle carries the column but not the definition, and its `target_table` is
+    // the SOURCE workspace's table id, which does not exist here. Importing it
+    // produced a column that pointed at a foreign workspace and that no surface
+    // could repair, rename, archive or delete — every column lifecycle command
+    // refuses a relation-shaped column, and the relation commands refuse a
+    // definition that was never written (OXY-4360). Skip them and say so;
+    // `tables relate` rebuilds a real relation on this side once both tables
+    // exist. Keyed on the NATIVE shape, not `kind === "relation"`: CRM
+    // relationship columns (`target_object`, no `storage`) are a different
+    // mechanism with their own lifecycle and must still import.
+    const isNativeRelationColumn = (column) => column.kind === "relation"
+        && (column.definition?.storage === "tables"
+            || typeof column.definition?.archived_relation_definition_id === "string");
+    const bundleColumns = bundle.columns.map(bundleColumnToCreateInput);
+    const skippedRelationColumns = bundleColumns
+        .filter(isNativeRelationColumn)
+        .map((column) => column.key ?? column.label);
+    const columns = bundleColumns.filter((column) => !isNativeRelationColumn(column));
+    if (bundleColumns.length === 0) {
+        throw new OxygenError("invalid_bundle", "Bundle has no columns; nothing to import.", { exitCode: 1 });
+    }
+    if (columns.length === 0) {
+        throw new OxygenError("invalid_bundle", "Bundle contains only native relation columns, which cannot be imported directly. Import the tables they point at, then run `tables relate`.", { details: { skipped_relation_columns: skippedRelationColumns }, exitCode: 1 });
+    }
+    const validColumnKeys = new Set(columns.map((column) => column.key).filter((key) => Boolean(key)));
+    const into = readOption(options.into);
+    const upsertKey = readOption(options.key);
+    // Resuming/appending into an existing table without an upsert key would
+    // duplicate every already-imported row. Require --key so the resume matches
+    // rows instead of re-inserting them.
+    if (into && !upsertKey) {
+        throw new OxygenError("invalid_input", "--into requires --key so rows already imported are matched instead of duplicated. Pass --key <uniqueColumn>.", { details: { into }, exitCode: 1 });
+    }
+    if (upsertKey) {
+        if (upsertKey.startsWith("_")) {
+            throw new OxygenError("invalid_input", "--key must be a workspace column key, not an internal field.", { details: { key: upsertKey }, exitCode: 1 });
+        }
+        if (validColumnKeys.size > 0 && !validColumnKeys.has(upsertKey)) {
+            throw new OxygenError("invalid_input", `--key ${upsertKey} is not a column in this bundle.`, { details: { key: upsertKey, available_keys: [...validColumnKeys] }, exitCode: 1 });
+        }
+    }
+    // Resolve the target table: resume into an existing one (--into), or create a
+    // fresh one from the bundle schema.
+    let newTableId;
+    let newTableSlug;
+    let createdTable;
+    if (into) {
+        const describe = await requestOxygen("/api/cli/tables/describe", { method: "POST", body: { table: into } });
+        const tableMeta = describe.table ?? null;
+        const resolvedId = tableMeta ? readRecordString(tableMeta, "id") : null;
+        if (!resolvedId) {
+            throw new OxygenError("table_not_found", `--into table ${into} was not found in this org.`, { details: { into }, exitCode: 1 });
+        }
+        newTableId = resolvedId;
+        newTableSlug = tableMeta ? readRecordString(tableMeta, "slug") ?? null : null;
+        createdTable = false;
+    }
+    else {
+        const tableName = readOption(options.name) ?? bundle.tableName;
+        if (!tableName) {
+            throw new OxygenError("invalid_bundle", "Bundle has no table.name and no --name override was provided.", { exitCode: 1 });
+        }
+        const createResponse = await requestOxygen("/api/cli/tables", {
+            method: "POST",
+            body: {
+                name: tableName,
+                columns,
+                ...(readOption(options.project) ? { project: readOption(options.project) } : {}),
+            },
+        });
+        const created = readRecord(createResponse, "table");
+        const createdId = readRecordString(createResponse, "table_id")
+            ?? (created ? readRecordString(created, "id") : null);
+        if (!createdId) {
+            throw new OxygenError("invalid_response", "Table create response did not include an id; bundle import cannot proceed.", { exitCode: 1 });
+        }
+        newTableId = createdId;
+        newTableSlug = readRecordString(createResponse, "table_slug")
+            ?? (created ? readRecordString(created, "slug") : null);
+        createdTable = true;
+    }
+    // In upsert mode every row must carry the key value; otherwise the upsert
+    // route rejects the whole batch midway. A single-document bundle has every
+    // row in memory, so it is checked before anything is written and never
+    // leaves a half-imported table behind for a predictable data problem. A
+    // streamed bundle is checked row by row as it is read; a miss stops the
+    // import with the row number, and --key makes the rerun idempotent.
+    if (upsertKey && bundle.preloadedRows) {
+        const missingIndex = bundle.preloadedRows.findIndex((row) => row[upsertKey] === undefined || row[upsertKey] === null);
+        if (missingIndex >= 0) {
+            throw new OxygenError("invalid_bundle", `Row ${missingIndex + 1} is missing a value for the upsert key "${upsertKey}".`, { details: { key: upsertKey, row_number: missingIndex + 1 }, exitCode: 1 });
+        }
+    }
+    const resumeCommand = buildBundleResumeCommand({
+        file: path,
+        tableId: newTableId,
+        key: upsertKey ?? null,
+        batchSize: effectiveBatchSize,
+        binaryName,
+    });
+    let processed = 0;
+    let insertedCount = 0;
+    let updatedCount = 0;
+    const batches = readBundleBatches({
+        bundle,
+        validColumnKeys,
+        upsertKey: upsertKey ?? null,
+        batchSize: effectiveBatchSize,
+        tableId: newTableId,
+        resumeCommand,
+    });
+    for await (const batch of batches) {
+        try {
+            // Same byte-aware writer as `tables import`: a wide batch pre-splits (and a
+            // server 413 halves) instead of dead-ending the bundle at an unchanged
+            // resume batch size. No request_id — bundle resumes match on --key.
+            const result = await writeImportBatchWithAutoSplit({
+                tableRef: newTableId,
+                upsertKey: upsertKey ?? undefined,
+                rows: batch,
+            });
+            if (upsertKey) {
+                insertedCount += result.insertedCount;
+                updatedCount += result.updatedCount;
+            }
+            else {
+                insertedCount += batch.length;
+            }
+            processed += batch.length;
+        }
+        catch (error) {
+            // A mid-loop failure used to leave a partial table with no way forward.
+            // Surface exactly where it stopped and how to resume so the import is
+            // recoverable instead of a silent half-write.
+            const cause = error instanceof OxygenError
+                ? error.code
+                : error instanceof Error
+                    ? error.message
+                    : "unknown";
+            const recovery = upsertKey
+                ? `Re-run with --into ${newTableId} --key ${upsertKey} to resume — already-imported rows are matched by "${upsertKey}", not duplicated.`
+                : `Resume with: ${resumeCommand}`;
+            throw new OxygenError("bundle_import_incomplete", `Bundle import stopped after ${processed}/${bundle.rowCount} rows. ${recovery}`, {
+                details: {
+                    table_id: newTableId,
+                    table_slug: newTableSlug,
+                    rows_total: bundle.rowCount,
+                    rows_processed: processed,
+                    failed_batch_offset: processed,
+                    failed_batch_size: batch.length,
+                    mode: upsertKey ? "upsert" : "insert",
+                    ...(upsertKey ? { key: upsertKey } : {}),
+                    resume_command: resumeCommand,
+                    web_url: tableWebUrl(newTableSlug ?? newTableId),
+                    cause,
+                },
+                exitCode: 1,
+            });
+        }
+    }
+    return {
+        table_id: newTableId,
+        table_slug: newTableSlug ?? null,
+        created_table: createdTable,
+        column_count: columns.length,
+        row_count: processed,
+        mode: upsertKey ? "upsert" : "insert",
+        ...(skippedRelationColumns.length > 0
+            ? {
+                skipped_relation_columns: skippedRelationColumns,
+                note: `${skippedRelationColumns.length} native relation column(s) were not imported: a relation must be created on this side with \`tables relate\` once both tables exist.`,
+            }
+            : {}),
+        ...(upsertKey
+            ? { upsert_key: upsertKey, inserted_count: insertedCount, updated_count: updatedCount }
+            : {}),
+        source_table: bundle.tableSummary,
+        schema_version: bundle.schemaVersion,
+        web_url: tableWebUrl(newTableSlug ?? newTableId),
+    };
+}
+// Builds the exact CLI command that resumes a failed `import-bundle` into the
+// table it already created. Always targets that table with --into + --key so the
+// resume is idempotent; falls back to a <uniqueColumn> placeholder when the
+// original run had no key (insert mode can't be safely auto-resumed).
+function buildBundleResumeCommand(input) {
+    const fileArg = /\s/.test(input.file) ? `"${input.file}"` : input.file;
+    const parts = [
+        // Must be the binary the user actually invoked. Hardcoding "oxygen" meant an
+        // `oxygen-dev` import printed a resume command that, pasted verbatim, re-ran
+        // a DEV bundle against PRODUCTION (OXY-4360).
+        `${input.binaryName} tables import-bundle`,
+        `--file ${fileArg}`,
+        `--into ${input.tableId}`,
+        `--key ${input.key ?? "<uniqueColumn>"}`,
+    ];
+    // 500 is the default in normalizeImportBatchSize; only echo --batch-size when
+    // the user picked something else, to keep the resume command minimal.
+    if (input.batchSize !== 500) {
+        parts.push(`--batch-size ${input.batchSize}`);
+    }
+    return parts.join(" ");
+}
+function toBundleColumn(column) {
+    // Persist only the fields `tables create` knows how to ingest. Drop ids,
+    // physical column names, archivedAt — those are tenant-local and would
+    // collide on import.
+    return {
+        key: column.key,
+        ...(column.label !== undefined ? { label: column.label } : {}),
+        ...(column.dataType !== undefined ? { dataType: column.dataType } : {}),
+        ...(column.kind !== undefined ? { kind: column.kind } : {}),
+        ...(column.semanticType !== undefined ? { semanticType: column.semanticType } : {}),
+        ...(column.definition !== undefined ? { definition: column.definition } : {}),
+        ...(column.position !== undefined ? { position: column.position } : {}),
+    };
+}
+function bundleColumnToCreateInput(column) {
+    const label = typeof column.label === "string" && column.label.trim()
+        ? column.label.trim()
+        : typeof column.key === "string"
+            ? column.key
+            : null;
+    if (!label) {
+        throw new OxygenError("invalid_bundle", "Bundle column is missing label/key.", {
+            details: { column },
+            exitCode: 1,
+        });
+    }
+    return {
+        label,
+        ...(typeof column.key === "string" ? { key: column.key } : {}),
+        ...(typeof column.dataType === "string" ? { dataType: column.dataType } : {}),
+        ...(typeof column.kind === "string" ? { kind: column.kind } : {}),
+        ...(typeof column.semanticType === "string" ? { semanticType: column.semanticType } : {}),
+        ...(column.definition && typeof column.definition === "object" && !Array.isArray(column.definition)
+            ? { definition: column.definition }
+            : {}),
+    };
+}
+// Opens either bundle format. A streamed (version 2) bundle is recognised by
+// its header line and read line by line, so a multi-GB file never has to fit
+// in memory; a single-document (version 1) bundle is parsed whole, as before.
+async function openTableBundle(filePath) {
+    if (!existsSync(filePath)) {
+        throw new OxygenError("invalid_input", `Bundle file not found: ${filePath}`, {
+            details: { file: filePath },
+            exitCode: 1,
+        });
+    }
+    const firstLine = readFirstBundleLine(filePath);
+    const header = firstLine === null ? null : parseJsonObjectOrNull(firstLine);
+    if (header && readBundleNumber(header.schemaVersion) === TABLE_BUNDLE_SCHEMA_VERSION) {
+        return openStreamedTableBundle(filePath, header);
+    }
+    let raw;
+    try {
+        raw = readFileSync(filePath, "utf8");
+    }
+    catch (error) {
+        if (error instanceof RangeError || error.code === "ERR_STRING_TOO_LONG") {
+            throw new OxygenError("bundle_too_large", "This bundle is one JSON document too large to load into memory. Re-export it with the current CLI (`oxygen tables export-bundle <table> --output <path>`), which writes one row per line and imports at any size.", { details: { file: filePath }, exitCode: 1 });
+        }
+        throw error;
+    }
+    const parsed = parseBundleFile(raw);
+    return {
+        schemaVersion: parsed.schemaVersion,
+        tableName: parsed.tableName,
+        tableSummary: parsed.tableSummary,
+        columns: parsed.columns,
+        rowCount: parsed.rows.length,
+        preloadedRows: parsed.rows,
+        rows: () => iterateArrayRows(parsed.rows),
+    };
+}
+async function* iterateArrayRows(rows) {
+    for (const row of rows)
+        yield row;
+}
+function openStreamedTableBundle(filePath, header) {
+    const rawColumns = header.columns;
+    if (!Array.isArray(rawColumns)) {
+        throw new OxygenError("invalid_bundle", "Streamed bundle header is missing a columns array.", {
+            details: { file: filePath },
+            exitCode: 1,
+        });
+    }
+    const tableSummary = readRecord(header, "table");
+    // The totals trailer is the last thing the exporter writes, so its absence
+    // means the export was interrupted: refuse before creating anything rather
+    // than importing a silently truncated table.
+    const trailer = parseJsonObjectOrNull(readLastBundleLine(filePath));
+    const totals = trailer ? readRecord(trailer, "totals") : null;
+    const rowCount = totals ? readBundleNumber(totals.rowCount) : null;
+    if (rowCount === null) {
+        throw new OxygenError("invalid_bundle", "This streamed bundle has no totals trailer, so the export that produced it was interrupted before it finished. Re-run `oxygen tables export-bundle` and import the complete file.", { details: { file: filePath }, exitCode: 1 });
+    }
+    return {
+        schemaVersion: TABLE_BUNDLE_SCHEMA_VERSION,
+        tableName: tableSummary
+            ? (readRecordString(tableSummary, "name") ?? readRecordString(tableSummary, "displayName"))
+            : null,
+        tableSummary,
+        columns: rawColumns.filter((entry) => Boolean(entry) && typeof entry === "object" && !Array.isArray(entry)),
+        rowCount,
+        preloadedRows: null,
+        rows: () => iterateStreamedBundleRows(filePath),
+    };
+}
+async function* iterateStreamedBundleRows(filePath) {
+    const fileStream = createReadStream(filePath, { encoding: "utf8" });
+    const reader = createInterface({ input: fileStream, crlfDelay: Infinity });
+    let lineNumber = 0;
+    try {
+        for await (const line of reader) {
+            lineNumber += 1;
+            if (lineNumber === 1 || !line.trim())
+                continue;
+            const entry = parseJsonObjectOrNull(line);
+            if (!entry) {
+                throw new OxygenError("invalid_bundle", `Line ${lineNumber} of the bundle is not a JSON object.`, {
+                    details: { file: filePath, line: lineNumber },
+                    exitCode: 1,
+                });
+            }
+            if ("totals" in entry)
+                return;
+            const row = readRecord(entry, "row");
+            if (!row) {
+                throw new OxygenError("invalid_bundle", `Line ${lineNumber} of the bundle is neither a row nor the totals trailer.`, { details: { file: filePath, line: lineNumber }, exitCode: 1 });
+            }
+            yield row;
+        }
+    }
+    finally {
+        reader.close();
+        fileStream.destroy();
+    }
+}
+// Batches the bundle's rows for the shared import writer, stripping tenant-local
+// fields and enforcing the upsert key on the way through.
+async function* readBundleBatches(input) {
+    let batch = [];
+    let rowNumber = 0;
+    for await (const rawRow of input.bundle.rows()) {
+        rowNumber += 1;
+        const row = stripRowForImport(rawRow, input.validColumnKeys);
+        if (input.upsertKey && (row[input.upsertKey] === undefined || row[input.upsertKey] === null)) {
+            throw new OxygenError("invalid_bundle", `Row ${rowNumber} is missing a value for the upsert key "${input.upsertKey}".`, {
+                details: {
+                    key: input.upsertKey,
+                    row_number: rowNumber,
+                    table_id: input.tableId,
+                    resume_command: input.resumeCommand,
+                },
+                exitCode: 1,
+            });
+        }
+        batch.push(row);
+        if (batch.length >= input.batchSize) {
+            yield batch;
+            batch = [];
+        }
+    }
+    if (batch.length > 0)
+        yield batch;
+}
+// Reads up to the first newline without loading the file. Returns null when no
+// newline appears inside the scan window and the file is larger than it, which
+// is what a huge single-document bundle looks like.
+function readFirstBundleLine(filePath) {
+    const size = statSync(filePath).size;
+    const span = Math.min(size, TABLE_BUNDLE_HEADER_SCAN_BYTES);
+    if (span === 0)
+        return "";
+    const fd = openSync(filePath, "r");
+    try {
+        const buffer = Buffer.alloc(span);
+        const read = readSync(fd, buffer, 0, span, 0);
+        const text = buffer.subarray(0, read).toString("utf8");
+        const newline = text.indexOf("\n");
+        if (newline >= 0)
+            return text.slice(0, newline);
+        return read < size ? null : text;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function readLastBundleLine(filePath) {
+    const size = statSync(filePath).size;
+    const span = Math.min(size, TABLE_BUNDLE_TRAILER_SCAN_BYTES);
+    if (span === 0)
+        return "";
+    const fd = openSync(filePath, "r");
+    try {
+        const buffer = Buffer.alloc(span);
+        const read = readSync(fd, buffer, 0, span, size - span);
+        const lines = buffer.subarray(0, read).toString("utf8").split("\n").map((line) => line.trim()).filter(Boolean);
+        return lines.at(-1) ?? "";
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function parseJsonObjectOrNull(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function parseBundleFile(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw new OxygenError("invalid_bundle", "Bundle file is not valid JSON.", {
+            details: { reason: error instanceof Error ? error.message : "unknown" },
+            exitCode: 1,
+        });
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new OxygenError("invalid_bundle", "Bundle file must be a JSON object.", { exitCode: 1 });
+    }
+    const record = parsed;
+    const schemaVersion = typeof record.schemaVersion === "number" ? record.schemaVersion : 1;
+    // A version-2 bundle never reaches this parser (openTableBundle streams it),
+    // so a single document claiming any other version is from a CLI this one
+    // does not know.
+    if (schemaVersion !== TABLE_BUNDLE_LEGACY_SCHEMA_VERSION) {
+        throw new OxygenError("unsupported_bundle_version", `Bundle schema version ${schemaVersion} is not supported by this CLI.`, {
+            details: { supported: TABLE_BUNDLE_SUPPORTED_SCHEMA_VERSIONS, got: schemaVersion },
+            exitCode: 1,
+        });
+    }
+    const rawColumns = record.columns;
+    if (!Array.isArray(rawColumns)) {
+        throw new OxygenError("invalid_bundle", "Bundle is missing a columns array.", { exitCode: 1 });
+    }
+    const rawRows = record.rows;
+    if (!Array.isArray(rawRows)) {
+        throw new OxygenError("invalid_bundle", "Bundle is missing a rows array.", { exitCode: 1 });
+    }
+    const tableSummary = record.table && typeof record.table === "object" && !Array.isArray(record.table)
+        ? record.table
+        : null;
+    return {
+        schemaVersion,
+        tableName: tableSummary
+            ? (readRecordString(tableSummary, "name") ?? readRecordString(tableSummary, "displayName"))
+            : null,
+        tableSummary,
+        columns: rawColumns.filter((entry) => Boolean(entry) && typeof entry === "object" && !Array.isArray(entry)),
+        rows: rawRows.filter((entry) => Boolean(entry) && typeof entry === "object" && !Array.isArray(entry)),
+    };
+}
+function stripRowForImport(row, validColumnKeys) {
+    const out = {};
+    for (const [key, value] of Object.entries(row)) {
+        if (key === "_row_id" || key === "_created_at" || key === "_updated_at")
+            continue;
+        if (validColumnKeys.size > 0 && !validColumnKeys.has(key))
+            continue;
+        out[key] = value;
+    }
+    return out;
+}
+function readBundleNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string" && value.trim() && Number.isFinite(Number(value)))
+        return Number(value);
+    return null;
+}
+async function readRowsFile(path, format, sheet) {
+    return await parseRowsFileBuffer(readFileSync(path), format, sheet ? { sheet } : {});
+}
+function normalizeCreatedTableUpsertKey(value, keyBySource) {
+    if (!value)
+        return undefined;
+    return keyBySource[value] ?? value;
+}
+// Deep-links must name the host the command actually talked to. This hardcoded
+// https://oxygen-agent.com, so every `oxygen-dev` bundle export/import handed
+// back a PRODUCTION url for a table that only exists on dev (OXY-4360).
+// `defaultApiUrl()` is the same resolver the request layer uses, so the link and
+// the call can no longer disagree.
+function tableWebUrl(tableIdOrSlug) {
+    return oxygenAppUrl(defaultApiUrl(), `/tables/${encodeURIComponent(tableIdOrSlug)}`);
+}
+function formatImportFileSizeLimit(tier) {
+    return formatImportByteSize(PLAN_LIMITS[tier].import.maxFileBytes);
+}
+function formatImportByteSize(bytes) {
+    const mebibytes = bytes / (1024 * 1024);
+    return mebibytes >= 1024 && mebibytes % 1024 === 0 ? `${mebibytes / 1024} GiB` : `${Math.round(mebibytes)} MiB`;
+}
+// Help copy reads the shared ceiling so the number can never drift from the
+// one the server enforces and the import writer splits against.
+function formatJsonBodyLimit() {
+    return `${Math.round(MAX_CLI_JSON_BODY_BYTES / 1_000_000)} MB`;
+}
+// A backgrounded import returns as soon as the file is staged, with counts.rows
+// still 0 while the worker loads. With no follow-up command in the envelope that
+// reads as a truncated import - which is how a 500-row `--batch-size` default
+// gets mistaken for a 500-row cap. `table-ingestions wait` takes the ingestion
+// run's own id (`ingestionRunId`), not the linked `runId`, which 404s.
+function withImportWaitNextStep(envelope) {
+    const ingestionRunId = readRecordString(envelope, "ingestionRunId")
+        ?? readRecordString(readRecord(envelope, "ingestionRun"), "id");
+    if (!ingestionRunId)
+        return envelope;
+    const nextStep = `oxygen table-ingestions wait ${ingestionRunId}`;
+    process.stderr.write(`note: rows load in the background - watch with ${nextStep}\n`);
+    return { ...envelope, next_step: nextStep };
+}
+function normalizeImportBatchSize(value) {
+    const batchSize = readPositiveInt(value) ?? 500;
+    if (batchSize > 5000) {
+        throw new OxygenError("invalid_number", "Import batch size cannot exceed 5000.", {
+            details: { value },
+            exitCode: 1,
+        });
+    }
+    return batchSize;
+}
+function hashImportFile(path) {
+    return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+// `tables tidy-suggest` is a read-only analysis (no credits, no writes): it
+// surfaces duplicate columns, formatting inconsistencies, hide candidates, and
+// value-sanity findings so the caller can pick which reversible cleanup to run
+// next. --json returns the raw report envelope; the default rendering compacts
+// the four sections for a terminal reader and echoes the deep-link.
+async function handleTablesTidySuggestAction(table, options) {
+    try {
+        const limit = readPositiveInt(options.limit);
+        const categories = readCsvOption(options.categories);
+        const data = await requestOxygen("/api/cli/tables/tidy/suggest", {
+            method: "POST",
+            body: {
+                table,
+                ...(limit ? { limit } : {}),
+                ...(categories.length ? { categories } : {}),
+            },
+        });
+        if (options.json) {
+            writeJson(success("tables tidy-suggest", data));
+            return;
+        }
+        process.stdout.write(formatTidySuggestions(data));
+    }
+    catch (error) {
+        emitCliFailure("tables tidy-suggest", error);
+    }
+}
+function formatTidyCount(value) {
+    return typeof value === "number" && Number.isFinite(value) ? String(value) : "0";
+}
+function formatTidyPercent(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return "—";
+    return `${(value * 100).toFixed(0)}%`;
+}
+// Render one tidy-suggest section (header + count, then either a dim "None" or
+// one formatted line per item) into the shared `lines` buffer. Extracted so the
+// four sections share a single control-flow shape instead of repeating it.
+function pushTidySection(lines, styles, title, items, renderItem) {
+    lines.push("", styles.bold(`${title} (${items.length})`));
+    if (items.length === 0) {
+        lines.push(`  ${styles.dim("None")}`);
+        return;
+    }
+    for (const item of items) {
+        lines.push(renderItem(item));
+    }
+}
+function formatTidySuggestions(data) {
+    const styles = ansi(output.isTTY === true && !process.env.NO_COLOR);
+    const duplicates = Array.isArray(data.duplicateColumns) ? data.duplicateColumns : [];
+    const formatting = Array.isArray(data.formattingIssues) ? data.formattingIssues : [];
+    const hide = Array.isArray(data.hideSuggestions) ? data.hideSuggestions : [];
+    const valueSanity = Array.isArray(data.valueSanity) ? data.valueSanity : [];
+    const notComputed = Array.isArray(data.notComputed) ? data.notComputed : [];
+    const lines = [
+        "",
+        `${styles.bold("Table tidy suggestions")} ${styles.dim(`(sampled ${formatTidyCount(data.sampledRows)} of ${formatTidyCount(data.rowCount)} rows)`)}`,
+    ];
+    pushTidySection(lines, styles, "Duplicate columns", duplicates, (dup) => {
+        const loser = dup.loserKey ?? dup.loserColumnId ?? "?";
+        const survivor = dup.survivorKey ?? dup.survivorColumnId ?? "?";
+        return `  ${loser} ${styles.dim("→ duplicate of")} ${survivor} ${styles.dim(`(${formatTidyPercent(dup.similarity)} match, ${dup.recommendation ?? "review"})`)}`;
+    });
+    pushTidySection(lines, styles, "Formatting issues", formatting, (issue) => {
+        const sampleCount = Array.isArray(issue.sampleRowIds) ? issue.sampleRowIds.length : 0;
+        const column = issue.columnKey ?? issue.columnId ?? "?";
+        return `  ${column} ${styles.dim(`— ${issue.issue ?? "issue"}`)}${issue.detail ? `: ${issue.detail}` : ""} ${styles.dim(`(${sampleCount} sample row(s))`)}`;
+    });
+    pushTidySection(lines, styles, "Hide suggestions", hide, (suggestion) => {
+        const column = suggestion.columnKey ?? suggestion.columnId ?? "?";
+        return `  ${column} ${styles.dim(`— ${suggestion.reason ?? "hide"} (${formatTidyPercent(suggestion.fillRate)} filled)`)}`;
+    });
+    pushTidySection(lines, styles, "Value-sanity findings", valueSanity, (finding) => {
+        const column = finding.columnKey ?? finding.columnId ?? "?";
+        return `  ${column} ${styles.dim(`row ${finding.rowId ?? "?"} — ${finding.reason ?? "check value"}`)}`;
+    });
+    // Printed even when empty, like the four finding sections: a reader who never
+    // sees this heading cannot tell a measured column from an unmeasured one.
+    pushTidySection(lines, styles, "Not measured", notComputed, (entry) => {
+        const column = entry.columnKey ?? entry.columnId ?? "?";
+        return `  ${column} ${styles.dim(`— ${entry.message ?? entry.reason ?? "could not be measured"}`)}`;
+    });
+    const link = data.deepLink ?? data.web_url ?? data.url;
+    if (link) {
+        lines.push("", styles.dim(`View table: ${link}`));
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+// `tables delete-row|delete-rows` for a human reader: a deleted row's lead stays
+// enrolled in its campaigns, so name them where the delete was typed.
+function writeRowDeleteWarnings(data) {
+    const payload = asPayloadRecord(data);
+    const warnings = Array.isArray(payload?.warnings) ? payload.warnings : [];
+    for (const entry of warnings) {
+        const warning = asPayloadRecord(entry);
+        if (warning && typeof warning.message === "string")
+            process.stderr.write(`Warning: ${warning.message}\n`);
+    }
+}
+export function registerTablesFamily(program, handleAsyncAction, binaryName) {
+    const tablesCommand = program
+        .command("tables")
+        .description("Tenant workspace tables: create, import rows (CSV, a link, a HubSpot saved list, a Pipedrive saved filter, Supabase), enrich with columns, and run them. `tables sources` lists every way a table can start.")
+        .addCommand(new Command("sources")
+        .description("List every way a table can start — imports, company/people/signal sources, webhooks, functions — with the provider count and per-row credit estimate behind each. Free; nothing is called or written. The same catalog the web New table picker shows.")
+        .option("--group <group>", "Only one group: Companies, People, \"Professional Network\" (or linkedin), Imports, CRM, Signals, or Tables.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("tables sources", options, () => {
+            const params = new URLSearchParams();
+            const group = readOption(options.group);
+            if (group)
+                params.set("group", group);
+            const qs = params.toString() ? `?${params.toString()}` : "";
+            return requestOxygen(`/api/cli/tables/sources${qs}`);
+        });
+    }))
+        .addCommand(new Command("records")
+        .description("Copy a Records object or saved view into a working Table, once or kept in sync. One-way: Records stay unchanged, the Table is keyed by record_id, cells edited in the Table are kept, and records that leave the source stay as rows with in_records=false.")
+        .addCommand(new Command("import")
+        .description("Create a Table from a Records object or saved view. --dry-run counts the records and lists the columns without creating anything. --refresh sync also arms a schedule (a Workflow you can pause) that repeats the copy. The copy costs 0 credits and calls no provider; each scheduled sync bills one workflow step (credits_per_scheduled_sync).")
+        .requiredOption("--object <slug>", "Records object slug, such as companies, people or deals (`crm objects`).")
+        .option("--view <id|name>", "Saved view on that object, by id or exact name (`tables views list <object table>`). Omit for every record.")
+        .option("--name <table>", "Name for the new Table. Defaults to the object and view name.")
+        .option("--project <project>", "Project id or slug. Defaults to General.")
+        .option("--refresh <once|sync>", "once (default) copies now; sync also keeps it in sync (needs --approved).")
+        .option("--every <cadence>", "With --refresh sync: hourly, every_6h, daily@<hour> or weekly@<day><hour> (UTC). Default daily@6.")
+        .option("--dry-run", "Preview without creating the Table.")
+        .option("--approved", "Approve the standing per-sync charge that --refresh sync arms.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("tables records import", options, () => requestOxygen("/api/cli/tables/records-import", {
+            method: "POST",
+            body: {
+                object: options.object,
+                ...(readOption(options.view) ? { view: readOption(options.view) } : {}),
+                ...(readOption(options.name) ? { name: readOption(options.name) } : {}),
+                ...(readOption(options.project) ? { project: readOption(options.project) } : {}),
+                ...(readOption(options.refresh) ? { refresh: readOption(options.refresh) } : {}),
+                ...(readOption(options.every) ? { every: readOption(options.every) } : {}),
+                ...(options.dryRun ? { dry_run: true } : {}),
+                ...(options.approved ? { approved: true } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("sync")
+        .description("Copy a Records-imported Table's source again now: new records are added, changed cells updated, edited cells kept, and departed records marked in_records=false (they flip back if they return). Without --refresh the schedule stays as it is; --refresh sync --approved arms or retimes it, --refresh once removes it. preserved_cells counts copied-field cells left as someone edited them in the Table; columns you added are never touched and not counted. Running it now costs 0 credits; each scheduled sync bills one workflow step (credits_per_scheduled_sync in an import dry run).")
+        .argument("<table>", "Table id, slug or URL.")
+        .option("--refresh <once|sync>", "Omit to keep the schedule; sync (with --approved) arms or retimes it; once removes it.")
+        .option("--every <cadence>", "With --refresh sync: hourly, every_6h, daily@<hour> or weekly@<day><hour> (UTC). Default daily@6.")
+        .option("--dry-run", "Count what would change without writing.")
+        .option("--approved", "Approve the standing per-sync charge that --refresh sync arms.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables records sync", options, () => requestOxygen("/api/cli/tables/records-sync", {
+            method: "POST",
+            body: {
+                table,
+                ...(readOption(options.refresh) ? { refresh: readOption(options.refresh) } : {}),
+                ...(readOption(options.every) ? { every: readOption(options.every) } : {}),
+                ...(options.dryRun ? { dry_run: true } : {}),
+                ...(options.approved ? { approved: true } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("status")
+        .description("Show a Records-imported Table's source object and view, the last sync's counts and its schedule. Read-only, 0 credits.")
+        .argument("<table>", "Table id, slug or URL.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables records status", options, () => requestOxygen(`/api/cli/tables/records-sync?table=${encodeURIComponent(table)}`));
+    })))
+        .addCommand(new Command("hubspot")
+        .description("Import HubSpot contacts or companies into a new table or Records, optionally from a saved list and with do-not-contact suppression.")
+        .addCommand(new Command("lists")
+        .description("List the connected portal's saved contact/company segments and readable identity properties. Reads definitions only; no memberships, rows, or writes. Free — 0 Oxygen credits, uses your HubSpot API quota.")
+        .option("--query <text>", "Optional list-name search.")
+        .option("--connection <id>", "HubSpot connection id; defaults to the first connected account.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("tables hubspot lists", options, () => {
+            const params = new URLSearchParams();
+            const query = readOption(options.query);
+            if (query)
+                params.set("query", query);
+            const connection = readOption(options.connection);
+            if (connection)
+                params.set("connection_id", connection);
+            const suffix = params.toString();
+            return requestOxygen(`/api/cli/tables/hubspot-import${suffix ? `?${suffix}` : ""}`);
+        });
+    }))
+        .addCommand(new Command("import")
+        .description("Preview or import HubSpot contacts/companies into a new table or Records. Named do-not-contact lists must synchronize before any import. Nothing is enrolled or sent. Live requires the exact dry-run fingerprint and approval.")
+        .option("--list <id>", "HubSpot saved-list id. Omit with --object to import all records; discover ids with `oxygen tables hubspot lists`.")
+        .option("--object <object>", "HubSpot object: contacts or companies. Required without --list; defaults to contacts for a saved list.")
+        .option("--destination <destination>", "Import into table (default) or records.")
+        .option("--connection <id>", "HubSpot connection id; defaults to the first connected account.")
+        .option("--sample", "Read up to 50 real records during the dry-run preview; uses HubSpot API quota and makes no writes.")
+        .option("--dnc-list <id>", "HubSpot contact-list id to suppress into do-not-contact before importing.")
+        .option("--company-dnc-list <id>", "Optional HubSpot company-list id to suppress organization-wide.")
+        .option("--no-dnc", "Import without suppressing anything. Required if you pass no --dnc-list, so an unsuppressed import is never accidental.")
+        .option("--name <table>", "Display name for the new table.")
+        .option("--project <project>", "Project id or slug. Defaults to General.")
+        .option("--contact-linkedin-property <name>", "Optional contact property holding a public LinkedIn /in/ URL.")
+        .option("--contact-company-domain-property <name>", "Optional contact property copied to company_domain.")
+        .option("--contact-company-linkedin-property <name>", "Optional contact property copied to company_linkedin_url.")
+        .option("--company-domain-property <name>", "Company domain property (default domain).", "domain")
+        .option("--company-linkedin-property <name>", "Optional company LinkedIn URL property.")
+        .option("--contact-properties <list>", "Comma-separated extra HubSpot contact properties to hydrate (max 50).")
+        .option("--max-records-per-list <n>", "Optional record limit; omit to import all selected records.")
+        .option("--max-credits <n>", "Hard credits cap per delivery.", "10")
+        .option("--once", "Import once instead of refreshing on a schedule.")
+        .option("--cron <expression>", "Refresh schedule; default every 15 minutes.")
+        .option("--timezone <iana>", "Schedule timezone; default UTC.")
+        .option("--reviewed-fingerprint <hash>", "Exact dry-run fingerprint, required for live.")
+        .option("--idempotency-key <key>", "Optional first-run idempotency key.")
+        .option("--live", "Create the import and queue the first durable run.")
+        .option("--approved", "Approve the reviewed reads, DNC writes, and destination upserts.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("tables hubspot import", options, () => {
+            const list = readOption(options.list);
+            const object = readOption(options.object);
+            const destination = readOption(options.destination);
+            if (!list && !object)
+                throw new OxygenError("invalid_request", "Pass --list or --object contacts|companies to select what to import.", { exitCode: 1 });
+            if (object && object !== "contacts" && object !== "companies")
+                throw new OxygenError("invalid_request", "--object must be contacts or companies.", { exitCode: 1 });
+            if (destination && destination !== "table" && destination !== "records")
+                throw new OxygenError("invalid_request", "--destination must be table or records.", { exitCode: 1 });
+            const dncList = readOption(options.dncList);
+            const companyDncList = readOption(options.companyDncList);
+            // Commander maps `--no-dnc` to `dnc: false`; the default is
+            // `true`, so an unset flag is indistinguishable from an opt-in.
+            // Requiring one of the two means an import that suppresses
+            // nothing is always something the operator typed, which is the
+            // same guarantee the web lane gets from its preview fingerprint.
+            const optedOut = options.dnc === false;
+            if (!dncList && !companyDncList && !optedOut) {
+                // invalid_request, not a bare Error: handleAsyncAction reports
+                // an uncoded throw as `unexpected_error`, which tells a calling
+                // agent that OXYGEN broke when the caller simply omitted a flag.
+                throw new OxygenError("invalid_request", "Pass --dnc-list (and/or --company-dnc-list) to suppress a HubSpot list, or --no-dnc to import without suppressing anything. Run `oxygen tables hubspot lists` to see the ids your portal exposes.", { exitCode: 1 });
+            }
+            if (optedOut && (dncList || companyDncList)) {
+                throw new OxygenError("invalid_request", "--no-dnc cannot be combined with --dnc-list or --company-dnc-list.", { exitCode: 1 });
+            }
+            const maxRecords = readPositiveInt(options.maxRecordsPerList);
+            const maxCredits = readPositiveNumber(options.maxCredits);
+            if (options.maxRecordsPerList !== undefined && (maxRecords === undefined || !Number.isSafeInteger(maxRecords)))
+                throw new OxygenError("invalid_request", "--max-records-per-list must be a positive integer.", { exitCode: 1 });
+            if (maxCredits === undefined)
+                throw new OxygenError("spend_cap_required", "--max-credits must be positive.", { exitCode: 1 });
+            const fingerprint = readOption(options.reviewedFingerprint);
+            if (options.live && !fingerprint)
+                throw new OxygenError("approval_required", "Live import requires --reviewed-fingerprint from the exact dry-run. Run the same command without --live first.", { exitCode: 1 });
+            const contactProperties = readOption(options.contactProperties)
+                ?.split(",")
+                .map((entry) => entry.trim())
+                .filter(Boolean) ?? [];
+            return requestOxygen("/api/cli/tables/hubspot-import", {
+                method: "POST",
+                body: {
+                    lead_list_id: list ?? null,
+                    ...(object ? { object } : {}),
+                    ...(destination ? { destination } : {}),
+                    ...(readOption(options.connection) ? { connection_id: readOption(options.connection) } : {}),
+                    ...(options.sample ? { sample: true } : {}),
+                    dnc_list_id: dncList ?? null,
+                    company_dnc_list_id: companyDncList ?? null,
+                    table_name: readOption(options.name) ?? null,
+                    project: readOption(options.project) ?? null,
+                    contact_linkedin_property: readOption(options.contactLinkedinProperty) ?? null,
+                    contact_company_domain_property: readOption(options.contactCompanyDomainProperty) ?? null,
+                    contact_company_linkedin_property: readOption(options.contactCompanyLinkedinProperty) ?? null,
+                    company_domain_property: readOption(options.companyDomainProperty) ?? "domain",
+                    company_linkedin_property: readOption(options.companyLinkedinProperty) ?? null,
+                    contact_properties: contactProperties,
+                    max_records_per_list: maxRecords ?? null,
+                    refresh: options.once ? "once" : "scheduled",
+                    cron: readOption(options.cron) ?? undefined,
+                    timezone: readOption(options.timezone) ?? undefined,
+                    max_credits: maxCredits,
+                    mode: options.live ? "live" : "dry_run",
+                    ...(options.approved ? { approved: true } : {}),
+                    ...(fingerprint ? { reviewed_fingerprint: fingerprint } : {}),
+                    ...(readOption(options.idempotencyKey) ? { idempotency_key: readOption(options.idempotencyKey) } : {}),
+                },
+            });
+        });
+    })))
+        .addCommand(new Command("pipedrive")
+        .description("Import a Pipedrive saved people filter into a new Oxygen table, optionally suppressing a Pipedrive do-not-contact filter first. Connect Pipedrive with an API token first: `oxygen integrations connect pipedrive --api-key <token>`.")
+        .addCommand(addContractFlags(new Command("filters")
+        .description("Read connected Pipedrive saved filters and custom-field definitions; no people imported. Four BYOK fees may apply. Use --approved with --max-credits to authorize this read; refusal returns the required cap without provider calls."), PIPEDRIVE_CATALOG_QUERY_CONTRACT, {
+        query: { valueName: "<text>" },
+        approved: { noNegate: true },
+        max_credits: { valueName: "<n>" },
+    })
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("tables pipedrive filters", options, () => {
+            const params = pipedriveCatalogQueryParams(readContractFlags(options, PIPEDRIVE_CATALOG_QUERY_CONTRACT, { approved: { noNegate: true } }));
+            const suffix = params.toString();
+            return requestOxygen(`/api/cli/tables/pipedrive-import${suffix ? `?${suffix}` : ""}`);
+        });
+    }))
+        .addCommand(new Command("import")
+        .description("Preview or run a Pipedrive saved people filter into a NEW table. Any do-not-contact filter you name is synchronized first and no row lands unless it fully succeeds. Nothing is ever enrolled or sent. Live requires the exact dry-run fingerprint and approval.")
+        .requiredOption("--filter <id>", "Pipedrive people-filter id whose persons become rows. Run `oxygen tables pipedrive filters` to see the ids your account exposes.")
+        .option("--dnc-filter <id>", "Pipedrive people-filter id to suppress into do-not-contact before importing (a filter on Marketing status = Unsubscribed is the usual choice).")
+        .option("--org-dnc-filter <id>", "Optional Pipedrive organization-filter id to suppress organization-wide.")
+        .option("--no-dnc", "Import without suppressing anything. Required if you pass no --dnc-filter, so an unsuppressed import is never accidental.")
+        .option("--name <table>", "Display name for the new table.")
+        .option("--project <project>", "Project id or slug. Defaults to General.")
+        .option("--person-linkedin-field <key>", "Optional person field key holding a public LinkedIn /in/ URL (custom keys are 40-character hex; see `tables pipedrive filters`).")
+        .option("--person-title-field <key>", "Optional person field key copied to title. Pipedrive has no native job-title field.")
+        .option("--org-domain-field <key>", "Optional organization field key holding the website or domain. Pipedrive has no native domain field; never inferred from email.")
+        .option("--org-linkedin-field <key>", "Optional organization field key holding its LinkedIn company page.")
+        .option("--person-fields <list>", "Comma-separated extra Pipedrive person field keys to hydrate into pipedrive_fields (max 15).")
+        .option("--no-hydrate-organizations", "Skip reading each person's organization; company columns stay empty.")
+        .option("--max-records-per-filter <n>", "Complete-snapshot cap (1-5000), enforced while the filter is read.", "5000")
+        .option("--max-credits <n>", "Hard credits cap per delivery.", "10")
+        .option("--once", "Import once instead of refreshing on a schedule.")
+        .option("--cron <expression>", "Refresh schedule; default every 15 minutes.")
+        .option("--timezone <iana>", "Schedule timezone; default UTC.")
+        .option("--reviewed-fingerprint <hash>", "Exact dry-run fingerprint, required for live.")
+        .option("--idempotency-key <key>", "Optional first-run idempotency key.")
+        .option("--live", "Create the table and queue the first durable run.")
+        .option("--approved", "Approve the reviewed bounded reads, DNC writes, and table upserts.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("tables pipedrive import", options, () => {
+            const dncFilter = readOption(options.dncFilter);
+            const orgDncFilter = readOption(options.orgDncFilter);
+            // Same affirmative contract as `tables hubspot import`: an import
+            // that suppresses nothing is always something the operator typed.
+            const optedOut = options.dnc === false;
+            if (!dncFilter && !orgDncFilter && !optedOut) {
+                throw new OxygenError("invalid_request", "Pass --dnc-filter (and/or --org-dnc-filter) to suppress a Pipedrive filter, or --no-dnc to import without suppressing anything. Run `oxygen tables pipedrive filters` to see the ids your account exposes.", { exitCode: 1 });
+            }
+            if (optedOut && (dncFilter || orgDncFilter)) {
+                throw new OxygenError("invalid_request", "--no-dnc cannot be combined with --dnc-filter or --org-dnc-filter.", { exitCode: 1 });
+            }
+            const maxRecords = readPositiveInt(options.maxRecordsPerFilter);
+            const maxCredits = readPositiveNumber(options.maxCredits);
+            if (maxRecords === undefined || maxRecords > 5000)
+                throw new OxygenError("invalid_request", "--max-records-per-filter must be between 1 and 5000.", { exitCode: 1 });
+            if (maxCredits === undefined)
+                throw new OxygenError("spend_cap_required", "--max-credits must be positive.", { exitCode: 1 });
+            const fingerprint = readOption(options.reviewedFingerprint);
+            if (options.live && !fingerprint)
+                throw new OxygenError("approval_required", "Live import requires --reviewed-fingerprint from the exact dry-run. Run the same command without --live first.", { exitCode: 1 });
+            const personFields = readOption(options.personFields)
+                ?.split(",")
+                .map((entry) => entry.trim())
+                .filter(Boolean) ?? [];
+            const hydrateOrganizations = options.hydrateOrganizations !== false;
+            return requestOxygen("/api/cli/tables/pipedrive-import", {
+                method: "POST",
+                body: {
+                    filter_id: readOption(options.filter),
+                    dnc_filter_id: dncFilter ?? null,
+                    org_dnc_filter_id: orgDncFilter ?? null,
+                    table_name: readOption(options.name) ?? null,
+                    project: readOption(options.project) ?? null,
+                    person_linkedin_field: readOption(options.personLinkedinField) ?? null,
+                    person_title_field: readOption(options.personTitleField) ?? null,
+                    org_domain_field: readOption(options.orgDomainField) ?? null,
+                    org_linkedin_field: readOption(options.orgLinkedinField) ?? null,
+                    person_fields: personFields,
+                    hydrate_organizations: hydrateOrganizations,
+                    max_records_per_filter: maxRecords,
+                    refresh: options.once ? "once" : "scheduled",
+                    cron: readOption(options.cron) ?? undefined,
+                    timezone: readOption(options.timezone) ?? undefined,
+                    max_credits: maxCredits,
+                    mode: options.live ? "live" : "dry_run",
+                    ...(options.approved ? { approved: true } : {}),
+                    ...(fingerprint ? { reviewed_fingerprint: fingerprint } : {}),
+                    ...(readOption(options.idempotencyKey) ? { idempotency_key: readOption(options.idempotencyKey) } : {}),
+                },
+            });
+        });
+    })))
+        .addCommand(new Command("create")
+        .description("Create a table private to the active workspace. Free — 0 Oxygen credits. To create a table and import a file in one step, use `tables import --create <name>`.")
+        .argument("<name>", "Display name for the table.")
+        .requiredOption("--columns-json <json>", 'Required nonempty JSON array of column definitions, e.g. [{"key":"name","label":"Name","dataType":"text"},{"key":"domain","label":"Domain","dataType":"text"}]. A column may name a field type instead, as `columns add --type` does: {"label":"Stage","type":"select","options":["Lead","Won"]} (text, number, checkbox, date, json, markdown, image, select, multi_select, status). Inspect an existing shape with `oxygen tables describe <table>`.')
+        .option("--project <project>", "Project id or slug. Defaults to General.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (name, options) => {
+        await handleAsyncAction("tables create", options, () => requestOxygen("/api/cli/tables", {
+            method: "POST",
+            body: {
+                name,
+                columns: parseJsonArray(options.columnsJson),
+                ...(readOption(options.project) ? { project: readOption(options.project) } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("duplicate")
+        .description("Duplicate a workspace table. Copies row values unless --schema-only is set.")
+        .argument("<table>", "Source table id or slug.")
+        .option("--name <name>", "Display name for the duplicated table. Defaults to '<source> Copy'.")
+        .option("--schema-only", "Duplicate columns and definitions without copying row values.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables duplicate", options, () => requestOxygen(`/api/cli/tables/${encodeURIComponent(table)}/duplicate`, {
+            method: "POST",
+            body: {
+                ...(readOption(options.name) ? { name: readOption(options.name) } : {}),
+                ...(options.schemaOnly ? { include_rows: false } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("insert")
+        .description("Insert rows into a workspace table. Table writes cost 0 Oxygen credits; paid column runs are separate.")
+        .argument("<table>", "Table id or slug.")
+        .requiredOption("--rows-json <json>", 'JSON array of row objects keyed by column key, e.g. [{"name":"Acme","domain":"acme.test"},{"name":"Globex","domain":"globex.test"}].')
+        .option("--request-id <id>", "Stable retry key. Reuse it after a timeout to return the committed write without duplicating rows.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables insert", options, () => requestOxygen("/api/cli/tables/rows", {
+            method: "POST",
+            body: {
+                table,
+                rows: parseJsonArray(options.rowsJson),
+                ...(readOption(options.requestId) ? { request_id: readOption(options.requestId) } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("update")
+        .description("Update one workspace table row.")
+        .argument("<table>", "Table id or slug.")
+        .argument("<row_id>", "Workspace row UUID.")
+        .requiredOption("--values-json <json>", "JSON object of values keyed by column key.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, rowId, options) => {
+        await handleAsyncAction("tables update", options, () => requestOxygen("/api/cli/tables/rows/update", {
+            method: "POST",
+            body: {
+                table,
+                row_id: rowId,
+                values: parseJsonObject(options.valuesJson),
+            },
+        }));
+    }))
+        .addCommand(new Command("delete-row")
+        .description("Delete one workspace table row. A lead enrolled in a campaign stays enrolled; the response names those campaigns.")
+        .argument("<table>", "Table id or slug.")
+        .argument("<row_id>", "Workspace row UUID.")
+        .option("--metadata-json <json-or-file>", "Durable row deletion provenance.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, rowId, options) => {
+        await handleAsyncAction("tables delete-row", options, async () => {
+            const data = await requestOxygen("/api/cli/tables/rows/delete", {
+                method: "POST",
+                body: {
+                    table,
+                    row_id: rowId,
+                    ...(options.metadataJson !== undefined ? { metadata: parseJsonObject(readFileIfPresent(options.metadataJson)) } : {}),
+                },
+            });
+            if (!options.json)
+                writeRowDeleteWarnings(data);
+            return data;
+        });
+    }))
+        .addCommand(new Command("delete-rows")
+        .description("Delete exact workspace row IDs. For a matching filtered selection, use tables rows remove-selection. Campaign enrollments stay enrolled; the response names those campaigns.")
+        .addHelpText("after", "\nFor a matching filtered selection, use tables rows remove-selection --help.")
+        .argument("<table>", "Table id or slug.")
+        .option("--row-ids-json <json>", "JSON array of workspace row UUIDs.")
+        .option("--row-ids-file <path>", "File containing row UUIDs or rows with a _row_id column.")
+        .option("--row-id-column <key>", "Column to read from --row-ids-file. Defaults to _row_id.")
+        .option("--format <format>", "File format for --row-ids-file: json, jsonl, csv, or xlsx.")
+        .option("--sheet <name>", "Worksheet name when reading row IDs from an XLSX file.")
+        .option("--metadata-json <json-or-file>", "Durable row deletion provenance.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables delete-rows", options, async () => {
+            const rowIds = await readDeleteRowIdsOption(options);
+            const data = await requestOxygen("/api/cli/tables/rows/delete", {
+                method: "POST",
+                body: {
+                    table,
+                    row_ids: rowIds,
+                    ...(options.metadataJson !== undefined ? { metadata: parseJsonObject(readFileIfPresent(options.metadataJson)) } : {}),
+                },
+            });
+            if (!options.json)
+                writeRowDeleteWarnings(data);
+            return data;
+        });
+    }))
+        .addCommand(new Command("upsert")
+        .description("Insert or update rows in a workspace table by a column key.")
+        .argument("<table>", "Table id or slug.")
+        .requiredOption("--key <key>", "Column key used to match existing rows.")
+        .requiredOption("--rows-json <json>", "JSON array of row objects keyed by column key.")
+        .option("--return <mode>", "Response shape: summary, ids, or rows. Defaults to summary.")
+        .option("--dry-run", "Preview inserts, updates, duplicate keys, and field conflicts without writing rows.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables upsert", options, () => requestOxygen("/api/cli/tables/rows/upsert", {
+            method: "POST",
+            body: {
+                table,
+                key: options.key,
+                rows: parseJsonArray(options.rowsJson),
+                ...(readOption(options["return"]) ? { return: readOption(options["return"]) } : {}),
+                ...(options.dryRun ? { dry_run: true } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("import")
+        .description(`Import JSON, JSONL, CSV, or XLSX rows into a workspace table. The table write is free — 0 Oxygen credits. Files over ${LARGE_IMPORT_BACKGROUND_ROW_THRESHOLD} rows load durably in the background: the command returns a queued envelope and rows keep landing after it exits, so wait with the printed 'table-ingestions wait <id>' before reading row counts. ${IMPORT_FILE_LIMIT_HELP}`)
+        .argument("[table]", "Table id or slug. Omit when using --create.")
+        .option("--file <path>", "Input file path. Pass this or --url.")
+        .option("--url <https-link>", "Public link to fetch instead of a local file: a CSV, TSV, JSON, JSONL or XLSX file, or a Google Sheet shared with anyone-with-the-link or published to the web. Fetched server-side, up to 10 MB, 0 credits.")
+        .option("--preview", "With --url: fetch and show the columns, a row sample and the row count without creating or writing anything.")
+        .option("--format <format>", "json, jsonl, csv, or xlsx. Defaults from file extension.")
+        .option("--sheet <name>", "Worksheet name for XLSX imports. Defaults to the first sheet.")
+        .option("--create <name>", "Create a new table with columns inferred from the file before importing.")
+        .option("--project <project>", "Project id or slug for --create. Defaults to General.")
+        .option("--upsert-key <key>", "Column key used to upsert instead of inserting.")
+        .option("--skip-blank-cells", "Leave a row's existing value where the file's cell is blank instead of clearing it, so a partial update needs one file.")
+        .option("--batch-size <n>", `Requested rows per import chunk, not a limit on the file. Defaults to 500; values up to 5000 are accepted, but Oxygen splits writes to at most 500 rows (and smaller for wide rows, about ${formatJsonBodyLimit()} of JSON per request) so they fit request and worker lease budgets.`)
+        .option("--background", "Enqueue durable import chunks for the background worker.")
+        .option("--sync", `Force foreground import even for files above ${LARGE_IMPORT_BACKGROUND_ROW_THRESHOLD} rows. That threshold picks foreground vs background; it does not cap how many rows a file may hold.`)
+        .option("--max-concurrency <n>", "Maximum concurrent import chunks for background mode. Defaults to 5.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables import", options, () => importRows(table, options));
+    }))
+        .addCommand(new Command("export")
+        .description("Export workspace table rows as JSON, JSONL, CSV, or a human-readable table. Rows only, capped at 1000; to copy a whole table including its columns and every row, use `tables export-bundle`.")
+        .argument("<table>", "Table id or slug.")
+        .option("--format <format>", "json, jsonl, csv, or table. Defaults to json. Use table for a typed, human-readable rendering with thousands grouping.")
+        .option("--output <path>", "Write export content to a file.")
+        .option("--limit <n>", "Maximum rows to export. Defaults to 100; hard cap is 1000.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        if (!options.json && !options.output && options.format?.trim().toLowerCase() === "table") {
+            // The human-readable table itself, not a JSON object holding it as one
+            // escaped string (blind user evals, 2026-09-30). --json keeps the envelope.
+            try {
+                const { content } = await exportRows(table, options);
+                const text = typeof content === "string" ? content : "";
+                process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+            }
+            catch (error) {
+                emitCliFailure("tables export", error);
+            }
+            return;
+        }
+        await handleAsyncAction("tables export", options, () => exportRows(table, options));
+    }))
+        .addCommand(new Command("export-bundle")
+        .description("Export a workspace table as a portable bundle (schema + every row) for cross-environment / cross-org copies. Effect: reads the table and writes only a local file — 0 credits, nothing changes in the workspace. With --output the bundle streams to the file one row per line, so a table of any size exports; without it the whole bundle prints as one JSON document, which only fits a small table.")
+        .argument("<table>", "Table id or slug to export.")
+        .option("--output <path>", "Write the bundle to this file as line-delimited JSON: a header line with the table and columns, then one {\"row\":{…}} line per row carrying every column value plus the source _row_id, _created_at and _updated_at (import-bundle drops those three), then a {\"totals\":{…}} trailer. Streams, so memory stays flat at any row count. Defaults to stdout as a single JSON document.")
+        .option("--page-size <n>", "Rows per cursor-paginated request. Defaults to 500; hard cap is 1000.")
+        .option("--json", "Print a JSON envelope (omit row payload — use --output to keep the rows).")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables export-bundle", options, () => exportTableBundle(table, options));
+    }))
+        .addCommand(new Command("import-bundle")
+        .description("Recreate a workspace table from an export-bundle file in this org. Effect: creates one new table in this workspace and inserts every bundled row — 0 credits, no provider calls, nothing runs. Reads both bundle formats and streams a line-delimited bundle row by row, so a multi-GB file imports without loading into memory. Restores columns (incl. enrichment/tool definitions). Pass --key to make the import idempotent (re-runnable), and --into to resume a failed import into the table it already created.")
+        .requiredOption("--file <path>", "Bundle JSON file produced by `tables export-bundle`.")
+        .option("--name <name>", "Override the table display name. Defaults to the bundle's table name. Ignored with --into.")
+        .option("--project <project>", "Project id or slug for the new table. Defaults to General. Ignored with --into.")
+        .option("--into <table>", "Resume into an existing table (id or slug) instead of creating a new one. Requires --key. Use the table id printed by the failed run.")
+        .option("--key <column>", "Upsert key column. When set, rows are matched by this key instead of blindly inserted, so re-running the import is idempotent (no duplicates). Required with --into.")
+        .option("--batch-size <n>", "Requested rows per write group. Defaults to 500; values up to 5000 are accepted and split into safe writes of at most 500 rows.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("tables import-bundle", options, () => importTableBundle(options, binaryName));
+    }))
+        .addCommand(addContractFlags(new Command("list").description("List workspace tables in the current tenant database."), TABLE_LIST_QUERY_CONTRACT, {
+        project: { help: "Project id or slug to filter by." },
+        tag: { help: "Only tables carrying this workspace tag (see `oxygen tags list`)." },
+        include_archived: {
+            help: "Also list archived, delete-scheduled and purging tables (the trash; each carries a lifecycle with purge_scheduled_at, and one with purgeStartedAt is being purged and can no longer be restored).",
+        },
+        limit: { help: "Maximum tables to list. Defaults to 200; hard cap is 1000.", valueName: "<n>" },
+    })
+        .option("--all", "List every table instead of the newest window.")
+        .option("--json", "Print a JSON envelope.")
+        .addHelpText("after", "\nLists the 200 newest tables by default. Follow nextCursor with --cursor and the same filters, or pass --all. --query searches names across every table; --projection summary keeps results compact. rowCount is null when not reconciled; measure unknown counts with `tables describe <table> --stats`.\n")
+        .action(async (options) => {
+        await handleAsyncAction("tables list", options, async () => {
+            const params = tableListQueryParams(readContractFlags(options, TABLE_LIST_QUERY_CONTRACT));
+            if (options.all)
+                params.set("all", "true");
+            const qs = params.toString() ? `?${params.toString()}` : "";
+            const data = await requestOxygen(`/api/cli/tables${qs}`);
+            // A capped list is where a blind agent filtered 200 rows locally to find
+            // one table by name (acceptance run, 2026-09-18); name the native lookup.
+            if (!options.json)
+                writeListCapNotice(data, "table(s)", "continue with --cursor <nextCursor>, or find a name with --query <text>");
+            return data;
+        });
+    }))
+        .addCommand(addContractFlags(new Command("query"), TABLE_QUERY_GRID_CONTRACT, {
+        format: { valueName: "<format>", help: "Grid cell previews/state: default 50, cap 200, optional stats/fill/window. Omit for raw filters, fields, search, sorts or offsets. JSON cells are null; their digests live in __oxygen_grid_cell_previews. Use tables rows inspect --projection value for complete values." },
+        max_chars: { help: "Maximum compact JSON envelope characters for raw or grid reads (1,000-100,000). Raw defaults to 12,000." },
+    })
+        .description("Read raw Table rows or --format grid cell previews/state with grid.nextCursor, in a JSON envelope. Use tables preview --summary-only for fill rates; tables export <table> --format table renders raw rows. Grid supports stats/fill/window options and refuses raw selectors.")
+        .argument("<table>", "Table id or slug.")
+        .option("--limit <n>", "Raw: default 20, native cap 2000; --full restores default 100. Grid: default 50, cap 200.")
+        .option("--cursor <cursor>", "Pagination cursor returned by a previous query. Walks forward one page at a time; mutually exclusive with --offset.")
+        .option("--offset <n>", "Skip this many rows and start there — jump straight to a row without paging to it. Mutually exclusive with --cursor.")
+        .option("--fields <columns>", "Comma-separated column keys or ids to include.")
+        .option("--filter-json <json>", "Legacy filter object or array, e.g. '{\"column\":\"mobile_phone_e164\",\"op\":\"is_null\"}'. Mutually exclusive with --filter-tree-json/--sort-json.")
+        .option("--filter-tree-json <json>", `Airtable-style filter group, e.g. '{\"type\":\"group\",\"conjunction\":\"and\",\"children\":[{\"type\":\"leaf\",\"columnKey\":\"stage\",\"operator\":\"is\",\"value\":\"won\"}]}'. Add \"path\":\"a.b\" to a leaf to match a key inside a JSON cell, e.g. the rows one Function run touched: {\"columnKey\":\"<function_column>\",\"path\":\"action_run_id\",\"operator\":\"is\",\"value\":\"<run_id>\"}. Leaf operators: ${FILTER_TREE_OPERATORS.join(", ")} (is_true/is_false need a checkbox column; --filter-json's is_null/is_not_null are is_empty/is_not_empty here). Mutually exclusive with --filter-json.`)
+        .option("--search <text>", "Find rows by one piece of text, matched against every text, number, date and checkbox column at once — the grid's magnifier. Combines with --filter-tree-json (both must hold). Use --filter-tree-json when you know which column to match.")
+        .option("--formula-values <mode>", "Formula filters are refused by default because displayed formulas are evaluated live. Refresh the formula's stored cells with `columns run <table> <column> --force` (0 credits), then pass 'materialized'; filtering uses that stored snapshot and returns a freshness note. A fill-empty field a bundle adds (definition fill: \"empty\", such as Headcount or Job title) is stored, not live: its cell is the value, so 'materialized' filters it exactly.")
+        .option("--sort-json <json>", "Ordered sort rules, e.g. '[{\"columnKey\":\"_created_at\",\"direction\":\"desc\"}]'. Earlier rules dominate. Mutually exclusive with --filter-json.")
+        .option("--no-system-fields", "Omit _row_id, _created_at, and _updated_at from returned rows (included by default).")
+        .option("--full", "Read legacy full rows without the default character limit.")
+        .option("--output <path>", "Write full JSON for this page to a new local file; print a small receipt.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables query", options, async () => {
+            const gridArgs = readContractFlags(options, TABLE_QUERY_GRID_CONTRACT);
+            if (gridArgs.format !== "grid" && Object.keys(gridArgs).some((key) => key !== "max_chars")) {
+                throw new OxygenError("invalid_request", "Grid options require --format grid.", { exitCode: 1 });
+            }
+            const full = options.full || Boolean(options.output);
+            if (full && options.format === "grid")
+                throw new OxygenError("invalid_request", "--full/--output require raw rows; omit --format grid.", { exitCode: 2 });
+            const limit = readPositiveInt(options.limit) ?? (options.format !== "grid" && !full ? TABLE_QUERY_CLI_DEFAULT_LIMIT : undefined);
+            if (options.format !== "grid" && !full && gridArgs.max_chars === undefined)
+                gridArgs.max_chars = TABLE_QUERY_CLI_DEFAULT_MAX_CHARS;
+            const filters = readFilterJsonOption(options.filterJson);
+            const filterTree = readJsonObjectOption(options.filterTreeJson);
+            const formulaValues = readFormulaValuesOption(options.formulaValues);
+            const sorts = readSortJsonOption(options.sortJson);
+            const offset = readNonNegativeInt(options.offset);
+            if (filters && (filterTree || sorts)) {
+                throw new OxygenError("invalid_filter", "Pass either --filter-json (legacy) or --filter-tree-json/--sort-json, not both.", { exitCode: 1 });
+            }
+            if (formulaValues && !filters && !filterTree) {
+                throw new OxygenError("invalid_filter", "--formula-values requires --filter-json or --filter-tree-json.", { exitCode: 1 });
+            }
+            if (readOption(options.cursor) && offset !== undefined) {
+                throw new OxygenError("invalid_request", "Pass either --cursor or --offset, not both.", { exitCode: 1 });
+            }
+            if (options.format === "grid" && (readCsvOption(options.fields).length > 0 || filters?.length || filterTree ||
+                readOption(options.search) || formulaValues || sorts?.length || (offset !== undefined && offset > 0))) {
+                throw new OxygenError("invalid_request", '--format grid takes only table, --limit, --cursor and optional --include-stats/--include-fill; omit --format for filters, fields, search, sorts or offsets.', { exitCode: 1 });
+            }
+            const data = await requestOxygen("/api/cli/tables/query", {
+                method: "POST",
+                body: {
+                    table,
+                    ...gridArgs,
+                    ...(limit ? { limit } : {}),
+                    ...(readOption(options.cursor) ? { cursor: readOption(options.cursor) } : {}),
+                    ...(offset !== undefined ? { offset } : {}),
+                    ...(readOption(options.fields) ? { fields: readCsvOption(options.fields) } : {}),
+                    ...(filters ? { filters } : {}),
+                    ...(filterTree ? { filterTree } : {}),
+                    ...(readOption(options.search) ? { search: readOption(options.search) } : {}),
+                    ...(formulaValues ? { formula_values: formulaValues } : {}),
+                    ...(sorts ? { sorts } : {}),
+                    ...(options.systemFields === false ? { include_system_fields: false } : {}),
+                },
+            });
+            // Enforce the window even against an older compatible serving API.
+            if (options.format !== "grid" && !tableQueryRawResultFits(data, typeof gridArgs.max_chars === "number" ? gridArgs.max_chars : undefined)) {
+                const firstRow = Array.isArray(data.rows) ? data.rows[0] : undefined;
+                throw new OxygenError("table_query_result_too_large", "Table rows exceed the requested result window.", {
+                    details: { max_chars: gridArgs.max_chars, ...tableQueryRawRecovery(table, typeof firstRow?._row_id === "string" ? firstRow._row_id : undefined) }, exitCode: 2,
+                });
+            }
+            if (!options.output)
+                return data;
+            const output = await writeExclusiveJson(options.output, success("tables query", data), process.argv.includes("--pretty"));
+            return { output, returned_count: data.returned_count ?? data.returnedCount, total_count: data.total_count ?? data.totalCount, hasMore: data.hasMore, nextCursor: data.nextCursor, web_url: data.web_url };
+        });
+    }))
+        .addCommand(new Command("preview")
+        .description("Preview a workspace table with projected rows and summary stats.")
+        .argument("<table>", "Table id or slug.")
+        .option("--limit <n>", "Maximum preview rows to return. Defaults to 25; hard cap is 1000.")
+        .option("--fields <columns>", "Comma-separated column keys or ids to include.")
+        .option("--include-system-fields", "Include _row_id, _created_at, and _updated_at in preview rows.")
+        .option("--include-cell-states", "Include per-cell run state in the preview response.")
+        .option("--summary-only", "Return per-column fill stats plus table metadata, without row JSON. Stats cover the whole table independent of --limit: exact up to 20,000 rows, then a 2,000-row sample labelled summary.statsSampled; rowCount stays exact. Higher fidelity than `tables describe --stats`, which samples at 100. fillRate counts non-null cells, nonEmptyRate also excludes blank strings. 0 credits.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables preview", options, () => {
+            const limit = readPositiveInt(options.limit);
+            return requestOxygen("/api/cli/tables/preview", {
+                method: "POST",
+                body: {
+                    table,
+                    ...(limit ? { limit } : {}),
+                    ...(readOption(options.fields) ? { fields: readCsvOption(options.fields) } : {}),
+                    ...(options.includeSystemFields ? { include_system_fields: true } : {}),
+                    ...(options.includeCellStates ? { include_cell_states: true } : {}),
+                    ...(options.summaryOnly ? { summary_only: true } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("describe")
+        .alias("get")
+        .description("Describe a workspace table and its columns. Add --stats for row count and per-column fill rates (0 credits). Next: `tools search --for-table <table>` lists what these columns can be enriched with and what each costs per row (0 credits).")
+        .argument("<table>", "Table id or slug.")
+        .option("--include-archived", "Include archived columns, and read a table that is archived, scheduled for deletion or being purged.")
+        .option("--stats", "Include stats.rowCount (also summary.rowCount) and per-column fill rates. Row count is exact; above 100 rows fill rates use a 100-row sample (stats.statsSampled). For whole-table fill rates on a bigger list use `tables preview <table> --summary-only` \u2014 exact up to 20,000 rows, 2,000-row sample above. 0 credits.")
+        .option("--column <key>", "Describe just this one column (its kind, definition and whether auto-run includes it) instead of every column.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables describe", options, () => requestOxygen("/api/cli/tables/describe", {
+            method: "POST",
+            body: {
+                table,
+                ...(options.includeArchived ? { include_archived: true } : {}),
+                ...(options.stats ? { include_stats: true } : {}),
+                ...(readOption(options.column) ? { column: readOption(options.column) } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("tidy-suggest")
+        .description("Read-only tidy analysis for a workspace table: duplicate columns, formatting issues, hide candidates, and value-sanity findings.")
+        .argument("<table>", "Table id or slug.")
+        .option("--limit <n>", "Maximum rows to sample for the analysis. Defaults to and is capped at 5000.")
+        .option("--categories <csv>", "Comma-separated subset of duplicates,formatting,hide,valueSanity. Defaults to all four.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleTablesTidySuggestAction(table, options);
+    }))
+        .addCommand(new Command("activity")
+        .description("Show background runs active on a workspace table right now, with a worker-queue health rollup.")
+        .argument("<table>", "Table id or slug.")
+        .option("--limit <n>", "Maximum active runs to return (1-100). Defaults to 20.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables activity", options, () => {
+            const params = new URLSearchParams({ table });
+            const limit = readPositiveInt(options.limit);
+            if (limit)
+                params.set("limit", String(limit));
+            return requestOxygen(`/api/cli/tables/activity?${params.toString()}`);
+        });
+    }))
+        .addCommand(new Command("rename")
+        .description("Rename a workspace table display name and slug.")
+        .argument("<table>", "Table id or slug.")
+        .requiredOption("--name <name>", "New table display name.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables rename", options, () => requestOxygen("/api/cli/tables/rename", {
+            method: "POST",
+            body: { table, name: options.name },
+        }));
+    }))
+        .addCommand(new Command("tag")
+        .description("Replace a table's workspace tags (Tags primitive; \"\" clears). Tags link the table to sequences, wiki pages, and workflows carrying the same tag — browse with `oxygen tags get <tag>`.")
+        .argument("<table>", "Table id or slug.")
+        .requiredOption("--tags <csv>", "Comma-separated tags; \"\" clears them.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables tag", options, () => requestOxygen("/api/cli/tables/tags", {
+            method: "POST",
+            body: { table, tags: readCsvOption(options.tags) },
+        }));
+    }))
+        .addCommand(new Command("archive")
+        .description("Archive a workspace table without dropping physical data. Hides it indefinitely with no purge timer; for cleanup with a restorable deadline use `tables delete`.")
+        .argument("<table>", "Table id or slug.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables archive", options, () => requestOxygen(`/api/cli/tables/${encodeURIComponent(table)}`, {
+            method: "DELETE",
+        }));
+    }))
+        .addCommand(new Command("delete")
+        .description("Delete workspace tables: archives now and schedules the physical purge (default 14 days; restorable via `tables restore` until then). --now purges immediately and permanently — it previews and refuses without --yes. A table with a large history answers `purging` and finishes in the background. Free — 0 Oxygen credits.")
+        .argument("<tables...>", "Table ids or slugs.")
+        .option("--now", "Purge immediately instead of scheduling. Irreversible; single table only. A large table finishes in the background.")
+        .option("--yes", "Approve the immediate purge previewed by --now.")
+        .option("--purge-after <days>", "Days until the scheduled purge runs. Defaults to 14; 0 purges on the next background sweep (sweeps visit each workspace every few minutes).")
+        .option("--reason <text>", "Recorded with the delete for the audit trail.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (tables, options) => {
+        await handleAsyncAction("tables delete", options, () => {
+            const purgeAfter = readOption(options.purgeAfter) ?? undefined;
+            const purgeAfterDays = purgeAfter === undefined ? undefined : Number.parseInt(purgeAfter, 10);
+            if (purgeAfterDays !== undefined && (!Number.isFinite(purgeAfterDays) || purgeAfterDays < 0)) {
+                throw new OxygenError("invalid_request", "--purge-after must be a non-negative number of days.", {
+                    exitCode: 2,
+                });
+            }
+            return requestOxygen("/api/cli/tables/delete", {
+                method: "POST",
+                body: {
+                    ...(tables.length === 1 ? { table: tables[0] } : { tables }),
+                    ...(options.now ? { now: true } : {}),
+                    ...(options.yes ? { approved: true } : {}),
+                    ...(purgeAfterDays !== undefined ? { purge_after_days: purgeAfterDays } : {}),
+                    ...(readOption(options.reason) ? { reason: readOption(options.reason) } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("restore")
+        .description("Restore an archived or delete-scheduled table: cancels the purge timer and reclaims its slug. A table whose purge has begun (lifecycle.purgeStartedAt) can no longer be restored.")
+        .argument("[table]", "Table id or slug (the pre-delete slug works).")
+        .option("--tables <refs>", "Restore a comma-separated batch; alternative to the table argument.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables restore", options, () => {
+            const refs = splitCommaList(options.tables);
+            if ((!table && refs.length === 0) || (table && refs.length > 0))
+                throw new OxygenError("invalid_selection", "Pass one table argument or --tables, not both.", { exitCode: 2 });
+            return requestOxygen("/api/cli/tables/restore", {
+                method: "POST",
+                body: { ...(options.tables !== undefined ? { tables: splitCommaList(options.tables) } : { table }) },
+            });
+        });
+    }))
+        .addCommand(new Command("move")
+        .description("Move one or more workspace tables into a project (folder) in one call. Rows, columns, runs, and provenance are preserved. Free; reverse it by moving the table back.")
+        .argument("<tables...>", "Table ids or slugs; several move together, each reported separately.")
+        .requiredOption("--project <project>", "Destination project id or slug (see `oxygen projects list`).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (tables, options) => {
+        await handleAsyncAction("tables move", options, () => requestOxygen("/api/cli/tables/move", {
+            method: "POST",
+            body: {
+                ...(tables.length === 1 ? { table: tables[0] } : { tables }),
+                project: options.project,
+            },
+        }));
+    }))
+        .addCommand(new Command("recover-pending")
+        .description("Recover existing BetterContact email or phone requests and inspect terminal verification blockers; no new orders.")
+        .argument("<table>", "Table id or slug.")
+        .option("--max-items <n>", "Max pending cache rows to poll in this run. Defaults to 1000.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables recover-pending", options, () => {
+            const maxItems = options.maxItems ? Number.parseInt(options.maxItems, 10) : undefined;
+            return requestOxygen("/api/cli/tables/recover-pending", {
+                method: "POST",
+                body: {
+                    table,
+                    ...(Number.isFinite(maxItems) ? { max_items: maxItems } : {}),
+                },
+            });
+        });
+    }));
+    const watcherCommand = tablesCommand.command("watcher")
+        .description("Professional Network Post Engagers: one editable table of daily engagers, source attribution, and current employers from posts in the past 7 days. Start with preview (free); create/resume activate paid daily monitoring after exact approval.");
+    watcherCommand.command("get")
+        .description("Read a table's Professional Network Post Engagers configuration and status. Free.")
+        .argument("<table>", "Watcher table id or slug.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables watcher get", options, () => requestOxygen(`/api/cli/tables/linkedin-profile-watcher?table=${encodeURIComponent(table)}`, { method: "GET" }));
+    });
+    for (const action of ["preview", "create", "update", "pause", "resume"]) {
+        const command = watcherCommand.command(action)
+            .description({
+            preview: "Free configuration and credit preview: no provider calls, writes, or scheduling. Omit --max-credits for a recommendation and preview hash. Ask for real profile URLs; never invent them.",
+            create: "Create and activate a Professional Network Post Engagers table after approval of its exact preview. Starts collection now and daily at 07:00 UTC under the approved per-cycle cap.",
+            update: "Edit watched profiles or the per-cycle cap from the table. Preview the changes first; approval binds the exact new configuration.",
+            pause: "Pause daily monitoring while retaining the table and collected rows.",
+            resume: "Resume paid daily monitoring after reviewing a fresh preview and approving its per-cycle credit cap.",
+        }[action])
+            .option("--table <table>", "Existing watcher table id or slug; required for get/update/pause/resume.")
+            .option("--json", "Print a JSON envelope.");
+        if (action !== "pause") {
+            command
+                .option("--name <name>", "Watcher table display name.")
+                .option("--project <project>", "Project id or slug; defaults to General.")
+                .option("--profiles-json <json>", "JSON array of 1–10 real public LinkedIn profile URLs; replaces the watched list.")
+                .option("--max-credits <credits>", "Hard credit ceiling for each daily cycle; never a monthly ceiling.")
+                .option("--credential-mode <mode>", "managed (default): Oxygen credits per cycle. user_api_key: every LinkedIn call runs on your own Up2Data key saved in Connections, billed by Up2Data, no Oxygen credits.");
+            if (action !== "preview")
+                command
+                    .option("--preview-hash <hash>", "Exact configuration hash returned by preview; re-preview after any change.")
+                    .option("--approved", "Approve this exact configuration and recurring per-cycle spending.");
+        }
+        if (action === "create") {
+            command.requiredOption("--request-id <uuid>", "One stable UUID for this new watcher. Reuse it and the identical configuration after a timeout; never generate a new retry key.");
+        }
+        command.action(async (options) => {
+            await handleAsyncAction(`tables watcher ${action}`, options, () => {
+                const profiles = options.profilesJson === undefined ? undefined : parseJsonArray(options.profilesJson);
+                if (profiles !== undefined && profiles.some((profile) => typeof profile !== "string")) {
+                    throw new OxygenError("invalid_input", "--profiles-json must be an array of LinkedIn profile URL strings.");
+                }
+                return requestOxygen("/api/cli/tables/linkedin-profile-watcher", {
+                    method: "POST",
+                    body: {
+                        action,
+                        ...(readOption(options.table) ? { table: readOption(options.table) } : {}),
+                        ...(readOption(options.name) ? { name: readOption(options.name) } : {}),
+                        ...(readOption(options.project) ? { project: readOption(options.project) } : {}),
+                        ...(profiles !== undefined ? { profiles } : {}),
+                        ...(options.maxCredits !== undefined ? { max_credits_per_cycle: readPositiveNumber(options.maxCredits) } : {}),
+                        ...(readOption(options.requestId) ? { request_id: readOption(options.requestId) } : {}),
+                        ...(readOption(options.previewHash) ? { preview_hash: readOption(options.previewHash) } : {}),
+                        ...(options.approved ? { approved: true } : {}),
+                        ...(readOption(options.credentialMode) ? { credential_mode: readOption(options.credentialMode) } : {}),
+                    },
+                });
+            });
+        });
+    }
+    const followersCommand = tablesCommand.command("followers")
+        .description("Order a LinkedIn company page's followers as a table of leads — a competitor's audience. `check` is free and quotes the order; fee-positive own-key previews leave the follower count unknown. `order` places it. The order is fulfilled by ScrapeLi, so the table is created immediately and its rows land later; there is no published delivery time.");
+    followersCommand.command("check")
+        .description("Free order preview. Managed quotes the follower cost; your own key quotes placement and later check fees, with a total ceiling you choose. No spend or table; `orderable: false` means the order is unavailable.")
+        .requiredOption("--company <url>", "LinkedIn company page URL, e.g. https://www.linkedin.com/company/hubspot.")
+        .option("--records <n>", "How many followers to price. Minimum 100; defaults to 1000.")
+        .option("--package <package>", "Basic (default): profile, job title, location, employer. Advanced (10x the credits): also a verified work email and region.")
+        .option("--credential-mode <mode>", "managed (default): Oxygen credits. user_api_key: your saved ScrapeLi key, billed by ScrapeLi, plus Oxygen placement/recovery platform fees.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("tables followers check", options, () => requestOxygen("/api/cli/tables/linkedin-company-followers", {
+            method: "POST",
+            body: {
+                action: "preview",
+                company_url: readOption(options.company),
+                ...(options.records !== undefined ? { records: readPositiveNumber(options.records) } : {}),
+                ...(readOption(options.package) ? { package: readOption(options.package) } : {}),
+                ...(readOption(options.credentialMode) ? { credential_mode: readOption(options.credentialMode) } : {}),
+            },
+        }));
+    });
+    followersCommand.command("order")
+        .description("Place the follower order after checking it. Requires --approved and --max-credits: managed uses the quoted order cost; own-key uses a TOTAL placement/recovery platform-fee ceiling. A ceiling equal to placement cannot recover rows. Budget exhaustion lands no partial rows; refetched pages consume the same ceiling. Creates the Table now; rows arrive later.")
+        .requiredOption("--approved", "Approve this purchase. Required, as on every command that buys data.")
+        .requiredOption("--company <url>", "LinkedIn company page URL whose followers to order.")
+        .option("--max-credits <credits>", "Approved order ceiling. On your key, TOTAL platform fees for placement and later checks; exhaustion stops recovery. At least the quoted placement fee. ScrapeLi charges separately.")
+        .requiredOption("--request-id <uuid>", "One stable UUID and identical order payload for retries. A new ID can buy the audience again.")
+        .option("--records <n>", "How many followers to buy. Minimum 100; defaults to 1000.")
+        .option("--package <package>", "Basic (default) or Advanced (10x the credits; adds a verified work email and region).")
+        .option("--name <name>", "Table name. Defaults to \"<Company> Followers\".")
+        .option("--project <project>", "Project id or slug; defaults to General.")
+        .option("--credential-mode <mode>", "managed (default): Oxygen credits. user_api_key: your saved ScrapeLi key, billed by ScrapeLi, plus Oxygen placement/recovery platform fees.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("tables followers order", options, () => requestOxygen("/api/cli/tables/linkedin-company-followers", {
+            method: "POST",
+            body: {
+                action: "create",
+                approved: true,
+                company_url: readOption(options.company),
+                ...(options.records !== undefined ? { records: readPositiveNumber(options.records) } : {}),
+                ...(readOption(options.package) ? { package: readOption(options.package) } : {}),
+                ...(readOption(options.name) ? { name: readOption(options.name) } : {}),
+                ...(readOption(options.project) ? { project: readOption(options.project) } : {}),
+                ...(options.maxCredits !== undefined ? { max_credits: readPositiveNumber(options.maxCredits) } : {}),
+                ...(readOption(options.requestId) ? { request_id: readOption(options.requestId) } : {}),
+                ...(readOption(options.credentialMode) ? { credential_mode: readOption(options.credentialMode) } : {}),
+            },
+        }));
+    });
+    followersCommand.command("status")
+        .description("Read a fee-budgeted own-key follower order's total fee ceiling, allocated attempts, recorded fees and recovery outcome by its original request ID, including interrupted setup. Optional --table-id verifies the saved Table binding. Recorded fees may settle later. Makes no provider call.")
+        .requiredOption("--request-id <uuid>", "Original order request ID.")
+        .option("--table-id <id>", "Optional saved Table ID; verifies the order belongs to that Table.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("tables followers status", options, () => {
+            const requestId = readOption(options.requestId);
+            if (!requestId)
+                throw new OxygenError("invalid_input", "--request-id must be the original nonblank order request ID.", { exitCode: 2 });
+            const query = new URLSearchParams({ request_id: requestId });
+            const tableId = readOption(options.tableId);
+            if (tableId)
+                query.set("table_id", tableId);
+            return requestOxygen(`/api/cli/tables/linkedin-company-followers?${query}`, { method: "GET" });
+        });
+    });
+    tablesCommand.addCommand(new Command("relate")
+        .description("Link two tables (the web's \"Link to another table\"): creates an empty linked-record column on BOTH tables, so links show and can be removed from either side; matching values are not required. `oxygen tables relate contacts --to accounts --live` names them from the tables (account on contacts, contacts on accounts) and re-running it finds the same link. Then use `oxygen tables link` to populate row-to-row edges. Works on any workspace table; plain tables stay plain and are never registered as CRM objects. Defaults to dry-run.")
+        .argument("<table>", "Source table id or slug.")
+        .argument("[slug]", "Relation slug — also the relation column key on the source, such as client. Omit it to name the relation from the target table (or reuse the one relation that already links them).")
+        .option("--to <table>", "Table to link to: id or slug. May also be a CRM object table (companies, people, deals).")
+        .option("--target-table <table>", "Same as --to.")
+        .option("--display-name <name>", "Display name for the relation column. Defaults to the target table's name, or the slug in Title Case when you name the slug.")
+        .option("--cardinality <cardinality>", "one_to_one, one_to_many, many_to_one, or many_to_many (source:target). Default many_to_many. one_to_many means each source row links many target rows and each target row links back to one source.")
+        .option("--inverse-slug <slug>", "Key of the linked-record column on the target table. Defaults to a name from the source table; a standard CRM object target (companies, people, deals) gets no column there.")
+        .option("--inverse-display-name <name>", "Display name for the inverse side.")
+        .option("--dry-run", "Preview the relation plan without writing.")
+        .option("--live", "Apply the relation. Default is dry-run.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, slug, options) => {
+        await handleAsyncAction("tables relate", options, () => {
+            const to = readOption(options.to);
+            const targetTable = readOption(options.targetTable);
+            if (to && targetTable && to !== targetTable) {
+                throw new OxygenError("invalid_request", "--to and --target-table name different tables; pass one.", { exitCode: 1 });
+            }
+            if (!to && !targetTable) {
+                throw new OxygenError("invalid_request", "Name the table to link to with --to <table>.", { exitCode: 1 });
+            }
+            return requestOxygen("/api/cli/tables/relations", {
+                method: "POST",
+                body: {
+                    table,
+                    relationship: {
+                        ...(readOption(slug) ? { slug: readOption(slug) } : {}),
+                        target_table: to ?? targetTable,
+                        ...(options.displayName ? { display_name: options.displayName } : {}),
+                        ...(options.cardinality ? { cardinality: options.cardinality } : {}),
+                        ...(options.inverseSlug ? { inverse_slug: options.inverseSlug } : {}),
+                        ...(options.inverseDisplayName ? { inverse_display_name: options.inverseDisplayName } : {}),
+                    },
+                    mode: options.live ? "live" : "dry_run",
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("relations")
+        .description("Inspect and manage native Tables-owned relation definitions.")
+        .addCommand(new Command("list")
+        .description("List the native relations visible from one table, including cardinality, target, and active link count.")
+        .argument("<table>", "Table id or slug.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables relations list", options, () => {
+            const params = new URLSearchParams({ table });
+            return requestOxygen(`/api/cli/tables/relations?${params.toString()}`);
+        });
+    }))
+        .addCommand(new Command("update")
+        .description("Rename either side of a relation or change its cardinality. Endpoints and slugs stay immutable. Previews by default.")
+        .argument("<table>", "Table id or slug.")
+        .argument("<relation>", "Relation slug as seen from this table.")
+        .option("--display-name <name>", "New display name on this table.")
+        .option("--inverse-display-name <name>", "New display name on the other table.")
+        .option("--cardinality <cardinality>", "one_to_one, one_to_many, many_to_one, or many_to_many from this table's perspective.")
+        .option("--approved", "Apply after inspecting the preview.")
+        .option("--dry-run", "Preview without writing. This is the default.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, relation, options) => {
+        await handleAsyncAction("tables relations update", options, () => requestOxygen("/api/cli/tables/relations", {
+            method: "PATCH",
+            body: {
+                table,
+                relation,
+                ...(readOption(options.displayName) ? { display_name: readOption(options.displayName) } : {}),
+                ...(readOption(options.inverseDisplayName)
+                    ? { inverse_display_name: readOption(options.inverseDisplayName) }
+                    : {}),
+                ...(readOption(options.cardinality) ? { cardinality: readOption(options.cardinality) } : {}),
+                mode: options.approved && !options.dryRun ? "live" : "dry_run",
+            },
+        }));
+    }))
+        .addCommand(new Command("archive")
+        .description("Archive a native relation, its active links, and both relation columns while preserving history. Previews by default.")
+        .argument("<table>", "Table id or slug.")
+        .argument("<relation>", "Relation slug as seen from this table.")
+        .option("--approved", "Apply after inspecting the preview.")
+        .option("--dry-run", "Preview without writing. This is the default.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, relation, options) => {
+        await handleAsyncAction("tables relations archive", options, () => requestOxygen("/api/cli/tables/relations", {
+            method: "DELETE",
+            body: {
+                table,
+                relation,
+                mode: options.approved && !options.dryRun ? "live" : "dry_run",
+            },
+        }));
+    })))
+        .addCommand(new Command("unlink")
+        .description("Unlink one exact pair of rows by archiving their relation edge. The relation definition and both rows remain. Previews by default.")
+        .argument("<table>", "Source table id or slug.")
+        .argument("<row_id>", "Source row id.")
+        .requiredOption("--relation <slug>", "Relation slug as seen from the source table.")
+        .requiredOption("--target-row-id <row_id>", "Linked row id to remove.")
+        .option("--approved", "Apply after inspecting the preview.")
+        .option("--live", "Alias for --approved.")
+        .option("--dry-run", "Preview without writing. This is the default.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, rowId, options) => {
+        await handleAsyncAction("tables unlink", options, () => requestOxygen("/api/cli/tables/relations/unlink", {
+            method: "POST",
+            body: {
+                table,
+                row_id: rowId,
+                relation: options.relation,
+                target_row_id: options.targetRowId,
+                mode: (options.approved || options.live) && !options.dryRun ? "live" : "dry_run",
+            },
+        }));
+    }))
+        .addCommand(new Command("link")
+        .description("Link two tables: Oxygen finds the column that joins them, works out the direction, shows you how many rows will match, and on approval links every row. Free. Previews by default; --approved queues a background run and records each row's outcome in a system link_status_<relation> column. Wait for that run with `oxygen table-runs wait <run_id>`. (Also links one row to one row — see --relation.)")
+        .argument("<table>", "Table id or slug to link FROM.")
+        .argument("[row_id]", "Row form only: the source row id to link. Omit for the whole-table form.")
+        .option("--to <table>", "Table id or slug to link TO. May be a CRM object table (companies, people, deals).")
+        .option("--on <column>", "Pin one table's column by name or key. Oxygen must still find a compatible column on the other table: generic text needs a strongly similar label, while domains, emails, LinkedIn URLs, and external IDs pair by semantic role.")
+        .option("--approved", "Queue the bulk link after inspecting the preview; then wait with `oxygen table-runs wait <run_id>`.")
+        .option("--create-missing", "Also create target rows for unmatched source keys (CRM records when filling an existing CRM relationship). Free.")
+        .option("--max-concurrency <n>", "Maximum concurrent row items for the run (1-1000; a ceiling shared with worker and provider capacity). Defaults to 250; native --create-missing runs serialize target-row creation safely.")
+        .option("--undo <run_id>", "Undo a previous link run, archiving only the links that run created.")
+        .option("--relation <slug>", "Row form: relation slug defined on the source table, such as client.")
+        .option("--target-row-id <row_id>", "Row form: target row id in the related table.")
+        .option("--dry-run", "Preview without writing. This is the default.")
+        .option("--live", "Row form: apply the single-row link.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, rowId, options) => {
+        const wholeTableForm = Boolean(readOption(options.to) || readOption(options.undo));
+        const rowForm = Boolean(rowId || readOption(options.relation) || readOption(options.targetRowId));
+        // Usage errors go through emitCliFailure like every other command, NOT a
+        // bare throw: a raw throw escapes commander's action handler as an
+        // uncaught exception, which prints a Node stack trace to stderr instead
+        // of the `{ok:false,error}` envelope every other command emits, and lets
+        // Node's generic exit code override the error's own. This is the first
+        // thing a user sees when they half-remember the command, so it has to be
+        // the standard shape.
+        const usageError = (message) => new OxygenError("invalid_request", message, { exitCode: 1 });
+        // Neither shape is complete: print BOTH rather than guessing which the
+        // user meant. A bare `oxygen tables link people` is far more likely a
+        // half-remembered whole-table command than a malformed row link.
+        if (!wholeTableForm && !rowForm) {
+            emitCliFailure("tables link", usageError([
+                "Say which table to link to, or which two rows to link.",
+                "",
+                `  Link two tables:  oxygen tables link ${table} --to <table>`,
+                `  Link two rows:    oxygen tables link ${table} <row_id> --relation <slug> --target-row-id <id>`,
+            ].join("\n")));
+            return;
+        }
+        if (wholeTableForm && rowForm) {
+            emitCliFailure("tables link", usageError("Use either the whole-table form (--to) or the row form (<row_id> --relation --target-row-id), not both."));
+            return;
+        }
+        if (rowForm) {
+            if (!rowId || !readOption(options.relation) || !readOption(options.targetRowId)) {
+                emitCliFailure("tables link", usageError(`Linking two rows needs all three: oxygen tables link ${table} <row_id> --relation <slug> --target-row-id <id>`));
+                return;
+            }
+            await handleAsyncAction("tables link", options, () => requestOxygen("/api/cli/tables/relations/link", {
+                method: "POST",
+                body: {
+                    table,
+                    row_id: rowId,
+                    relation: options.relation,
+                    target_row_id: options.targetRowId,
+                    // --approved is accepted as an alias for --live so one verb does
+                    // not teach two different confirm words.
+                    mode: options.live || options.approved ? "live" : "dry_run",
+                },
+            }));
+            return;
+        }
+        const maxConcurrency = readPositiveInt(options.maxConcurrency);
+        const undoRunId = readOption(options.undo);
+        const approved = Boolean(options.approved) && !options.dryRun;
+        const result = await requestOxygen("/api/cli/tables/link", {
+            method: "POST",
+            body: {
+                table,
+                ...(undoRunId ? { undo_run_id: undoRunId } : { to: readOption(options.to) }),
+                ...(readOption(options.on) ? { on: readOption(options.on) } : {}),
+                ...(approved ? { approved: true } : { dry_run: true }),
+                ...(options.createMissing ? { create_missing: true } : {}),
+                ...(maxConcurrency ? { max_concurrency: maxConcurrency } : {}),
+            },
+        }).catch((error) => {
+            emitCliFailure("tables link", error);
+            return null;
+        });
+        if (!result)
+            return;
+        if (options.json) {
+            emitSuccess("tables link", result, options);
+            return;
+        }
+        writeTableLinkPreview(table, result, options);
+    }))
+        .addCommand(new Command("promote")
+        .description("Write bound rows' columns onto their matched CRM records (Records<->Tables). Free, but a truth write: previews by default, then re-run with --approved to write. Approved runs queue as a background run — watch with `oxygen table-runs wait <run_id>`.")
+        .argument("<table>", "Table id or slug whose bound rows to promote.")
+        .option("--object <slug>", "CRM object to promote onto (companies, people, deals, ...). Inferred when the table has exactly one bind column.")
+        .requiredOption("--map <pairs>", "Column-to-attribute mapping as column=attribute pairs (e.g. job_title=job_title,seniority=seniority) or a JSON array/object.")
+        .option("--policy <policy>", "Conflict policy: fill-empty-only (default), overwrite, or skip-conflicts.", "fill-empty-only")
+        .option("--row-id <id...>", "Promote only these row ids. Defaults to every bound row.")
+        .option("--dry-run", "Preview per-field would_fill/would_overwrite/conflicts without writing (the default when --approved is absent).")
+        .option("--approved", "Confirm the truth write onto CRM records after inspecting the preview.")
+        .option("--max-concurrency <n>", "Maximum concurrent row items for the run (1-1000; a ceiling shared with worker and provider capacity). Defaults to 50.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        if (options.dryRun && options.approved) {
+            throw new OxygenError("invalid_promote", "Pass either --dry-run or --approved, not both.", { exitCode: 1 });
+        }
+        const mappings = parsePromoteMapOption(options.map);
+        const policy = normalizePromotePolicy(options.policy);
+        const maxConcurrency = readPositiveInt(options.maxConcurrency);
+        await handleAsyncAction("tables promote", options, () => requestOxygen("/api/cli/tables/promote", {
+            method: "POST",
+            body: {
+                table,
+                ...(readOption(options.object) ? { object: readOption(options.object) } : {}),
+                mappings,
+                policy,
+                ...(options.rowId && options.rowId.length > 0 ? { row_ids: options.rowId } : {}),
+                // Preview by default; --approved is the only path that writes.
+                ...(options.approved ? { approved: true } : { dry_run: true }),
+                ...(maxConcurrency ? { max_concurrency: maxConcurrency } : {}),
+            },
+        }));
+    }));
+    tablesCommand.addCommand(new Command("dedupe")
+        .description("Collapse duplicate rows by normalized (email/domain/linkedin) or fuzzy-label keys, or cross-check a column against another table. Previews by default; --apply --approved deletes losers (kept in row history).")
+        .argument("<table>", "Table id or slug to dedupe.")
+        .requiredOption("--on <cols>", "Key column(s): one column, or two comma-separated for a composite key (e.g. email or first_name,company).")
+        .option("--normalize <mode>", "Match mode: exact (default), email, domain, linkedin, or fuzzy-label. Fuzzy allowed only as a single key.", "exact")
+        .option("--keep <policy>", "Survivor per duplicate group: oldest (default), newest, or most-complete.", "oldest")
+        .option("--merge-values <mode>", "With --apply, fill the survivor's blank cells from the losers first: fill-empty.")
+        .option("--scan-limit <n>", "Max rows to scan. Defaults to 50000, capped at 200000.")
+        .option("--apply", "Delete the duplicate rows (losers). Without this flag the command only previews.")
+        .option("--approved", "Confirm the deletion (required with --apply); without it the API returns the preview to inspect first.")
+        .option("--against <table>", "Cross-table check: report rows whose --on value already exists in this other table (read-only).")
+        .option("--against-column <col>", "Column in the --against table to match against. Required with --against.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables dedupe", options, () => {
+            const request = buildDedupeRequest(table, options);
+            return requestOxygen(request.endpoint, { method: "POST", body: request.body });
+        });
+    }));
+    tablesCommand.addCommand(new Command("send")
+        .description("Copy rows from one table into another as a durable background run (free, resumable). Map columns with --map (or --automap), optionally flatten an array column into one row per element, and insert or upsert. --dry-run previews the resolved mapping, row estimate, and sample rows without writing.")
+        .argument("<source>", "Source table id or slug.")
+        .argument("<target>", "Target table id or slug (must be a different table).")
+        .option("--map <pairs>", "target=source column pairs, comma-separated and/or repeated (e.g. --map company=company_name,website=domain).", collectRepeatable, [])
+        .option("--mapping <json>", 'Full mapping JSON array for literals and dot-paths, e.g. [{"target":"email","source":{"type":"column","key":"$element"},"path":"email"}]. Escape hatch when --map is not enough.')
+        .option("--automap", "Match columns automatically (exact key, then case-insensitive label). The resolved mapping is echoed back.")
+        .option("--flatten <column>", 'Source column whose array value emits one target row per element (the element is mapping source key "$element"); non-array values pass through as one row.')
+        .option("--flatten-path <path>", "Dot-path to the array inside the --flatten column's value.")
+        .option("--filter <json>", 'Source-row filters JSON, e.g. [{"column":"domain","op":"is_not_null"}]. Ops: eq, neq, is_null, is_not_null, in, not_in.')
+        .option("--mode <mode>", "insert (append, default) or upsert (requires --upsert-key).", "insert")
+        .option("--upsert-key <key>", "Mapped target column that identifies existing rows for upsert.")
+        .option("--page-size <n>", "Rows copied per durable page. Defaults to 500, max 2000.")
+        .option("--dry-run", "Validate and preview only; nothing is written.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (source, target, options) => {
+        try {
+            const body = buildTablesSendRequest(source, target, options);
+            const data = await requestOxygen("/api/cli/tables/send", { method: "POST", body });
+            emitSuccess("tables send", data, options);
+            writeTablesSendHint(data);
+        }
+        catch (error) {
+            emitCliFailure("tables send", error);
+        }
+    }));
+    tablesCommand.addCommand(new Command("webhook")
+        .description("Create and manage direct table webhooks.")
+        .addCommand(new Command("list")
+        .description("List direct table webhooks.")
+        .argument("[table]", "Optional table id or slug.")
+        .option("--status <status>", "Filter by active or disabled.")
+        .option("--limit <n>", "Maximum webhooks to return. Defaults to 100.")
+        .option("--json", "Print a JSON envelope.")
+        .action((table, options) => handleAsyncAction("tables webhook list", options, () => requestOxygen(tableWebhookListPath({
+        table: table ?? options.table,
+        status: options.status,
+        limit: options.limit,
+    })))))
+        .addCommand(new Command("get")
+        .description("Get one direct table webhook by endpoint id.")
+        .argument("<endpoint_id>", "Webhook endpoint id, such as tw_...")
+        .option("--json", "Print a JSON envelope.")
+        .action((endpointId, options) => handleAsyncAction("tables webhook get", options, () => {
+        const params = new URLSearchParams({ endpoint_id: endpointId });
+        return requestOxygen(`/api/cli/tables/webhooks?${params.toString()}`);
+    })))
+        .addCommand(new Command("create")
+        .description(`Create a direct webhook endpoint that writes inbound JSON into a table (${TABLE_WEBHOOK_RATE_HELP}).`)
+        .argument("<table>", "Table id or slug.")
+        .option("--name <name>", "Display name for the webhook.")
+        .option("--mode <mode>", "insert or upsert. Defaults to upsert when --upsert-key is set, otherwise insert.")
+        .option("--auth-mode <mode>", "none or secret. Defaults to none; use secret when the sender can include an Oxygen webhook secret.")
+        .option("--upsert-key <key>", "Column key used to upsert rows. Required for upsert mode.")
+        .option("--items-path <path>", "Dot path to an array of row objects in the webhook payload.")
+        .option("--event-id-path <path>", "Dot path to the event id. Defaults to event_id, eventId, id, or payload hash.")
+        .option("--event-type-path <path>", "Dot path to the event type. Defaults to type or event.")
+        .option("--occurred-at-path <path>", "Dot path to the event timestamp.")
+        .option("--source <source>", "http (default) writes inbound JSON anyone can POST. unipile subscribes the table to your connected LinkedIn/WhatsApp accounts' events instead — no endpoint URL, no secret to share, and 0 credits: rows appear as the events reach Oxygen.")
+        .option("--account <unipile_account_id>", "unipile source only. Listen to ONE connected account. Omit to listen to every connected account in the workspace.")
+        .option("--events <csv>", "unipile source only. Comma-separated event types, e.g. relation.new,message.new. Omit for every event the receiver handles. Post reactions, post comments, profile viewers and followers are NOT pushed by the provider — capture those with a scheduled feed (`oxygen feeds bind`).")
+        .option("--mapping <mapping>", "unipile source only. curated (default) flattens known events into stable named columns; passthrough lands the raw provider event so you can map any type yourself.")
+        .option("--auto-run-columns <csv>", "Comma-separated enrichment, tool, AI, or formula columns to queue for webhook-written rows.")
+        .option("--auto-run-max-credits <n>", "Credit ceiling per webhook-triggered auto-run batch; items beyond it are skipped with credit_limit_reached. Defaults to your plan's per-delivery ceiling when omitted.")
+        .option("--auto-run-max-concurrency <n>", "Maximum concurrent row items for webhook-triggered auto-runs.")
+        .option("--auto-run-force", "Run auto-run columns even when the target cell already has a value.")
+        .option("--auto-run-connection-id <connection_id>", "Optional provider integration connection id for auto-runs.")
+        .addOption(new Option("--auto-run-approved", "Deprecated no-op. Auto-run is enabled by --auto-run-columns.").hideHelp())
+        .option("--json", "Print a JSON envelope.")
+        .action((table, options) => {
+        const autoRun = readTableWebhookAutoRunOptions(options);
+        const unipile = readOption(options.source) === "unipile";
+        return handleAsyncAction("tables webhook create", options, () => requestOxygen("/api/cli/tables/webhooks", {
+            method: "POST",
+            body: {
+                table,
+                ...(readOption(options.name) ? { name: readOption(options.name) } : {}),
+                ...(readOption(options.mode) ? { mode: readOption(options.mode) } : {}),
+                ...(readOption(options.authMode) ? { auth_mode: readOption(options.authMode) } : {}),
+                ...(readOption(options.upsertKey) ? { upsert_key: readOption(options.upsertKey) } : {}),
+                ...(readOption(options.itemsPath) ? { items_path: readOption(options.itemsPath) } : {}),
+                ...(readOption(options.eventIdPath) ? { event_id_path: readOption(options.eventIdPath) } : {}),
+                ...(readOption(options.eventTypePath) ? { event_type_path: readOption(options.eventTypePath) } : {}),
+                ...(readOption(options.occurredAtPath) ? { occurred_at_path: readOption(options.occurredAtPath) } : {}),
+                ...(unipile
+                    ? {
+                        feed_kind: "unipile",
+                        ...(readOption(options.account) ? { unipile_account_id: readOption(options.account) } : {}),
+                        ...(readOption(options.events) ? { event_types: readOption(options.events) } : {}),
+                        ...(readOption(options.mapping) ? { mapping: readOption(options.mapping) } : {}),
+                    }
+                    : {}),
+                ...(autoRun ? { auto_run: autoRun } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("update")
+        .description("Update a direct table webhook endpoint.")
+        .argument("<endpoint_id>", "Webhook endpoint id, such as tw_...")
+        .option("--name <name>", "Update the webhook display name.")
+        .option("--status <status>", "active or disabled.")
+        .option("--auth-mode <mode>", "none or secret. Setting secret rotates and returns a new webhook secret.")
+        .option("--auto-run-columns <csv>", "Comma-separated enrichment, tool, AI, or formula columns to queue for webhook-written rows.")
+        .option("--auto-run-max-credits <n>", "Credit ceiling per webhook-triggered auto-run batch; items beyond it are skipped with credit_limit_reached. Defaults to your plan's per-delivery ceiling when omitted.")
+        .option("--auto-run-max-concurrency <n>", "Maximum concurrent row items for webhook-triggered auto-runs.")
+        .option("--auto-run-force", "Run auto-run columns even when the target cell already has a value.")
+        .option("--auto-run-connection-id <connection_id>", "Optional provider integration connection id for auto-runs.")
+        .addOption(new Option("--auto-run-approved", "Deprecated no-op. Auto-run is enabled by --auto-run-columns.").hideHelp())
+        .option("--clear-auto-run", "Remove the webhook auto-run configuration.")
+        .option("--json", "Print a JSON envelope.")
+        .action((endpointId, options) => {
+        const autoRun = readTableWebhookAutoRunOptions(options);
+        if (autoRun && options.clearAutoRun) {
+            throw new OxygenError("invalid_table_webhook", "Pass either auto-run options or --clear-auto-run, not both.", {
+                exitCode: 1,
+            });
+        }
+        return handleAsyncAction("tables webhook update", options, () => requestOxygen("/api/cli/tables/webhooks", {
+            method: "PATCH",
+            body: {
+                endpoint_id: endpointId,
+                ...(readOption(options.name) ? { name: readOption(options.name) } : {}),
+                ...(readOption(options.status) ? { status: readOption(options.status) } : {}),
+                ...(readOption(options.authMode) ? { auth_mode: readOption(options.authMode) } : {}),
+                ...(autoRun ? { auto_run: autoRun } : {}),
+                ...(options.clearAutoRun ? { clear_auto_run: true } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("deliveries")
+        .description("List direct table webhook deliveries and auto-run enqueue status.")
+        .argument("[endpoint_id]", "Optional webhook endpoint id, such as tw_...")
+        .option("--table <table>", "Filter by table id or slug.")
+        .option("--status <status>", "Filter by received, completed, failed, or rejected (rejected = arrived while the feed was paused and was turned away; no rows written). A delivery refused with HTTP 429 for exceeding the plan's rate is not recorded here: the sender redelivers it.")
+        .option("--auto-run-status <status>", "Filter by not_configured, queued, skipped, or failed_to_enqueue.")
+        .option("--limit <n>", "Maximum deliveries to return. Defaults to 50.")
+        .option("--json", "Print a JSON envelope.")
+        .action((endpointId, options) => handleAsyncAction("tables webhook deliveries", options, () => requestOxygen(tableWebhookDeliveriesPath({
+        endpointId,
+        table: options.table,
+        status: options.status,
+        autoRunStatus: options.autoRunStatus,
+        limit: options.limit,
+    }))))));
+    // One authoritative statement of the config shape, on the flag that stores
+    // it. The previous copy — "(filters, sorts, columns, group). Usually written
+    // by the app." — named the LEGACY key and disowned the flag; a blind-eval
+    // agent (2026-09-20) followed it, wrote {"group":{"columnKey":...}}, and got a
+    // board that grouped by accident. --group-by is the plain path; this is the
+    // full one, and it says which key is the grouping key.
+    const TABLE_VIEW_CONFIG_HELP = 'JSON view config, typed v2 shape: {"version":2,"groupBy":"<select column key>","filterTree":{...},"sorts":[{"columnKey":"...","direction":"asc|desc"}],"visibleColumns":["..."],"cardFields":["..."]}. '
+        + 'groupBy is the kanban group-by column (--group-by sets it for you); a complete board config is \'{"version":2,"groupBy":"lifecycle_stage"}\'. Malformed v2 is rejected with invalid_view_config.';
+    tablesCommand.addCommand(new Command("views")
+        .description("Create and manage saved table views (grid / kanban configurations).")
+        .addCommand(new Command("list")
+        .description("List a table's saved views.")
+        .argument("<table>", "Table id or slug.")
+        .option("--json", "Print a JSON envelope.")
+        .action((table, options) => handleAsyncAction("tables views list", options, () => requestOxygen(`/api/cli/tables/${encodeURIComponent(table)}/views`))))
+        .addCommand(new Command("get")
+        .description("Get one saved view by id.")
+        .argument("<table>", "Table id or slug.")
+        .argument("<view>", "View id.")
+        .option("--json", "Print a JSON envelope.")
+        .action((table, view, options) => handleAsyncAction("tables views get", options, () => requestOxygen(`/api/cli/tables/views?table=${encodeURIComponent(table)}&view=${encodeURIComponent(view)}`))))
+        .addCommand(new Command("create")
+        .description("Create a saved view.")
+        .argument("<table>", "Table id or slug.")
+        .requiredOption("--name <name>", "View name.")
+        .option("--view-type <type>", "table (grid) or kanban (board split into lanes by a select/status column). Defaults to table; --group-by implies kanban. A kanban created without --group-by is not refused: the board renders on the table's first groupable column and every read reports that fallback as effective_group_by plus a warning, so pin the column with --group-by.")
+        .option("--group-by <column>", "Kanban: the editable select/status column key the board splits on, e.g. --group-by lifecycle_stage. Unknown or non-groupable keys are refused with the groupable candidates. The response's effective_group_by is the column the board actually uses.")
+        .option("--config <json>", TABLE_VIEW_CONFIG_HELP)
+        .option("--default", "Make this the table's default view.")
+        .option("--no-default", "Clear this view's default status.")
+        .option("--position <n>", "Zero-based order among the table's saved views.")
+        .option("--json", "Print a JSON envelope.")
+        .action((table, options) => handleAsyncAction("tables views create", options, () => requestOxygen(`/api/cli/tables/${encodeURIComponent(table)}/views`, {
+        method: "POST",
+        body: {
+            name: readOption(options.name),
+            ...(readOption(options.viewType) ? { view_type: readOption(options.viewType) } : {}),
+            ...(readOption(options.groupBy) ? { group_by: readOption(options.groupBy) } : {}),
+            ...(readOption(options.config)
+                ? { config: parseJsonValue(readOption(options.config) ?? "", "--config") }
+                : {}),
+            ...(typeof options.default === "boolean" ? { is_default: options.default } : {}),
+            ...(readOption(options.position) !== null ? { position: readNonNegativeInt(options.position) } : {}),
+        },
+    }))))
+        .addCommand(new Command("update")
+        .description("Update a saved view.")
+        .argument("<table>", "Table id or slug.")
+        .argument("<view>", "View id.")
+        .option("--name <name>", "Rename the view.")
+        .option("--view-type <type>", "table (grid) or kanban (board). A kanban whose config names no group column renders on the first groupable column; reads report that fallback as effective_group_by plus a warning.")
+        .option("--group-by <column>", "Kanban: change the select/status column the board splits on; folds into the stored config and keeps the rest of it. Refused for a grid view unless --view-type kanban is passed with it.")
+        .option("--config <json>", `${TABLE_VIEW_CONFIG_HELP} Replaces the stored config.`)
+        .option("--default", "Make this the table's default view.")
+        .option("--no-default", "Clear this view's default status.")
+        .option("--position <n>", "0-based order among the table's views.")
+        .option("--json", "Print a JSON envelope.")
+        .action((table, view, options) => handleAsyncAction("tables views update", options, () => requestOxygen(`/api/cli/tables/${encodeURIComponent(table)}/views/${encodeURIComponent(view)}`, {
+        method: "PATCH",
+        body: {
+            ...(readOption(options.name) ? { name: readOption(options.name) } : {}),
+            ...(readOption(options.viewType) ? { view_type: readOption(options.viewType) } : {}),
+            ...(readOption(options.groupBy) ? { group_by: readOption(options.groupBy) } : {}),
+            ...(readOption(options.config)
+                ? { config: parseJsonValue(readOption(options.config) ?? "", "--config") }
+                : {}),
+            ...(typeof options.default === "boolean" ? { is_default: options.default } : {}),
+            ...(readOption(options.position) ? { position: Number(readOption(options.position)) } : {}),
+        },
+    }))))
+        .addCommand(new Command("delete")
+        .description("Delete a saved view by id.")
+        .argument("<table>", "Table id or slug.")
+        .argument("<view>", "View id.")
+        .option("--json", "Print a JSON envelope.")
+        .action((table, view, options) => handleAsyncAction("tables views delete", options, () => requestOxygen(`/api/cli/tables/${encodeURIComponent(table)}/views/${encodeURIComponent(view)}`, { method: "DELETE" })))));
+    tablesCommand.addCommand(new Command("auto-run")
+        .description("Inspect and manage a table's standing auto-run configuration (columns queued automatically when new rows are written).")
+        .addCommand(new Command("get")
+        .description("Show a table's standing auto-run configuration (columns queued automatically when new rows are written).")
+        .argument("<table>", "Table id or slug.")
+        .option("--json", "Print a JSON envelope.")
+        .action((table, options) => handleAsyncAction("tables auto-run get", options, () => {
+        const params = new URLSearchParams({ table });
+        return requestOxygen(`/api/cli/tables/auto-run?${params.toString()}`);
+    })))
+        .addCommand(new Command("set")
+        .description("Enable a standing auto-run: automatically queue the given columns for rows written to this table (imports, inserts, upserts), including workflow audience upserts and own-follower capture. A queued cell that already has a value is skipped unless --force, so an upsert that touches an existing, filled row is not charged again. Profile viewers use their separate `viewers enrichment --on` subscription. Default off.")
+        .argument("<table>", "Table id or slug.")
+        .requiredOption("--columns <csv>", "Comma-separated column keys to auto-run on newly written rows (tool, AI, formula, enrichment, bind, or lookup columns).")
+        .option("--sources <csv>", "Which write sources trigger the auto-run: any of import, insert, upsert, send. Defaults to all when omitted.")
+        .option("--force", "Re-run the columns even for rows that already have values.")
+        .option("--max-credits <n>", "Credit ceiling PER enqueued auto-run batch; rows beyond it are skipped with credit_limit_reached. Defaults to your plan's per-delivery ceiling when omitted.")
+        .option("--max-concurrency <n>", "Maximum concurrent row items per auto-run batch.")
+        .option("--json", "Print a JSON envelope.")
+        .action((table, options) => {
+        const columns = readCsvOption(options.columns);
+        const sources = readCsvOption(options.sources);
+        const maxCredits = readPositiveNumber(options.maxCredits);
+        const maxConcurrency = readPositiveInt(options.maxConcurrency);
+        const force = Boolean(options.force);
+        return handleAsyncAction("tables auto-run set", options, () => requestOxygen("/api/cli/tables/auto-run", {
+            method: "POST",
+            body: {
+                table,
+                columns,
+                ...(sources.length ? { sources } : {}),
+                ...(force ? { force: true } : {}),
+                ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+                ...(maxConcurrency ? { max_concurrency: maxConcurrency } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("disable")
+        .description("Disable (clear) a table's standing auto-run configuration.")
+        .argument("<table>", "Table id or slug.")
+        .option("--json", "Print a JSON envelope.")
+        .action((table, options) => handleAsyncAction("tables auto-run disable", options, () => requestOxygen("/api/cli/tables/auto-run", {
+        method: "DELETE",
+        body: { table },
+    })))));
+    tablesCommand.addCommand(new Command("auto-dedupe")
+        .description("Inspect and manage a table's standing auto-dedupe configuration (duplicate rows collapsed automatically after every write; deleted rows are kept in row history).")
+        .addCommand(new Command("get")
+        .description("Show a table's standing auto-dedupe configuration.")
+        .argument("<table>", "Table id or slug.")
+        .option("--json", "Print a JSON envelope.")
+        .action((table, options) => handleAsyncAction("tables auto-dedupe get", options, () => {
+        const params = new URLSearchParams({ table });
+        return requestOxygen(`/api/cli/tables/auto-dedupe?${params.toString()}`);
+    })))
+        .addCommand(new Command("set")
+        .description("Enable a standing auto-dedupe: after every write (insert, upsert, import, send, webhook), duplicate groups containing a just-written row are collapsed by the keep policy — losers are DELETED automatically without per-write approval (kept in row history), and any standing auto-run only enriches the survivors. Runs BEFORE auto-run so credits are never spent on rows about to be deleted. Fuzzy-label matching is on-demand only: use `oxygen tables dedupe --normalize fuzzy-label` instead.")
+        .argument("<table>", "Table id or slug.")
+        .requiredOption("--on <cols>", "Key column(s): one column, or two comma-separated for a composite key (e.g. email or first_name,company).")
+        .option("--normalize <modes>", "Match mode per --on column, comma-separated positionally: exact (default), email, domain, or linkedin. Unpaired columns default to exact; fuzzy-label is rejected (on-demand only).")
+        .option("--keep <policy>", "Survivor per duplicate group (existing rows included): oldest (default), newest, or most-complete.", "oldest")
+        .option("--merge-values <mode>", "Fill the survivor's blank cells from the losers before deleting them: fill-empty.")
+        .option("--json", "Print a JSON envelope.")
+        .action((table, options) => handleAsyncAction("tables auto-dedupe set", options, () => requestOxygen("/api/cli/tables/auto-dedupe", {
+        method: "POST",
+        body: buildTablesAutoDedupeSetBody(table, options),
+    }))))
+        .addCommand(new Command("disable")
+        .description("Disable (clear) a table's standing auto-dedupe configuration.")
+        .argument("<table>", "Table id or slug.")
+        .option("--json", "Print a JSON envelope.")
+        .action((table, options) => handleAsyncAction("tables auto-dedupe disable", options, () => requestOxygen("/api/cli/tables/auto-dedupe", {
+        method: "DELETE",
+        body: { table },
+    })))));
+    tablesCommand.addCommand(new Command("schedule")
+        .description("Scheduled column refresh: a cron workflow re-runs one column on a schedule (only empty/failed cells unless --force). One schedule per column.")
+        .addCommand(new Command("set")
+        .description("Create or replace a column's scheduled refresh (a cron-triggered hosted workflow; visible via `oxygen workflows list`). Paid columns (tool, AI, enrichment) require --max-credits AND --approved; formula columns are free.")
+        .argument("<table>", "Table id or slug.")
+        .argument("<column>", "Column key or id (tool, AI, formula, or enrichment kind).")
+        .option("--cron <expr>", 'Cron expression in UTC, e.g. "0 9 * * *".')
+        .option("--every <sugar>", CADENCE_FLAG_DESCRIPTION)
+        .option("--max-credits <n>", "Credit ceiling PER scheduled refresh; required with --approved for paid columns.")
+        .option("--approved", "Approve the recurring paid runs; required with --max-credits for paid columns.")
+        .option("--force", "Re-run cells that already have values on every tick (full refresh instead of fill-missing).")
+        .option("--json", "Print a JSON envelope.")
+        .action((table, column, options) => {
+        const maxCredits = readPositiveNumber(options.maxCredits);
+        return handleAsyncAction("tables schedule set", options, () => requestOxygen("/api/cli/tables/schedule", {
+            method: "POST",
+            body: {
+                table,
+                column,
+                ...(readOption(options.cron) ? { cron: readOption(options.cron) } : {}),
+                ...(readOption(options.every) ? { every: readOption(options.every) } : {}),
+                ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
+                ...(options.approved ? { approved: true } : {}),
+                ...(options.force ? { force: true } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("list")
+        .description("List a table's scheduled column refreshes.")
+        .argument("<table>", "Table id or slug.")
+        .option("--json", "Print a JSON envelope.")
+        .action((table, options) => handleAsyncAction("tables schedule list", options, () => {
+        const params = new URLSearchParams({ table });
+        return requestOxygen(`/api/cli/tables/schedule?${params.toString()}`);
+    })))
+        .addCommand(new Command("remove")
+        .description("Remove a column's scheduled refresh (deletes the backing cron workflow; future scheduled runs stop).")
+        .argument("<table>", "Table id or slug.")
+        .argument("<column>", "Column key or id.")
+        .option("--json", "Print a JSON envelope.")
+        .action((table, column, options) => handleAsyncAction("tables schedule remove", options, () => requestOxygen("/api/cli/tables/schedule", {
+        method: "DELETE",
+        body: { table, column },
+    })))));
+}