@oxygen-agent/cli 1.936.1 → 1.982.3

package/dist/index.js

@@ -1,6 +1,6 @@
 import { execFileSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, createReadStream, createWriteStream, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, extname, join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
@@ -8,12 +8,13 @@ import { stdin as input, stdout as output } from "node:process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { Command, CommanderError, Option } from "commander";
 import { registerUgcCommands } from "./ugc-commands.js";
+import { registerKnowledgeRepositoryCommands } from "./knowledge-repository-commands.js";
 import { registerVisualCommands } from "./visual-commands.js";
 import { renderPrimaryProviderBoard } from "./admin-primary-providers-render.js";
 import { registerFunctionsCommands } from "./functions-commands.js";
 import { applyOxygenHelp } from "./help.js";
 import { buildCommandManifest, getCommandManifestEntry, searchCommandManifest, suggestCommandNames, } from "./command-manifest.js";
-import { AGENCY_DIRECTORY_REGIONS, AGENCY_DIRECTORY_SERVICES, COLLAB_GATE_KINDS, COLLAB_GATE_PROSE, COLLAB_SUBJECT_KINDS, COLLAB_SUBJECT_KINDS_PROSE, COLLAB_SUBJECT_LABELS, COLLAB_SUBJECT_PROSE, GATE_KIND_SUBJECTS, describeWorkflowStatusChange, formatCellForDisplay, formatCopilotPlanDuration, formatCopilotPlanSeconds, formatPublicBudgetScopes, SUBJECT_PATH_FORMS_PROSE, formatSubjectPath, exitCodeForOxygenError, parseSubjectPath, parseSubjectRef, parseWorkflowStatusChange, isVersionGreater, isVersionLess, KNOWLEDGE_BOOTSTRAP_MAX_CREDITS, MAX_MCP_TOOL_NAME_LENGTH, normalizeCopilotPlanStepStatus, OXYGEN_CAPABILITY_ROUTES, OXYGEN_VERSION, OxygenError, getCapabilityRouteMatch, inferUserCapabilityRoute, parseKnowledgePageMarkdown, PLAN_LIMITS, serializeCapabilityRoute, sleep, success, TABLE_IMPORT_ROW_LIMIT, TAG_KINDS_PROSE, toFailure, workflowMcpToolName, } from "@oxygen/shared";
+import { AGENCY_DIRECTORY_REGIONS, AGENCY_DIRECTORY_SERVICES, COLLAB_GATE_KINDS, COLLAB_GATE_PROSE, COLLAB_SUBJECT_KINDS, COLLAB_SUBJECT_KINDS_PROSE, COLLAB_SUBJECT_LABELS, COLLAB_SUBJECT_PROSE, GATE_KIND_SUBJECTS, describeWorkflowStatusChange, formatCellForDisplay, formatCopilotPlanDuration, formatCopilotPlanSeconds, formatPublicBudgetScopes, SUBJECT_PATH_FORMS_PROSE, formatSubjectPath, exitCodeForOxygenError, parseSubjectPath, parseSubjectRef, parseWorkflowStatusChange, isVersionGreater, isVersionLess, KNOWLEDGE_BOOTSTRAP_MAX_CREDITS, MAX_CLI_JSON_BODY_BYTES, MAX_MCP_TOOL_NAME_LENGTH, normalizeCopilotPlanStepStatus, OXYGEN_CAPABILITY_ROUTES, OXYGEN_VERSION, OxygenError, getCapabilityRouteMatch, inferUserCapabilityRoute, parseKnowledgePageMarkdown, PLAN_LIMITS, serializeCapabilityRoute, sleep, success, TABLE_IMPORT_ROW_LIMIT, TAG_KINDS_PROSE, toFailure, workflowMcpToolName, } from "@oxygen/shared";
 import { TAG_COLORS } from "@oxygen/shared/select-options";
 import { inferImportColumnLabels, inferRowsFileFormat, normalizeImportColumnKey, normalizeRowsForNewTable, normalizeRowsFormat, parseRowsFileBuffer, parseXlsxWorkbookBuffer, } from "@oxygen/shared/file-import";
 import { MAILBOX_IMPORT_FILE_MAX_BYTES as SHARED_MAILBOX_IMPORT_FILE_MAX_BYTES, MAILBOX_IMPORT_ROW_LIMIT as SHARED_MAILBOX_IMPORT_ROW_LIMIT, normalizeMailboxImportFile as normalizeSharedMailboxImportFile, normalizeMailboxImportVendor as normalizeSharedMailboxImportVendor, normalizeMailboxWorkbookRows, parseMailboxImportText, summarizeMailboxImportValidation as summarizeSharedMailboxImportValidation, } from "@oxygen/shared/mailbox-import";
@@ -24,7 +25,7 @@ import { clearCredentials, defaultApiUrl, listCredentialProfiles, loadCredential
 import { ensureFreshCliForApiUrl, requestOxygen } from "./http-client.js";
 import { acquireMirrorLock, clearConflictFiles, deletePageFile, emptyMirrorState, findMirrorSlugByPageId, isFileDirty, listConflictFiles, listLocalMirrors, localPageSha256, markMirrorStale, mirrorExists, pageFilePath, planMirrorPush, purgeMirror, resetMirrorForFullResync, quarantineDirtyFile, readMirrorState, releaseMirrorLock, resolveDefaultConfigDir, resolveMirrorDir, writeGeneratedIndexFile, writeGeneratedLogFile, writeMirrorState, writePageFile, } from "./knowledge-mirror.js";
 import { waitForCliRun } from "./run-wait.js";
-import { assertModeFlagsExclusive, parseKeyValuePairs, parseJsonObject, readJsonObjectOption, readPositiveInt, readRecordString, resolveLiveDryRunMode, } from "./cli-values.js";
+import { assertModeFlagsExclusive, parseKeyValuePairs, parseJsonObject, readJsonObjectOption, readNonNegativeInt, readPositiveInt, readRecordString, resolveLiveDryRunMode, } from "./cli-values.js";
 import { formatAiPromptPreviewNotice, formatColumnReferenceNotices, } from "./column-run-notices.js";
 import { runLocalCustomHttpColumn } from "./local-custom-http-column.js";
 import { captureCurrentTranscript, collectFeedbackEnvironment, TranscriptCaptureError, } from "./transcript.js";
@@ -200,8 +201,13 @@ function buildFindBody(capability, options) {
     }
     if (options.mode)
         body.mode = options.mode;
-    const maxCredits = readPositiveNumber(options.maxCredits);
-    if (maxCredits)
+    // Company only: 0 is a real ceiling meaning "run only the zero-credit lanes".
+    // The person capabilities are paid on every lane, so 0 stays a usage error
+    // there. `!== undefined` because 0 is falsy and would otherwise be dropped.
+    const maxCredits = capability === "company"
+        ? readCreditCeilingOrZero(options.maxCredits)
+        : readPositiveNumber(options.maxCredits);
+    if (maxCredits !== undefined)
         body.max_credits = maxCredits;
     // Phone-only opt-in; the route ignores it for other capabilities.
     if (options.verify)
@@ -410,6 +416,335 @@ function writeTableLinkPreview(table, data, options) {
     if (data.web_url)
         out(`  ${data.web_url}`);
 }
+/**
+ * The active warm-up filter as the flags that produced it, or null for a
+ * pool-wide read.
+ *
+ * The server's echo wins because it is what was actually applied; the flags this
+ * CLI sent are the fallback for a server too old to echo anything. Neither path
+ * invents a number — the choice here is only about WORDING, because the counts
+ * are already scoped to the matches and printing them bare reads as the whole
+ * workspace.
+ */
+function describeMailboxFilters(echo, filterFlags) {
+    const parts = [];
+    if (echo) {
+        // Query order, so the line reads back as the command that produced it.
+        if (typeof echo.status === "string" && echo.status.length > 0) {
+            parts.push(`--status ${echo.status}`);
+        }
+        if (Array.isArray(echo.tag) && echo.tag.length > 0)
+            parts.push(`--tag ${echo.tag.join(",")}`);
+        if (Array.isArray(echo.warmup) && echo.warmup.length > 0) {
+            parts.push(`--warmup ${echo.warmup.join(",")}`);
+        }
+        if (Array.isArray(echo.next_action) && echo.next_action.length > 0) {
+            parts.push(`--next-action ${echo.next_action.join(",")}`);
+        }
+        if (echo.stalled === true)
+            parts.push("--stalled");
+    }
+    if (parts.length === 0)
+        parts.push(...filterFlags);
+    return parts.length > 0 ? parts.join(" ") : null;
+}
+const MAILBOX_POOL_COLUMNS = 80;
+/**
+ * How many mailboxes may owe an action before a block each stops being a list
+ * and becomes a wall. Measured on dev's eval workspace: 223 of 224 mailboxes
+ * needed one, and a block each printed ~1,100 lines in which the same four
+ * sentences repeated 93 times and the single unusual seat was buried in the
+ * middle of them. Under this limit the per-mailbox detail IS the value, so it
+ * stays exactly as it is; over it, the same rows are grouped by the step they
+ * need and the filter that selects each group is printed instead.
+ */
+const MAILBOX_POOL_DETAIL_LIMIT = 12;
+/** Example addresses per group, and rows sampled from a long settled list. */
+const MAILBOX_POOL_SAMPLES = 3;
+/** Distinct cause sentences named before the rest are counted off. */
+const MAILBOX_POOL_CAUSE_SAMPLES = 3;
+/**
+ * Wrap prose under a label, hanging-indented to the label's width. Commands are
+ * never passed through here.
+ */
+function writeWrappedPoolProse(out, prefix, text, 
+// Defaults to the label's own width; the headline overrides it, because a
+// continuation starting at column 0 with `--next-action` reads as a separate
+// command rather than the rest of a sentence.
+hangingIndent) {
+    const [first, ...rest] = text.split(/\s+/).filter(Boolean);
+    if (!first)
+        return;
+    const indent = hangingIndent ?? " ".repeat(prefix.length);
+    let line = `${prefix}${first}`;
+    for (const word of rest) {
+        if (line.length + 1 + word.length > MAILBOX_POOL_COLUMNS) {
+            out(line);
+            line = `${indent}${word}`;
+            continue;
+        }
+        line = `${line} ${word}`;
+    }
+    out(line);
+}
+/**
+ * `warmupNeedsAction`, read off the wire instead of recomputed: the server
+ * publishes the code, the CLI only compares it. A row from a server that sends no
+ * warmupTruth cannot owe an action this renderer could name, so it reads as
+ * settled rather than being invented into the urgent list.
+ */
+function mailboxNeedsWarmupAction(row) {
+    const code = row.warmupTruth?.next_action?.code;
+    return typeof code === "string" && code !== "none";
+}
+function mailboxPoolRow(row) {
+    const address = row.emailAddress ?? row.id ?? "(unnamed mailbox)";
+    const truth = row.warmupTruth;
+    const state = truth?.state ?? row.warmupState ?? "unknown";
+    const dispatch = truth?.dispatch;
+    const facts = [];
+    if (typeof dispatch?.current_day === "number")
+        facts.push(`day ${dispatch.current_day}`);
+    // A measured 0 is the entire story of a billed, silent seat, so it is printed.
+    // A null count was never reported by the rail and must not be shown as zero.
+    if (typeof dispatch?.sent === "number") {
+        facts.push(`${dispatch.sent.toLocaleString("en-US")} sent`);
+    }
+    // Only when it is not the boring answer: a mailbox OXYGEN is not sending from
+    // at all explains a silent warm-up faster than any warm-up field can.
+    if (typeof row.status === "string" && row.status !== "active")
+        facts.push(row.status);
+    return `  ${address.padEnd(34)} ${state.padEnd(12)} ${facts.join("   ")}`.trimEnd();
+}
+/** One mailbox's block: what it is, why, who stopped it, and what to run. */
+function writeMailboxActionDetail(out, row) {
+    out(mailboxPoolRow(row));
+    const truth = row.warmupTruth;
+    if (truth?.label)
+        writeWrappedPoolProse(out, "    Why:  ", truth.label);
+    const pauseLabel = truth?.pause?.paused === true ? truth.pause.label : null;
+    // Who stopped it, when the state sentence did not already say so.
+    if (pauseLabel && !(truth?.label ?? "").includes(pauseLabel)) {
+        writeWrappedPoolProse(out, "    Stop: ", pauseLabel);
+    }
+    const action = truth?.next_action;
+    if (action?.label)
+        writeWrappedPoolProse(out, "    Fix:  ", action.label);
+    if (action?.command)
+        out(`    Run:  ${action.command}`);
+    out();
+}
+/**
+ * One mailbox's next command with its own address replaced by a placeholder, so
+ * 93 rows that differ only by recipient collapse to one printable shape instead
+ * of 93 near-identical lines.
+ */
+function mailboxCommandShape(row) {
+    const command = row.warmupTruth?.next_action?.command;
+    if (typeof command !== "string" || command.length === 0)
+        return null;
+    const address = row.emailAddress;
+    return address ? command.replaceAll(address, "<address>") : command;
+}
+function groupMailboxesByNextAction(rows) {
+    const groups = new Map();
+    for (const row of rows) {
+        const action = row.warmupTruth?.next_action;
+        const code = typeof action?.code === "string" ? action.code : "unknown";
+        const group = groups.get(code) ?? { code, rows: [], causes: [], commands: [] };
+        group.rows.push(row);
+        // Collected, never merged: two mailboxes can need the same step for
+        // different reasons, and printing one of those reasons over both is a lie
+        // the reader would act on.
+        if (action?.label && !group.causes.includes(action.label))
+            group.causes.push(action.label);
+        const shape = mailboxCommandShape(row);
+        if (shape && !group.commands.includes(shape))
+            group.commands.push(shape);
+        groups.set(code, group);
+    }
+    // Biggest first — the wall is what most needs collapsing — and alphabetically
+    // inside a tie so two runs over the same pool read the same way.
+    return [...groups.values()].sort((left, right) => right.rows.length - left.rows.length || left.code.localeCompare(right.code));
+}
+/**
+ * Example addresses, fitted to the line rather than counted out blindly: the
+ * trailing "(+N more)" is part of the budget, so this line cannot be the one
+ * that breaks the 80-column promise.
+ */
+function mailboxSampleLine(rows, prefix) {
+    const addresses = rows.map((row) => row.emailAddress ?? row.id ?? "(unnamed mailbox)");
+    const shown = [];
+    for (const address of addresses.slice(0, MAILBOX_POOL_SAMPLES)) {
+        const remaining = addresses.length - (shown.length + 1);
+        const suffix = remaining > 0 ? `  (+${remaining} more)` : "";
+        const candidate = `${prefix}${[...shown, address].join(", ")}${suffix}`;
+        if (candidate.length > MAILBOX_POOL_COLUMNS && shown.length > 0)
+            break;
+        shown.push(address);
+    }
+    const remaining = addresses.length - shown.length;
+    return `${prefix}${shown.join(", ")}${remaining > 0 ? `  (+${remaining} more)` : ""}`;
+}
+/** The opening sentence, marked as clipped when there was more after it. */
+function firstSentenceOf(text) {
+    const [first] = text.split(/(?<=[.!?])\s+/);
+    if (!first || first.length === text.length)
+        return text;
+    // The clipped sentence keeps its own question or exclamation mark; a full stop
+    // becomes the ellipsis, so the line never reads ". ...".
+    return `${first.replace(/\.$/, "")}\u2026`;
+}
+/**
+ * `listAll` is the other side of the `List:` line this function prints: once the
+ * reader has narrowed to one group, the samples they were given to choose with
+ * are no longer the answer — the addresses are. So a single group states its
+ * shared cause and command once, then lists every member compactly, and drops
+ * the filter line that would only point back at the view they are already in.
+ */
+function writeMailboxActionGroups(out, groups, listAll = false) {
+    for (const group of groups) {
+        const count = group.rows.length;
+        const [only] = group.rows;
+        const noun = `${count} mailbox${count === 1 ? "" : "es"}`;
+        // A group of one is the odd seat in a pool of hundreds — the one thing a
+        // wall of repeated blocks buries. Name it on its own header line.
+        out(count === 1 && only
+            ? `  ${group.code}   ${noun}: ${only.emailAddress ?? only.id ?? "(unnamed mailbox)"}`
+            : `  ${group.code}   ${noun}`);
+        const [firstCause, ...otherCauses] = group.causes;
+        if (firstCause && otherCauses.length === 0) {
+            writeWrappedPoolProse(out, "    Why:  ", firstCause);
+        }
+        else if (firstCause) {
+            out(`    Why:  ${group.causes.length} different causes share this next step:`);
+            for (const cause of group.causes.slice(0, MAILBOX_POOL_CAUSE_SAMPLES)) {
+                // Opening sentence only: what differs between two causes sharing one
+                // next step is stated up front (the domain, the fault), and the rest is
+                // the shared remedy repeated verbatim. The full text is one `List:` line
+                // away, printed directly below.
+                writeWrappedPoolProse(out, "      - ", firstSentenceOf(cause));
+            }
+            if (group.causes.length > MAILBOX_POOL_CAUSE_SAMPLES) {
+                out(`      ... ${group.causes.length - MAILBOX_POOL_CAUSE_SAMPLES} more distinct causes`);
+            }
+        }
+        // One member means the real command; more means the shape, because a
+        // placeholder is honest about the 92 addresses it stands for.
+        const single = count === 1 && only ? only.warmupTruth?.next_action?.command : null;
+        const commands = single ? [single] : group.commands;
+        for (const command of commands.slice(0, 2))
+            out(`    Run:  ${command}`);
+        if (commands.length > 2) {
+            const rest = commands.length - 2;
+            out(`    ...   ${rest} more command ${rest === 1 ? "shape" : "shapes"} in this group`);
+        }
+        if (listAll) {
+            out();
+            for (const row of group.rows)
+                out(mailboxPoolRow(row));
+            out();
+            continue;
+        }
+        if (count > 1)
+            out(mailboxSampleLine(group.rows, "    e.g.  "));
+        // The exact filter that turns this group back into every one of its members.
+        out(`    List: oxygen mailboxes list --next-action ${group.code}`);
+        out();
+    }
+}
+function writeMailboxPoolOverview(data, view) {
+    const out = (line = "") => process.stdout.write(`${line}\n`);
+    const rows = data.mailboxes ?? [];
+    const total = typeof data.count === "number" ? data.count : rows.length;
+    const warmup = data.summary?.warmup;
+    const filterLabel = describeMailboxFilters(data.filters, view.filterFlags);
+    if (filterLabel) {
+        // count, summary.total and summary.warmup are all scoped to what matched, so
+        // the pool-wide headline would be right about the wrong population: "2
+        // mailboxes" to a founder with 224 inboxes is not a smaller number, it is a
+        // false one. Name the filter, count the matches, and say which is which.
+        const stalled = warmup?.stalled;
+        const clause = typeof stalled === "number" && stalled > 0 && stalled < total
+            ? ` — ${stalled} of them have never sent`
+            : "";
+        writeWrappedPoolProse(out, "", `${total} mailbox${total === 1 ? "" : "es"} match${total === 1 ? "es" : ""} ${filterLabel}${clause}`, "  ");
+        out("(a filtered view — not your whole pool; run oxygen mailboxes list for that)");
+    }
+    else {
+        const headline = [`${total} mailbox${total === 1 ? "" : "es"}`];
+        if (typeof warmup?.enrolled === "number")
+            headline.push(`${warmup.enrolled} in warm-up`);
+        if (typeof warmup?.stalled === "number") {
+            headline.push(`${warmup.stalled} enrolled but never sent`);
+        }
+        out(headline.join("   "));
+    }
+    // An older server has no summary.warmup at all. Say that under either
+    // headline, rather than printing a 0 a customer would read as "nothing is
+    // stalled" — or, in the filtered view, silently omitting the one count that
+    // explains why no stalled clause appeared.
+    if (!warmup)
+        out("(this server does not report warm-up pool counts)");
+    out();
+    if (rows.length === 0) {
+        out(view.filtered ? "No mailbox matches that filter." : "No mailboxes in this workspace yet.");
+        const emptyLink = data.web_url ?? data.deepLink;
+        if (emptyLink) {
+            out();
+            out(emptyLink);
+        }
+        return;
+    }
+    const needsAction = rows.filter((row) => mailboxNeedsWarmupAction(row));
+    const settled = rows.filter((row) => !mailboxNeedsWarmupAction(row));
+    // First, and never behind the healthy ones: this block is the reason the
+    // command was run.
+    if (needsAction.length > 0 && needsAction.length <= MAILBOX_POOL_DETAIL_LIMIT) {
+        out(`NEEDS ACTION (${needsAction.length})`);
+        out();
+        for (const row of needsAction)
+            writeMailboxActionDetail(out, row);
+    }
+    else if (needsAction.length > 0) {
+        const groups = groupMailboxesByNextAction(needsAction);
+        if (groups.length === 1) {
+            out(`NEEDS ACTION (${needsAction.length}) — all of them need the same next step`);
+            out();
+            writeMailboxActionGroups(out, groups, true);
+        }
+        else {
+            out(`NEEDS ACTION (${needsAction.length}) — grouped by next step, not listed one by one`);
+            out();
+            writeMailboxActionGroups(out, groups);
+            // Nothing is hidden, and the reader should not have to add the groups up
+            // to be sure of it.
+            out(`  All ${needsAction.length} are in a group above. Add --json for every row.`);
+            out();
+        }
+    }
+    if (settled.length > 0) {
+        out(`NOTHING TO DO (${settled.length})`);
+        out();
+        // A healthy mailbox has nothing to say beyond existing, so past the limit a
+        // sample plus the count carries the same information as the whole list.
+        const shown = settled.length <= MAILBOX_POOL_DETAIL_LIMIT
+            ? settled
+            : settled.slice(0, MAILBOX_POOL_SAMPLES);
+        for (const row of shown)
+            out(mailboxPoolRow(row));
+        if (shown.length < settled.length) {
+            out(`  ... ${settled.length - shown.length} more, not listed`);
+        }
+        out();
+    }
+    const link = data.web_url ?? data.deepLink;
+    if (link)
+        out(link);
+    if (!view.filtered && needsAction.length > 0) {
+        out("Narrow it with --stalled, --warmup <state>, or --next-action <code>.");
+    }
+}
 function emitSuccess(command, data, options) {
     if (options.json) {
         writeJson(success(command, data));
@@ -427,6 +762,7 @@ async function handleAsyncAction(command, options, action) {
         writeBillingNotices(command, data);
         emitSuccess(command, data, options);
         writeDryRunNotice(data);
+        writeManagedProviderAvailabilityNotice(data);
         writeAvatarWarning(data);
         writeCreditsReceipt(data);
     }
@@ -434,6 +770,37 @@ async function handleAsyncAction(command, options, action) {
         emitCliFailure(command, error);
     }
 }
+// The preview-time face of the managed-provider credit bench (OXP-1.14.11).
+// `companies search plan` / `companies search run --mode dry_run` carry
+// `provider_availability` and `verify email` (dry_run) carries
+// `catch_all_escalation_available`; both are in the envelope for --json readers,
+// but a benched provider buried in a 150-line plan is exactly how a customer
+// sizes and approves a run that Oxygen already knows will be refused. One line
+// per benched provider on stderr, same stdout/stderr split as the dry-run notice.
+function writeManagedProviderAvailabilityNotice(data) {
+    const payload = asPayloadRecord(data);
+    if (!payload)
+        return;
+    const availability = asPayloadRecord(payload.provider_availability);
+    if (availability) {
+        const providers = asPayloadRecord(availability.providers) ?? {};
+        for (const [provider, entry] of Object.entries(providers)) {
+            const record = asPayloadRecord(entry);
+            if (record?.status !== "benched" && record?.status !== "unknown")
+                continue;
+            const message = typeof record.message === "string" ? record.message
+                : record.status === "unknown" ? `Oxygen could not check its managed ${provider} account availability.`
+                    : `Oxygen's managed ${provider} account is benched.`;
+            const nextAction = typeof record.next_action === "string" ? ` ${record.next_action}` : "";
+            process.stderr.write(`! ${message}${nextAction}\n`);
+        }
+        return;
+    }
+    if ((payload.catch_all_escalation_available === false || payload.catch_all_escalation_availability === "unknown")
+        && typeof payload.next_action === "string") {
+        process.stderr.write(`! ${payload.next_action}\n`);
+    }
+}
 // Single-source the CLI failure-emit contract: write the machine-readable
 // failure envelope to stdout, surface any spend-gate hint on stderr, and set the
 // process exit code from the error. Command handlers that don't route through
@@ -443,6 +810,33 @@ function emitCliFailure(command, error) {
     writeMaxCreditsHint(error);
     process.exitCode = error instanceof OxygenError ? exitCodeForOxygenError(error) : 1;
 }
+// A post's engagers list is the one payload in this tree that is routinely
+// thousands of lines long, and the field that decides whether you may act on it
+// — `truncated` — is one boolean inside it. Printed raw, a partial audience
+// looks exactly like a whole one until you scroll past every person in it. So
+// lead with the receipt on stderr (the same stdout/stderr split the dry-run and
+// credits notices use, leaving stdout a clean envelope) and say plainly what to
+// do about a short read. `--json` callers are untouched: they read the fields.
+function writeEngagersReceipt(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return;
+    const record = data;
+    const pages = isRecord(record.pages_read) ? record.pages_read : {};
+    const line = (text) => process.stderr.write(`${text}\n`);
+    line(`Post ${String(record.post ?? "?")}`);
+    line(`  ${String(record.total_engagers ?? 0)} engagers`
+        + ` (${String(record.reactors_count ?? 0)} reactions, ${String(record.commenters_count ?? 0)} comments)`
+        + ` from ${String(pages.reactions ?? 0)}+${String(pages.comments ?? 0)} pages`);
+    if (record.truncated === true) {
+        const reason = typeof record.partial_reason === "string" ? record.partial_reason : "unknown";
+        line(`  PARTIAL (${reason}) — this post has more engagers than were read.`);
+        line(reason === "max_pages"
+            ? "  Raise --max-pages (max 20), or run `oxygen engagement harvest` to walk the whole post into a table."
+            : "  Retry, or run `oxygen engagement harvest` to walk the whole post into a table.");
+    }
+    if (typeof record.web_url === "string")
+        line(`  ${record.web_url}`);
+}
 // A dry run's stdout envelope looks like a successful result — same shape, same
 // `ok: true` — so in a terminal the only tell that nothing was fetched was
 // `meta.mode` buried inside the payload. That is how a working provider key gets
@@ -1728,6 +2122,7 @@ function buildPublishingPostCreateBody(options) {
     const providerConnection = readOption(options.providerConnection);
     const title = readOption(options.title);
     const timezone = readOption(options.timezone);
+    const ugcParticipationId = readOption(options.ugcParticipationId);
     const content = buildPublishingContent(options);
     if (provider)
         body.provider = provider;
@@ -1741,6 +2136,12 @@ function buildPublishingPostCreateBody(options) {
         body.title = title;
     if (timezone)
         body.timezone = timezone;
+    if (ugcParticipationId) {
+        if (options.approved) {
+            throw new OxygenError("ugc_draft_required", "A program-bound personal post must be saved unapproved. Remove --approved, then review it in Publishing → UGC.", { exitCode: 1 });
+        }
+        body.ugc_participation_id = ugcParticipationId;
+    }
     if (content)
         body.content = content;
     return body;
@@ -1825,6 +2226,12 @@ function buildPublishingContent(options) {
 }
 function resolvePublishingCreateStatus(options) {
     const status = readOption(options.status);
+    if (readOption(options.ugcParticipationId)) {
+        if (status && status !== "draft") {
+            throw new OxygenError("ugc_draft_required", "--ugc-participation-id only creates an unapproved draft; omit --status or pass --status draft.", { exitCode: 1 });
+        }
+        return "draft";
+    }
     if (options.draft === true && status && status !== "draft") {
         throw new OxygenError("conflicting_flags", "Pass either --draft or --status, not both.", { exitCode: 1 });
     }
@@ -2658,7 +3065,7 @@ export function createProgram() {
     const directoryDocsUrl = `${defaultApiUrl()}/docs/agencies`;
     program
         .name(binaryName)
-        .description("Revenue infrastructure for B2B startups — agent-operated GTM: tables, enrichment, sequences, workflows, CRM, knowledge. MCP + CLI first; every state-changing action returns a web_url deep-link.")
+        .description("Revenue infrastructure for B2B startups — agent-operated GTM: tables, enrichment, sequences, workflows, CRM, knowledge. Everything here also runs in the web app and over MCP; every state-changing action returns a web_url deep-link.")
         .version(OXYGEN_VERSION)
         .option("--profile <name>", "Use a stored CLI profile for this command.")
         .option("--org <organization>", "Use an organization id, Clerk org id, or slug for this command.");
@@ -3059,7 +3466,7 @@ export function createProgram() {
         .description("Open and track Plain support conversations for the active OXYGEN organization. In the app, the support chat is the widget in the bottom-right corner of every page. Retry is the only recovery control; it returns after each failed connection attempt and never creates a Thread. `support chat` starts or continues a zero-credit conversation without making you write a ticket title. Guide: https://oxygen-agent.com/docs/surfaces/support.")
         .addCommand(new Command("chat")
         .description("Start a Plain Chat conversation from one message, or pass an existing Thread ID to continue it. New conversations derive Plain's internal title from the message; you never have to file each message as a separate titled ticket.")
-        .argument("[threadId]", "Existing Plain Thread ID (th_...) to continue. Omit to start a new conversation.")
+        .argument("[threadId]", "Existing Plain Thread ID (th_...) or Thread ref (T-<n>) to continue. Omit to start a new conversation.")
         .requiredOption("-m, --message <message>", "Your message to OXYGEN support.")
         .option("--severity <severity>", "New conversation only: low | normal | high. Defaults to normal.")
         .option("--category <category>", "New conversation only: question, bug, feature_request, billing, security_data, configuration, agency_directory, or other. Defaults to question.")
@@ -3120,14 +3527,14 @@ Examples:
     }))
         .addCommand(new Command("get")
         .description("Show one Plain support Thread and its customer-visible timeline.")
-        .argument("<ticketId>", "Plain Thread ID (th_...) or migrated legacy ticket UUID.")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>) — both shown by `oxygen support list` as `id` and `ref` — or a migrated legacy ticket UUID.")
         .option("--json", "Print a JSON envelope.")
         .action(async (ticketId, options) => {
         await handleAsyncAction("support ticket get", options, () => requestOxygen(`/api/cli/support/tickets/${encodeURIComponent(ticketId)}`));
     }))
         .addCommand(new Command("reply")
         .description("Reply to a Plain Chat thread; migrated or native-channel history continues in one linked Chat thread.")
-        .argument("<ticketId>", "Plain Thread ID (th_...) or migrated legacy ticket UUID.")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>) — both shown by `oxygen support list` as `id` and `ref` — or a migrated legacy ticket UUID.")
         .requiredOption("--body <body>", "Your reply.")
         .option("--json", "Print a JSON envelope.")
         .action(async (ticketId, options) => {
@@ -3158,14 +3565,14 @@ Examples:
     }))
         .addCommand(new Command("get")
         .description("Show one live Plain Thread, its routing metadata, and customer-visible messages (staff only).")
-        .argument("<ticketId>", "Plain Thread ID (th_...).")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
         .option("--json", "Print a JSON envelope.")
         .action(async (ticketId, options) => {
         await handleAsyncAction("support admin get", options, () => requestOxygen(`/api/cli/admin/support/tickets/${encodeURIComponent(ticketId)}`));
     }))
         .addCommand(new Command("open")
         .description("Return the exact Plain Inbox URL for one live Thread (staff only).")
-        .argument("<ticketId>", "Plain Thread ID (th_...).")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
         .option("--json", "Print a JSON envelope.")
         .action(async (ticketId, options) => {
         await handleAsyncAction("support admin open", options, () => requestOxygen(`/api/cli/admin/support/tickets/${encodeURIComponent(ticketId)}`)
@@ -3173,7 +3580,7 @@ Examples:
     }))
         .addCommand(new Command("claim")
         .description("Claim a live Plain Thread and move it to In progress without overwriting another assignee (staff only).")
-        .argument("<ticketId>", "Plain Thread ID (th_...).")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
         .option("--agent", "Claim as the authenticated Oxygen Support machine user instead of the signed-in human.")
         .option("--json", "Print a JSON envelope.")
         .action(async (ticketId, options) => {
@@ -3184,7 +3591,7 @@ Examples:
     }))
         .addCommand(new Command("start")
         .description("Set a live Plain Thread to Plain TODO with the In progress detail when OXYGEN work remains after a reply, preserving its assignee (staff only).")
-        .argument("<ticketId>", "Plain Thread ID (th_...).")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
         .requiredOption("--agent", "Required safety declaration: reconcile this Thread's status as the Oxygen Support machine user.")
         .requiredOption("--confirm-message <messageId>", "Apply only while this is still the exact latest customer-visible conversation-head message ID. From support admin get --json, use the id of the data.messages[] entry with the greatest created_at.")
         .option("--json", "Print a JSON envelope.")
@@ -3211,7 +3618,7 @@ The final readback must show ticket.status triaging, plain_status TODO, the In p
     }))
         .addCommand(new Command("priority")
         .description("Set the native Plain priority for a live Thread (staff only).")
-        .argument("<ticketId>", "Plain Thread ID (th_...).")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
         .requiredOption("--priority <priority>", "urgent | high | normal | low")
         .option("--json", "Print a JSON envelope.")
         .action(async (ticketId, options) => {
@@ -3221,7 +3628,7 @@ The final readback must show ticket.status triaging, plain_status TODO, the In p
     }))
         .addCommand(new Command("snooze")
         .description("Park a live Thread until a named time, so work blocked on a release, a provider, or a scheduled retry stops reading as unanswered (staff only).")
-        .argument("<ticketId>", "Plain Thread ID (th_...).")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
         .option("--days <n>", "Snooze for this many days.")
         .option("--hours <n>", "Snooze for this many hours. Combined with --days when both are given.")
         .requiredOption("--confirm-message <messageId>", "Confirm the exact latest customer-visible message ID. A Thread whose customer just wrote must be answered, not snoozed past.")
@@ -3234,14 +3641,14 @@ The final readback must show ticket.status triaging, plain_status TODO, the In p
     }))
         .addCommand(new Command("todo")
         .description("Return a snoozed Thread to the queue when its blocker clears (staff only). Never reopens a Done Thread: Plain does that on real customer activity.")
-        .argument("<ticketId>", "Plain Thread ID (th_...).")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
         .option("--json", "Print a JSON envelope.")
         .action(async (ticketId, options) => {
         await handleSupportAdminUpdateRequest("todo", ticketId, options, {});
     }))
         .addCommand(new Command("assign")
         .description("Hand a live Thread to a named human, for escalation past an agent's authority or judgment boundary (staff only).")
-        .argument("<ticketId>", "Plain Thread ID (th_...).")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
         .requiredOption("--user <email>", "The staff email to assign the Thread to.")
         .option("--allow-takeover", "Required to move a Thread that already has an owner. Without it, an owned Thread is refused rather than silently reassigned.")
         .option("--json", "Print a JSON envelope.")
@@ -3253,7 +3660,7 @@ The final readback must show ticket.status triaging, plain_status TODO, the In p
     }))
         .addCommand(new Command("field-set")
         .description("Record OXYGEN workflow state on a live Thread as structured, filterable Plain data — which version and commit carry a fix, and the PR that shipped it (staff only).")
-        .argument("<ticketId>", "Plain Thread ID (th_...).")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
         .requiredOption("--field <key>", "oxygen_fix_version | oxygen_fix_sha | oxygen_fix_pr. Customer-intake fields are read-only evidence and cannot be written here.")
         .requiredOption("--value <value>", "The value to record.")
         .option("--json", "Print a JSON envelope.")
@@ -3265,7 +3672,7 @@ The final readback must show ticket.status triaging, plain_status TODO, the In p
     }))
         .addCommand(new Command("label-add")
         .description("Add an active Plain label by external ID (staff only).")
-        .argument("<ticketId>", "Plain Thread ID (th_...).")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
         .requiredOption("--label <externalId>", "Plain label external ID, for example oxygen_request_bug.")
         .option("--json", "Print a JSON envelope.")
         .action(async (ticketId, options) => {
@@ -3275,7 +3682,7 @@ The final readback must show ticket.status triaging, plain_status TODO, the In p
     }))
         .addCommand(new Command("label-remove")
         .description("Remove a Plain label by external ID (staff only).")
-        .argument("<ticketId>", "Plain Thread ID (th_...).")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
         .requiredOption("--label <externalId>", "Plain label external ID.")
         .option("--json", "Print a JSON envelope.")
         .action(async (ticketId, options) => {
@@ -3285,7 +3692,7 @@ The final readback must show ticket.status triaging, plain_status TODO, the In p
     }))
         .addCommand(new Command("note")
         .description("Add a team-only internal note to a live Plain Thread (staff only).")
-        .argument("<ticketId>", "Plain Thread ID (th_...).")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
         .requiredOption("--body <body>", "Internal note body.")
         .option("--json", "Print a JSON envelope.")
         .action(async (ticketId, options) => {
@@ -3295,7 +3702,7 @@ The final readback must show ticket.status triaging, plain_status TODO, the In p
     }))
         .addCommand(new Command("draft")
         .description("Stage a reply as a team-only Plain note; this never sends to the customer (staff and agents).")
-        .argument("<ticketId>", "Plain Thread ID (th_...).")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
         .requiredOption("--body <body>", "Proposed customer reply.")
         .option("--json", "Print a JSON envelope.")
         .action(async (ticketId, options) => {
@@ -3305,7 +3712,7 @@ The final readback must show ticket.status triaging, plain_status TODO, the In p
     }))
         .addCommand(new Command("reply")
         .description("Preview or send a guarded public reply on the Thread's native Plain channel as Oxygen Support (staff only). CLI delivery is agent-only; named humans use Plain Inbox or Plain MCP.")
-        .argument("<ticketId>", "Plain Thread ID (th_...).")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
         .requiredOption("--body <body>", "Customer-visible reply body.")
         .requiredOption("--agent", "Required safety declaration: reply as the authenticated Oxygen Support machine user after it owns the Thread.")
         .option("--confirm-ref <ref>", "Send only when this exactly matches the previewed Plain ref (for example T-10). Omit to preview without sending.")
@@ -3332,7 +3739,7 @@ The final readback must show ticket.status triaging, plain_status TODO, the In p
     }))
         .addCommand(new Command("done")
         .description("Preview or mark a Plain Thread Done after the exact verified agent reply; new customer activity reopens it to Todo (staff only). CLI completion is agent-only.")
-        .argument("<ticketId>", "Plain Thread ID (th_...).")
+        .argument("<ticketId>", "Plain Thread ID (th_...) or Thread ref (T-<n>), as shown by `oxygen support admin list`.")
         .requiredOption("--agent", "Required safety declaration: mark Done as the authenticated Oxygen Support machine user while it still owns the Thread.")
         .requiredOption("--reply-token <token>", "Use the exact agent_done_token returned by the preceding live `support admin reply --agent`; previews and errors never mint or reveal one.")
         .option("--confirm-ref <ref>", "Complete only when this exactly matches the previewed Plain ref.")
@@ -3770,7 +4177,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
     }));
     program
         .command("publishing")
-        .description("Social publishing, performance, and public-comment operations. Start Community triage with `oxygen publishing comments list --view unanswered --json`.")
+        .description("Social publishing, performance, and public-comment operations. Start Community triage with `oxygen publishing comments list --view unanswered --json`. Docs: https://oxygen-agent.com/docs/execution/publishing")
         .addCommand(new Command("mentions")
         .description("Resolve LinkedIn identities for a publish-faithful post preview.")
         .addCommand(new Command("resolve")
@@ -3807,21 +4214,22 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         await handleAsyncAction("publishing posts list", options, () => requestOxygen(buildPublishingPostsListPath(options)));
     }))
         .addCommand(new Command("create")
-        .description("Create a scheduled post. Publishing requires approval before the worker can send.")
-        .requiredOption("--publish-at <iso>", "ISO date-time when the post should publish.")
-        .option("--provider <provider>", "Publishing provider: linkedin, x, instagram, tiktok, facebook, or youtube. Defaults to linkedin.")
+        .description("Create a personal Publishing post. Use --ugc-participation-id to save it into one program as an unapproved draft; otherwise it defaults to scheduled and publishes only after approval.")
+        .requiredOption("--publish-at <iso>", "ISO date-time when the post should publish, e.g. 2026-09-15T10:00:00+02:00. A bare local time with no offset is stored as UTC, never converted into --timezone, so pass an offset or Z to fix the instant; --timezone only changes how it displays.")
+        .option("--provider <provider>", "Publishing provider: linkedin, x, instagram, tiktok, facebook, or youtube. Defaults to linkedin. LinkedIn publishes through --sender; every other provider publishes through a connected account (--provider-connection), which the worker needs before it can deliver.")
         .option("--channel <channel>", "Publishing channel override. Defaults to provider.")
         .option("--sender <sender_account_id>", "LinkedIn sender account id. Required for LinkedIn before the worker can publish.")
-        .option("--provider-connection <connection_id>", "Oxygen integration connection id for Composio-backed providers.")
+        .option("--provider-connection <connection_id>", "Oxygen integration connection id for Composio-backed providers. Find it with `integrations list` (each integration's connection); create one with `integrations connect <provider>` (an OAuth redirect URL, or Settings > Connections on the web).")
         .option("--title <title>", "Internal title for the queue.")
         .option("--text <text>", "Post text. For LinkedIn mentions, use @<public-identifier> directly.")
         .option("--text-file <path>", "Read post text from a local file.")
         .option("--content-json <json>", "Structured content. Use media_asset_ids for Oxygen uploads. LinkedIn attachments require [{content:<base64>,content_type:<MIME>,filename:<name>}]; content.mentions is rejected, so put verified @<public-identifier> values in --text. Composio accepts provider_arguments or composio.arguments.")
         .option("--composio-action <slug>", "Override the Composio action slug for this scheduled post.")
-        .option("--timezone <tz>", "Display timezone for the scheduled date. Defaults to UTC.")
-        .option("--status <status>", "draft or scheduled. Defaults to scheduled.")
+        .option("--timezone <tz>", "Display timezone for the scheduled date. Defaults to the LinkedIn sender's own timezone when --sender is set, else UTC.")
+        .option("--status <status>", "draft or scheduled. Defaults to scheduled. A draft sits outside the queue until `publishing posts approve` schedules and arms it in one step; scheduled is queued for its publish time and still waits for approval.")
         .option("--draft", "Create as a draft instead of scheduled.")
-        .option("--approved", "Mark the post approved for the scheduler.")
+        .option("--ugc-participation-id <id>", "Also enroll this personal post in one active creator participation. It is always saved as an unapproved draft; omit --approved.")
+        .option("--approved", "Mark an ordinary post approved for the scheduler. Invalid with --ugc-participation-id.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("publishing posts create", options, () => requestOxygen("/api/cli/publishing/posts", {
@@ -5013,7 +5421,8 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .description("Source EXTERNAL market signals into a table: hiring, technology adoption, funding, acquisitions, and news. This is the sourcing half of Signals — `signals list` reads the events already captured for your workspace.")
         .addCommand(new Command("plan")
         .description("Compile a signal-sourcing request into ordered provider routes without provider calls: the chain, per-route applied/dropped filters, credit estimate, table blueprint, and whether the route can be kept LIVE on a cadence. Free.")
-        .requiredOption("--prompt <text-or-file>", "Signal-sourcing prompt, or a path to a prompt file.")
+        .argument("[prompt]", "Prompt text or @file (same as --prompt). The --prompt flag wins if both are given.")
+        .option("--prompt <text-or-file>", "Signal-sourcing prompt, or a path to a prompt file.")
         .requiredOption("--family <family>", "Signal family: hiring, tech, funding, acquisition, news, or job_change.")
         .option("--scope <scope>", "market (discover new companies) or watch_list (track companies you name via --domains). Defaults per family.")
         .option("--target-count <n>", "Desired row count for routing and estimates.")
@@ -5027,14 +5436,15 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--filters-json <json-or-file>", "Filters JSON inline or a path to a JSON file; wins over individual flags per top-level filter path.")
         .option("--estimate", "Run the free server-side preflight pass: resolves provider enum values and, where a provider publishes one, a free match count (zero credits).")
         .option("--json", "Print a JSON envelope.")
-        .action(async (options) => {
+        .action(async (promptArg, options) => {
         await handleAsyncAction("signals search plan", options, () => requestOxygen("/api/cli/signals/search/plan", {
             method: "POST",
-            body: readSignalsSearchPlanBody(options),
+            body: readSignalsSearchPlanBody(options, promptArg),
         }));
     }))
         .addCommand(new Command("run")
         .description("Return a dry-run request or queue a live signal-search ingestion run. Live requires --approved and --max-credits. Add --bind-feed --every to also bind a pull feed to the same table in the same call, so the table keeps refilling on a cadence.")
+        .argument("[prompt]", "Prompt text or @file (same as --prompt); requires --family. The --prompt flag wins if both are given.")
         .option("--prompt <text-or-file>", "Signal-sourcing prompt, or a path to a prompt file. Requires --family.")
         .option("--plan-json <json-or-file>", "Plan JSON returned by signals search plan, or a path to a JSON file.")
         .option("--family <family>", "Signal family when planning from --prompt: hiring, tech, funding, acquisition, news, or job_change.")
@@ -5062,10 +5472,10 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--max-credits-per-cycle <n>", "Credit ceiling PER sync cycle for the bound feed.")
         .option("--max-rows-per-cycle <n>", "Advisory row ceiling per sync cycle for the bound feed.")
         .option("--json", "Print a JSON envelope.")
-        .action(async (options) => {
+        .action(async (promptArg, options) => {
         await handleAsyncAction("signals search run", options, () => requestOxygen("/api/cli/signals/search/run", {
             method: "POST",
-            body: readSignalsSearchRunBody(options),
+            body: readSignalsSearchRunBody(options, promptArg),
         }));
     })));
     const tablesCommand = program
@@ -5199,7 +5609,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .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("--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) so they fit request and worker lease budgets.")
+        .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.")
@@ -5208,7 +5618,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         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.")
+        .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.")
@@ -5218,16 +5628,16 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         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.")
+        .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 JSON to a file. Defaults to stdout.")
+        .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. Restores columns (incl. enrichment/tool definitions) and inserts every row. Pass --key to make the import idempotent (re-runnable), and --into to resume a failed import into the table it already created.")
+        .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.")
@@ -5236,7 +5646,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .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));
+        await handleAsyncAction("tables import-bundle", options, () => importTableBundle(options, binaryName));
     }))
         .addCommand(new Command("list")
         .description("List workspace tables in the current tenant database.")
@@ -5278,7 +5688,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .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\"}]}'. Mutually exclusive with --filter-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>\"}. Mutually exclusive with --filter-json.")
         .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.")
         .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).")
@@ -5290,14 +5700,14 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
             const filterTree = readJsonObjectOption(options.filterTreeJson);
             const formulaValues = readFormulaValuesOption(options.formulaValues);
             const sorts = readSortJsonOption(options.sortJson);
-            const offset = readPositiveInt(options.offset);
+            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) {
+            if (readOption(options.cursor) && offset !== undefined) {
                 throw new OxygenError("invalid_request", "Pass either --cursor or --offset, not both.", { exitCode: 1 });
             }
             return requestOxygen("/api/cli/tables/query", {
@@ -5306,7 +5716,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
                     table,
                     ...(limit ? { limit } : {}),
                     ...(readOption(options.cursor) ? { cursor: readOption(options.cursor) } : {}),
-                    ...(offset ? { offset } : {}),
+                    ...(offset !== undefined ? { offset } : {}),
                     ...(readOption(options.fields) ? { fields: readCsvOption(options.fields) } : {}),
                     ...(filters ? { filters } : {}),
                     ...(filterTree ? { filterTree } : {}),
@@ -5324,7 +5734,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .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 table metadata and stats without row JSON.")
+        .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, () => {
@@ -5343,9 +5753,10 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("describe")
-        .description("Describe a workspace table and its columns.")
+        .description("Describe a workspace table and its columns. Add --stats for row count and per-column fill rates (0 credits).")
         .argument("<table>", "Table id or slug.")
         .option("--include-archived", "Include archived columns.")
+        .option("--stats", "Include summary stats: exact row count and per-column fill rates. Exact at or under 100 rows; above that fill rates come from a 100-row sample (summary.statsSampled, summary.statsSampledRowCount) while rowCount stays exact. 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("--json", "Print a JSON envelope.")
         .action(async (table, options) => {
         await handleAsyncAction("tables describe", options, () => requestOxygen("/api/cli/tables/describe", {
@@ -5353,6 +5764,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
             body: {
                 table,
                 ...(options.includeArchived ? { include_archived: true } : {}),
+                ...(options.stats ? { include_stats: true } : {}),
             },
         }));
     }))
@@ -5478,6 +5890,63 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
             });
         });
     }));
+    const watcherCommand = tablesCommand.command("watcher")
+        .description("LinkedIn Profile Watcher: 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 LinkedIn Profile Watcher 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 LinkedIn Profile Watcher 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.");
+            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 } : {}),
+                    },
+                });
+            });
+        });
+    }
     tablesCommand.addCommand(new Command("relate")
         .description("Relate two tables: define empty Tables-owned relation columns on the source and target. 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.")
@@ -6158,7 +6627,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .description("Workspace-level GTM context commands.")
         .addCommand(new Command("resolve")
         .description("Resolve task-scoped workspace GTM context with readiness and revision provenance.")
-        .option("--purpose <purpose>", "general, lead_sourcing, qualification, outbound_copy, or workflow_design.")
+        .option("--purpose <purpose>", "onboarding, general, lead_sourcing, qualification, outbound_copy, or workflow_design.")
         .option("--asset-type <csv>", "Comma-separated context asset types to include.")
         .option("--asset-status <status>", "draft, active, archived, or all. Defaults to active.")
         .option("--tags <csv>", "Comma-separated asset tags that must be present.")
@@ -6279,9 +6748,9 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
     // command, not on `status` — the same collision the `commands` group above
     // handles. The named reference lets `status` read the parent's flag back.
     const knowledgeBootstrapCommand = new Command("bootstrap")
-        .description(`Research THIS workspace's own company from its domain and fill the typed company profile plus one cited wiki page — the empty-Knowledge-Graph fix, so a founder never has to type their own positioning back at us. Two authorization paths, and they are NOT the same: running this command manually is authorized by --live (plus --max-credits), like every other paid Oxygen action; the identical pass that runs ONCE automatically after signup is authorized by the consent recorded at signup instead, and is capped (<= ${KNOWLEDGE_BOOTSTRAP_MAX_CREDITS} credits), journalled (a marker, a system run, and immutable page sources), kill-switched fleet-wide, and reversible. A bare call previews: it resolves the domain, plans the reads, estimates the cost, and spends nothing. Once per workspace ever — any existing marker (completed, partial, skipped, failed) blocks a second pass until --force clears it.`)
-        .option("--domain <domain>", "Company apex domain to research. Defaults to the workspace domain resolved at signup from the org's Clerk metadata or the creator's email; a personal-email signup has none, and a preview says so instead of guessing.")
-        .option("--linkedin <url>", "Company LinkedIn URL, as a second identity signal alongside the domain.")
+        .description(`Research this workspace's company through direct LinkedIn company enrichment and website reads. Save company facts, a cited wiki note, and separate inferred ICP, offer, and opportunity hypotheses. A bare call previews for free; manual execution is customer-funded and requires --live plus --max-credits (hard cap ${KNOWLEDGE_BOOTSTRAP_MAX_CREDITS}). The separate automatic signup pass is platform-funded, runs once under the consent recorded when the workspace was created (its required company website), and may also research the actual creator. Check bootstrap status before spending; an existing marker blocks a repeat unless --force re-arms it.`)
+        .option("--domain <domain>", "Company domain to research. Defaults to the recorded workspace domain; if none is available, the preview asks for one.")
+        .option("--linkedin <url>", "Optional company LinkedIn URL to use for the direct lookup. The returned company website must still match the domain.")
         .option("--live", "Authorize this manual run to spend and write. Requires --max-credits. Without it the command previews and nothing is billed.")
         .option("--approved", "Same as --live. Accepted because the global help footer names --approved as the way to authorize a credit-spending command.")
         .option("--max-credits <credits>", `Hard credit ceiling for the whole pass. Required with --live, and clamped server-side to ${KNOWLEDGE_BOOTSTRAP_MAX_CREDITS}.`)
@@ -6607,7 +7076,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
     })))
         .addCommand(new Command("resolve")
         .description("Resolve task-scoped workspace GTM context with readiness and revision provenance.")
-        .option("--purpose <purpose>", "general, lead_sourcing, qualification, outbound_copy, or workflow_design.")
+        .option("--purpose <purpose>", "onboarding, general, lead_sourcing, qualification, outbound_copy, or workflow_design.")
         .option("--asset-type <csv>", "Comma-separated context asset types to include.")
         .option("--asset-status <status>", "draft, active, archived, or all. Defaults to active.")
         .option("--tags <csv>", "Comma-separated asset tags that must be present.")
@@ -7361,7 +7830,15 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("show")
-        .description("Show one recipe: the full playbook body plus prerequisites, credits, and approval gates.")
+        // `get` is what a naive agent reaches for first, because `workflows`,
+        // `knowledge page` and `table-ingestions` all use it and only `recipes`
+        // uses `show` (while `sequences` is the mirror image and rejects
+        // `show`). A blind user eval on 2026-09-13 burned two steps on
+        // `recipes get inbound-led-outbound` -> "unknown command 'get'".
+        // The catalog is the front door of the whole kit; it should not punish
+        // the guess the rest of the CLI teaches.
+        .alias("get")
+        .description("Show one recipe: its kit, the install status of each stage here, prerequisites, credits, approval gates, and the playbook body. Alias: `get`.")
         .argument("<slug>", "Recipe slug, e.g. outbound-pilot-50.")
         .option("--json", "Print a JSON envelope.")
         .action(async (slug, options) => {
@@ -7389,6 +7866,40 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
                 body.force = true;
             return requestOxygen("/api/cli/recipes/install", { method: "POST", body });
         });
+    }))
+        .addCommand(new Command("apply")
+        .description("Install a recipe's kit: every Blueprint stage in order under ONE approval — 0 credits, no provider calls, no external writes, every installed Workflow disabled until you arm it with its own credit cap. A stage whose Workflow is already active is left untouched. `--dry-run` preflights every stage into one combined forecast and writes nothing.")
+        .argument("<slug>", "Recipe slug, e.g. inbound-led-outbound.")
+        .option("--input-json <json>", "Stage inputs as a JSON object keyed by blueprint id, e.g. '{\"linkedin-profile-engager-monitor\":{\"profiles\":[\"https://www.linkedin.com/in/example\"],\"max_credits\":2200}}'.")
+        .option("--table-ref <blueprint.ref=table...>", "Bind a stage's table ref to an existing table id or slug, e.g. --table-ref linkedin-engager-tier-router.engaged_people=linkedin-engaged-people (repeatable).", collectMultiple, [])
+        .option("--dry-run", "Preflight every stage and print the combined forecast; installs nothing.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (slug, options) => {
+        const command = options.dryRun ? "recipes preflight" : "recipes apply";
+        await handleAsyncAction(command, options, () => {
+            const body = { slug };
+            const inputJson = readOption(options.inputJson);
+            if (inputJson)
+                body.inputs = parseJsonValue(inputJson, "--input-json");
+            const tableRefs = {};
+            for (const entry of options.tableRef ?? []) {
+                const eq = entry.indexOf("=");
+                const dot = entry.indexOf(".");
+                if (eq <= 0 || dot <= 0 || dot > eq) {
+                    throw new Error(`--table-ref expects <blueprint>.<ref>=<table id or slug>, got "${entry}"`);
+                }
+                const blueprint = entry.slice(0, dot);
+                const ref = entry.slice(dot + 1, eq);
+                const table = entry.slice(eq + 1);
+                tableRefs[blueprint] = { ...(tableRefs[blueprint] ?? {}), [ref]: table };
+            }
+            if (Object.keys(tableRefs).length > 0)
+                body.table_refs = tableRefs;
+            return requestOxygen(options.dryRun ? "/api/cli/recipes/preflight" : "/api/cli/recipes/apply", {
+                method: "POST",
+                body,
+            });
+        });
     }));
     program.addCommand(buildPromptTemplatesCommand("prompts", "Reusable prompt templates layered into AI columns at run time."));
     // The deprecated `templates` alias tree was removed at its registry sunset
@@ -7468,12 +7979,13 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .argument("<table>", "Table id or slug.")
         .option("--preset <preset>", "Add a pre-built enrichment bundle instead of one column: `person_enrich` (one LinkedIn profile lookup, then headline, bio, location and followers for free) or `company_enrich` (domain, LinkedIn page, headcount, industry and full profile, cascading across providers until one answers). Oxygen finds the identity column itself — override with --input. Creating the columns is free; run them afterwards, --dry-run first.")
         .option("--input <slot=column...>", "Bind a preset input to an exact column, e.g. --input url=linkedin_url, or --input company_name=account --input domain=website. Repeatable. Only needed when the automatic match is wrong or missing.", collectRepeatable, [])
-        .option("--label <label>", "Display label for the new column. Required unless --prompt-key supplies a default title.")
+        .option("--capability <capability>", "Seed a ready-to-run enrichment column WITHOUT running it (0 credits): verify_email grades the address a row already holds \u2014 MillionVerifier first, catch-all domains escalate to BounceBan; work_email, mobile_phone and linkedin_url find a value the row is missing through the managed waterfall. Sets kind=enrichment and jsonb; label and key default from the capability. Preview cost with `enrich-column preview --capability <same>` and run later with `enrich-column run --approved --max-credits <n>`.")
+        .option("--label <label>", "Display label for the new column. Required unless --prompt-key or --capability supplies a default title.")
         .option("--key <key>", "Optional stable column key. Defaults to a normalized label.")
         .option("--data-type <type>", "Column data type: text, numeric, boolean, jsonb, or timestamptz.")
-        .option("--kind <kind>", "Column kind: manual, research, ai, formula, enrichment, tool, bind, or lookup. Defaults to manual. Use research for anything you would look up on the web. `lookup` reads a value out of another table; to LINK two tables row-to-row use `oxygen tables relate` instead \u2014 relation columns are two-sided and cannot be added here.")
+        .option("--kind <kind>", "Column kind: manual, research, ai, formula, enrichment, tool, bind, or lookup. Defaults to manual. Use research for anything you would look up on the web. Enrichment columns always hold a jsonb cell, and --data-type is set for you \u2014 use --capability to seed a ready-to-run one. `lookup` reads a value out of another table; to LINK two tables row-to-row use `oxygen tables relate` instead \u2014 relation columns are two-sided and cannot be added here.")
         .option("--semantic-type <type>", "Optional semantic type such as company_domain.")
-        .option("--definition-json <json>", "Optional JSON object with column definition metadata.")
+        .option("--definition-json <json>", "Optional JSON object with column definition metadata. Required for --kind formula as a flat object: {\"expression\":\"trim(company_name)\"}. Check the expression with `formulas validate` first.")
         .option("--prompt <text-or-file>", "AI or research column prompt, or a path to a prompt file — a value that resolves to a readable file is read as one, matching --prompt everywhere else in this CLI. On its own it sets kind=ai; pair it with --kind research to search the web per row instead. If the prompt names its output sections — a line reading 'Return the following sections:' followed by 'Score: ...', 'Reasoning: ...' — the column answers in exactly that shape and each section becomes a referenceable sub-column; otherwise it answers in plain text. Use --no-structured-output to keep it plain text either way. Reference other columns inline as {{column_key}} — no --input-mapping needed; unknown keys are rejected here instead of failing per row. Merges into --definition-json (the escape hatch for everything else); a `prompt` in both is an error.")
         .option("--research-query <template>", "Research columns: the per-row web search query, templated like the prompt (e.g. \"{{company_name}} pricing page\"). Omit to derive the query from the row's values and the prompt.")
         .option("--research-domains <csv>", "Research columns: comma-separated domains to search within, e.g. techcrunch.com,sec.gov. Omit to search the whole web.")
@@ -7505,6 +8017,36 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         // skipcq: JS-R1005 — intentional per-option branching to assemble the columns-add request body
         .action(async (table, options) => {
         await handleAsyncAction("columns add", options, async () => {
+            // --capability seeds a COMPLETE enrichment column server-side (kind,
+            // jsonb data type, intent, the default provider order, label and
+            // key), so any flag that authors a different column is a conflict,
+            // not a modifier. Caught here rather than server-side so the user
+            // never gets back a column they did not ask for.
+            const capability = readOption(options.capability);
+            if (capability) {
+                const conflicting = [
+                    readOption(options.preset) ? "--preset" : null,
+                    readOption(options.prompt) ? "--prompt" : null,
+                    readOption(options.promptKey) ? "--prompt-key" : null,
+                    readOption(options.bindObject) ? "--bind-object" : null,
+                    readOption(options.bindMap) ? "--bind-map" : null,
+                    options.bindCreate ? "--bind-create" : null,
+                    readOption(options.lookupTable) ? "--lookup-table" : null,
+                    readOption(options.lookupMatch) ? "--lookup-match" : null,
+                    readOption(options.lookupMode) ? "--lookup-mode" : null,
+                    readOption(options.lookupReturn) ? "--lookup-return" : null,
+                    readOption(options.lookupOrder) ? "--lookup-order" : null,
+                    readOption(options.lookupAggregate) ? "--lookup-aggregate" : null,
+                    readOption(options.lookupNormalize) ? "--lookup-normalize" : null,
+                ].filter((flag) => flag !== null);
+                if (conflicting.length > 0) {
+                    throw new OxygenError("invalid_request", `--capability ${capability} seeds a complete enrichment column, so it cannot be combined with ${conflicting.join(", ")}. Drop one of the two.`, { exitCode: 1 });
+                }
+                const capabilityKind = readOption(options.kind)?.toLowerCase() ?? null;
+                if (capabilityKind && capabilityKind !== "enrichment") {
+                    throw new OxygenError("invalid_request", `--capability authors an enrichment column, but --kind ${capabilityKind} was requested. Drop --kind, or drop --capability.`, { exitCode: 1 });
+                }
+            }
             // A preset names its own columns, so --label does not apply to it.
             const preset = readOption(options.preset);
             if (preset) {
@@ -7522,7 +8064,9 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
                     body: presetBody,
                 });
             }
-            if (!options.promptKey && !options.label) {
+            // --capability supplies its own label ("Email Verification", ...)
+            // server-side, the same one the web picker writes.
+            if (!options.promptKey && !capability && !options.label) {
                 throw new OxygenError("invalid_request", "--label is required.", { exitCode: 1 });
             }
             if (options.promptKey && !options.inputMapping) {
@@ -7547,6 +8091,15 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
                 column.definition = parseJsonObject(options.definitionJson);
             const requestedKind = readOption(options.kind)?.toLowerCase() ?? null;
             const isResearch = requestedKind === "research";
+            if (capability)
+                column.capability = capability;
+            // An enrichment cell is always the provider envelope, so the server
+            // rejects any other data type ("Enrichment columns must use jsonb
+            // data type."). Default it, the way --bind-object already does,
+            // instead of making the caller bolt on --data-type jsonb.
+            if (requestedKind === "enrichment" && !options.dataType) {
+                column.data_type = "jsonb";
+            }
             if (prompt !== null) {
                 if (requestedKind && requestedKind !== "ai" && !isResearch) {
                     throw new OxygenError("invalid_request", `--prompt authors an AI or research column, but --kind ${requestedKind} was requested. Drop --kind, or drop --prompt.`, { exitCode: 1 });
@@ -7652,10 +8205,10 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .argument("<column>", "Column id or key.")
         .option("--row-id <row_id>", "Workspace row id to run. Get one from `oxygen tables query <table> --limit 1 --json` — the field is `_row_id`, not `id`.")
         .option("--limit <n>", "Run the next N rows whose target cell is still empty (--force runs the first N regardless). Repeat until rowCount is 0 to page through a table. Defaults to 10; inline deterministic runs have a hard cap of 25.")
-        .option("--all", "Run all rows. Requires --background.")
+        .option("--all", "Run all rows. Requires --background, except with --dry-run, which previews the background run without queueing it.")
         .option("--filter-json <json>", "Row selector filter object or array for background runs. Do not combine with --all, --limit, or --row-id.")
         .option("--formula-values <mode>", "With --filter-json on a formula column, first refresh that selector with `columns run <table> <column> --force` (0 credits), then pass 'materialized'. The run filters the stored snapshot and persists this freshness acknowledgement.")
-        .option("--force", "Run even when the target cell already has a value.")
+        .option("--force", "Run even when the target cell already has a value. Formula columns compute when read, so `tables query` shows their values without a run; a run skips rows that already store a value (existing_value), and --force refreshes them.")
         .option("--connection-id <connection_id>", "Optional provider integration connection id.")
         .option("--background", "Create a durable background run for a free deterministic column. Paid AI/tool/enrichment/custom-HTTP server runs are always backgrounded.")
         .option("--approved", "Confirm a paid durable run, or a bind create-mode run (onNoMatch=create), after inspecting a dry run or preview.")
@@ -7685,18 +8238,27 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
             Boolean(readOption(options.rowId)),
             Boolean(effectiveFilterSelection),
         ].filter(Boolean).length;
-        if (selectedModes > 1) {
-            throw new OxygenError("invalid_selection", "Pass only one of --all, --limit, --row-id, or --filter-json.", {
-                exitCode: 1,
-            });
-        }
-        if (options.all && !options.background) {
-            throw new OxygenError("invalid_column_run", "--all requires --background.", {
-                exitCode: 1,
-            });
-        }
         // skipcq: JS-R1005 — intentional branching for local/background/filter column-run modes
         await handleAsyncAction("columns run", options, async () => {
+            // Selection-shape errors are raised inside the action so --json
+            // callers get the failure envelope, not a bare stack trace.
+            if (selectedModes > 1) {
+                throw new OxygenError("invalid_selection", "Pass only one of --all, --limit, --row-id, or --filter-json.", {
+                    exitCode: 1,
+                });
+            }
+            // A dry run of an all-rows run previews the background run the live
+            // command would create and queues nothing, so demanding --background
+            // for it only teaches a flag with no behavioural basis (blind eval
+            // 2026-09-10: the agent tripped the error, then re-ran with the flag).
+            if (options.all && options.dryRun && !options.background && !options.local) {
+                options.background = true;
+            }
+            if (options.all && !options.background) {
+                throw new OxygenError("invalid_column_run", "--all requires --background.", {
+                    exitCode: 1,
+                });
+            }
             if (options.local) {
                 if (options.background) {
                     throw new OxygenError("invalid_column_run", "Pass either --local or --background, not both.", {
@@ -8093,7 +8655,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
     }));
     program
         .command("table-runs")
-        .description("Durable background table action run commands.")
+        .description("Durable background table action run commands. `list --table <table> --status all` is a table's full run history, including Function runs launched from it; without --status, list shows only active runs.")
         .addCommand(new Command("create")
         .description("Create a durable background run for table tool-column actions. Large runs are accepted immediately and their rows are prepared in the background (execution_status 'planning'); follow with `table-runs wait <run_id>`.")
         .argument("<table>", "Table id or slug.")
@@ -8135,7 +8697,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .addCommand(new Command("list")
         .description("List durable table action runs for one table.")
         .requiredOption("--table <table>", "Table id or slug.")
-        .option("--status <status>", "Filter by active, queued, running, paused, completed, completed_with_errors, failed, canceling, or canceled. Defaults to active.")
+        .option("--status <status>", "Filter by all, active, queued, running, paused, completed, completed_with_errors, failed, canceling, or canceled. Defaults to active; pass all for the full history in one call, including Function runs launched from this table.")
         .option("--limit <n>", "Maximum runs to return. Defaults to 20.")
         .option("--format <format>", "Format run history as json, jsonl, csv, or table (same serializer as `tables export`). Omit to keep the default envelope output.")
         .option("--output <path>", "Write the formatted run history to a file instead of embedding it in the response.")
@@ -8144,14 +8706,14 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         await handleAsyncAction("table-runs list", options, () => listTableRuns(options));
     }))
         .addCommand(new Command("get")
-        .description("Get one durable table action run.")
+        .description("Get one durable table action run. For a Function run, selection.rowIds are rows of the Function's execution table, not the calling table; list the calling table's rows it wrote with `tables query <caller> --filter-tree-json` on the Function column's \"action_run_id\" path.")
         .argument("<run_id>", "Table action run UUID or parent workspace run UUID.")
         .option("--json", "Print a JSON envelope.")
         .action(async (runId, options) => {
         await handleAsyncAction("table-runs get", options, () => requestOxygen(`/api/cli/table-action-runs/${encodeURIComponent(runId)}`));
     }))
         .addCommand(new Command("items")
-        .description("List row items for a durable table action run.")
+        .description("List row items for a durable table action run. For a Function run, list the calling table's rows it wrote with `tables query <caller> --filter-tree-json` on the Function column's \"action_run_id\" path instead of joining items.")
         .argument("<run_id>", "Table action run UUID.")
         .option("--status <status>", "Filter by pending, leased, completed, failed, skipped, or canceled.")
         .option("--limit <n>", "Maximum items to return. Defaults to 100.")
@@ -8538,8 +9100,9 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .addCommand(new Command("search")
         .description("Plan, dry-run, or queue provider-backed company search.")
         .addCommand(new Command("plan")
-        .description("Compile a company-search prompt into ordered provider routes without provider calls.")
-        .requiredOption("--prompt <text-or-file>", "Company-search prompt, or a path to a prompt file.")
+        .description("Compile a company-search prompt into ordered provider routes without provider calls. To turn a list of company NAMES into websites or domains, pass --source-intent url_recovery (e.g. --prompt \"Find the websites for these companies: <names>\" --source-intent url_recovery). The plan carries provider_availability: a route on a benched managed provider reads degraded with a next_action.")
+        .argument("[prompt]", "Prompt text or @file (same as --prompt). The --prompt flag wins if both are given.")
+        .option("--prompt <text-or-file>", "Company-search prompt, or a path to a prompt file.")
         .option("--target-count <n>", "Desired company count. Single-plan ceiling 50,000; larger requests return an explicit clamp warning and segmentation guidance.")
         .option("--source-intent <intent>", "Override detected intent: sizing, structured, lookalike, technology, hiring, local, known_source, concept, web, url, or fallback.")
         .option("--filters-json <json-or-file>", "CompanySearchFilters JSON inline or a @file/path; wins over individual flags per top-level filter path.")
@@ -8557,14 +9120,15 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--estimate", "Run a free server-side preflight pass: resolves provider enums and a free count probe for an estimated match count (zero credits).")
         .option("--materialize-preview", "Create a preview table with route rows.")
         .option("--json", "Print a JSON envelope.")
-        .action(async (options) => {
+        .action(async (promptArg, options) => {
         await handleAsyncAction("companies search plan", options, () => requestOxygen("/api/cli/companies/search/plan", {
             method: "POST",
-            body: readCompaniesSearchPlanBody(options),
+            body: readCompaniesSearchPlanBody(options, promptArg),
         }));
     }))
         .addCommand(new Command("run")
         .description("Return a dry-run request or queue a live company-search ingestion run.")
+        .argument("[prompt]", "Prompt text or @file (same as --prompt). The --prompt flag wins if both are given.")
         .option("--prompt <text-or-file>", "Company-search prompt, or a path to a prompt file.")
         .option("--plan-json <json-or-file>", "Plan JSON returned by companies search plan, or a path to a JSON file.")
         .option("--route-id <id>", "Route id from the plan to execute.")
@@ -8592,10 +9156,10 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--estimate", "Run a free server-side preflight pass when planning from --prompt: resolves provider enums and a free count probe (zero credits).")
         .option("--approved", "Required for live runs after inspecting dry-run output.")
         .option("--json", "Print a JSON envelope.")
-        .action(async (options) => {
+        .action(async (promptArg, options) => {
         await handleAsyncAction("companies search run", options, () => requestOxygen("/api/cli/companies/search/run", {
             method: "POST",
-            body: readCompaniesSearchRunBody(options),
+            body: readCompaniesSearchRunBody(options, promptArg),
         }));
     })))
         .addCommand(new Command("enrich")
@@ -8604,7 +9168,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .description("Inspect missing company fields, provider routing, and credit estimates without provider calls.")
         .argument("<table>", "Table id or slug.")
         .option("--missing-fields <fields>", "Comma-separated fields to fill: domain,linkedin_url,headcount,industry,funding,technologies,hiring_signals,company_profile.")
-        .option("--providers <providers>", "Comma-separated provider order pool. Defaults to blitzapi,crustdata,ai_ark,prospeo,leadmagic.")
+        .option("--providers <providers>", "Comma-separated provider order pool. Defaults to scraper,blitzapi,crustdata,ai_ark,prospeo,leadmagic.")
         .option("--all", "Preview all rows.")
         .option("--limit <n>", "Preview a limited row scope.")
         .option("--row-ids <ids>", "Comma-separated row ids.")
@@ -8869,7 +9433,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         await handleAsyncAction("billing invoices", options, () => requestOxygen("/api/cli/billing/invoices"));
     }))
         .addCommand(new Command("allowance")
-        .description("Show this billing cycle's credit pool as one breakdown: fixed spend, flexible spend, credits committed to the next renewal, and what is free to spend — the numbers behind the bar on the credit-usage page. The parts always sum to the total, with ONE deliberate exception: `renewals_past_due` (and its region=past_due segment) reports renewals that FAILED to charge, which is money not taken and therefore outside total_credits. fixed_spent_credits is what has ALREADY been charged this cycle, NOT your monthly run-rate — for the forward figure billed at the next renewal see `billing commitments`, which is normally much larger. reserved_credits is in-flight spend already carved out of free_to_spend_credits, so treat free_to_spend as the ceiling and free_to_spend minus reserved as what is genuinely uncommitted. Every segment carries region=fixed|flexible. Read-only, 0 Oxygen credits.")
+        .description("Show this billing cycle's credit pool as one breakdown: fixed spend, flexible spend, credits committed to the next renewal, and what is free to spend — the numbers behind the bar on the credit-usage page. The parts always sum to the total, with ONE deliberate exception: `renewals_past_due` (and its region=past_due segment) reports renewals that FAILED to charge, which is money not taken and therefore outside total_credits. fixed_spent_credits is what has ALREADY been charged this cycle, NOT your monthly run-rate — for the forward figure billed at the next renewal see `billing commitments`, which is normally much larger. For organization wallet scope, reserved_credits is in-flight spend already removed from the available balance: do not subtract it again from free_to_spend_credits. Reserved credits can exceed the remaining free balance without implying an overdraft. For workspace_cap scope, free_to_spend_credits is remaining allowance, not the billing owner's wallet; live execution still checks that wallet and spend policies. Every segment carries region=fixed|flexible. Read-only, 0 Oxygen credits.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("billing allowance", options, () => requestOxygen("/api/cli/billing/allowance"));
@@ -9311,6 +9875,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .description("Board of the PRIMARY managed external data providers (enrichment, people/company search, web search, scraping, signals, AI-column web grounding, LLM inference): per provider health probe, 7d traffic, balance, 30d/7d COGS, rate policy, spend ceilings, breaker, and posture, plus the platform runaway guards and how old each snapshot is. Reads the snapshots the crons write; --refresh re-runs those same zero-credit snapshots first. Staff only.")
         .option("--refresh", "Re-run the zero-credit snapshot work the three crons run (provider health probes, managed balances, cost snapshot) before reading the board. No paid provider call and no credit spend; takes up to a few minutes.")
         .option("--stages <csv>", "Limit --refresh to these stages: health, balances, costs. Defaults to all three.")
+        .option("--force", "Refresh even inside the server's cooldown on re-probing every managed vendor. Only with --refresh.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         const stages = readCsvOption(options.stages);
@@ -9320,6 +9885,13 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
             emitCliFailure("admin primary-providers", new OxygenError("invalid_request", "--stages only applies to --refresh. Add --refresh to re-run those snapshots.", { exitCode: 2 }));
             return;
         }
+        if (options.force && !options.refresh) {
+            // Same reason as --stages: --force only relaxes the refresh
+            // cooldown, so on its own it reads the very board the caller
+            // believes it just forced a re-probe of.
+            emitCliFailure("admin primary-providers", new OxygenError("invalid_request", "--force only applies to --refresh. Add --refresh to re-run those snapshots.", { exitCode: 2 }));
+            return;
+        }
         let failed = false;
         const board = await requestOxygen("/api/cli/admin/primary-providers", options.refresh
             ? {
@@ -9330,7 +9902,11 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
                 // finishes — the operator reads a failure for work that
                 // succeeded and re-runs the outbound probes.
                 timeoutMs: 300_000,
-                body: { refresh: true, ...(stages.length > 0 ? { stages } : {}) },
+                body: {
+                    refresh: true,
+                    ...(stages.length > 0 ? { stages } : {}),
+                    ...(options.force ? { force: true } : {}),
+                },
             }
             : undefined).catch((error) => {
             emitCliFailure("admin primary-providers", error);
@@ -9382,9 +9958,9 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         }));
     }))
         .addCommand(new Command("halt")
-        .description("Force a breaker OPEN — the platform kill switch for managed provider spend.")
-        .option("--scope <kind>", "Scope kind to halt. Defaults to global.", "global")
-        .option("--key <key>", "Scope key. Defaults to * (everything in that scope).", "*")
+        .description("Force a breaker OPEN — the platform kill switch for managed provider spend. --scope managed_credit --key <provider> benches Oxygen's managed account for one provider (the same bench a vendor 402 opens).")
+        .option("--scope <kind>", "Scope kind to halt: global, category, provider, organization, signature, or managed_credit (key = provider id). Defaults to global.", "global")
+        .option("--key <key>", "Scope key. Defaults to * (everything in that scope). For --scope managed_credit, the provider id (serper, bounceban, ...).", "*")
         .option("--reason <text>", "Why the halt was applied.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
@@ -9399,9 +9975,9 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         }));
     }))
         .addCommand(new Command("resume")
-        .description("Close a breaker and clear its backoff, resuming managed provider spend.")
-        .option("--scope <kind>", "Scope kind to resume. Defaults to global.", "global")
-        .option("--key <key>", "Scope key. Defaults to *.", "*")
+        .description("Close a breaker and clear its backoff, resuming managed provider spend. After funding a managed provider account, --scope managed_credit --key <provider> closes its credit bench fleet-wide instead of waiting out the window.")
+        .option("--scope <kind>", "Scope kind to resume: global, category, provider, organization, signature, or managed_credit (key = provider id). Defaults to global.", "global")
+        .option("--key <key>", "Scope key. Defaults to *. For --scope managed_credit, the provider id (serper, bounceban, ...).", "*")
         .option("--reason <text>", "Why the breaker was reset.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
@@ -9919,7 +10495,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--per-turn-ceiling <number>", "Legacy compatibility only: accepted and clamped, but does not cap an attended turn.")
         .option("--journey <slug>", "Optional journey slug to seed the session's goal and context.")
         .option("--title <text>", "Optional human title for the session.")
-        .option("--auto-approve", "Start with auto-approve ON for paid, workspace-internal actions (cards are still created and decided automatically within each action's credit cap). External sends, enrollments, publishes, DNS, and external CRM pushes always stay human-gated.")
+        .option("--auto-approve", "Start with auto-approve ON for paid, workspace-internal actions (cards are still created and decided automatically within each action's credit cap). External sends, sequence starts, publishes, DNS, and external CRM pushes always stay human-gated.")
         .option("--no-follow", "Start with screen-follow OFF. On by default: while the session is open in the browser, your screen opens onto whatever the copilot creates or changes, with the live session docked beside it. Change it later with `copilot follow`.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
@@ -10455,11 +11031,20 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--return <mode>", "Legacy response shape: raw, compact, or summary. Defaults to raw.")
         .option("--return-mode <mode>", "Response shape: raw, compact, or summary. Prefer summary for large search responses.")
         .option("--oxygen-cursor <cursor>", "Short Oxygen cursor returned as oxygen_next_cursor by a previous tool run.")
-        .option("--max-credits <n>", "Credit ceiling for live paid tools; not needed for no-bill tools.")
+        .option("--max-credits <n>", "Credit ceiling for live paid tools; not needed for no-bill tools, and 0 is accepted for no-bill operations.")
         .option("--approved", "Required for live paid tools and external writes after inspecting dry-run output.")
         .option("--json", "Print a JSON envelope.")
         .action(async (toolId, options) => {
-        const maxCredits = readPositiveNumber(options.maxCredits);
+        // Zero is a real ceiling here, not a typo: /api/cli/tools/run only
+        // demands a positive max_credits for BILLED tools, so a documented
+        // no-bill operation is legitimately run with --max-credits 0. The
+        // positive-only reader rejected that locally, before the request.
+        //
+        // Non-negative NUMBER, not readPositiveNumberOrZero (a whole seat
+        // count): this command's own dry-run hint prints "--max-credits
+        // 24.94", so an integer reader would refuse the very command the CLI
+        // just told the operator to run.
+        const maxCredits = readNonNegativeNumber(options.maxCredits);
         await handleAsyncAction("tools run", options, () => requestOxygen("/api/cli/tools/run", {
             method: "POST",
             body: {
@@ -10502,7 +11087,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--email-pattern-validation <mode>", "Work-email pattern pre-step: leadmagic_valid_only or disabled.")
         .option("--phone-waterfall-profile <profile>", "Phone waterfall profile: auto (input-aware), linkedin_url, email, or name_domain. Auto picks the cheapest cost-ordered provider set for each row's inputs (mobile match rate ~30-60%).")
         .option("--verify-phone", "Validate found phone numbers with ClearoutPhone (adds phone_line_type + phone_carrier; filter phone_line_type=mobile for mobile-only).")
-        .option("--allow-premium-lanes", "Opt in to premium high-cost lanes (e.g. >25cr/row phone reveal). Off by default: premium lanes are skipped so an unattended run can't bill-shock.")
+        .option("--allow-premium-lanes", "Opt in to managed lanes billing over 500 credits per call. Only linkedin_url has one (LeadMagic email_to_profile, 1225cr); it is off by default so an unattended run can't bill-shock. No effect on mobile_phone, work_email or verify_email.")
         .option("--phone-verification-credential-mode <mode>", "ClearoutPhone credential mode for phone verification: managed or user_api_key.")
         .option("--limit <n>", "Rows to estimate. Defaults to 10.")
         .option("--all", "Estimate all rows.")
@@ -10537,7 +11122,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--email-pattern-validation <mode>", "Work-email pattern pre-step: leadmagic_valid_only or disabled.")
         .option("--phone-waterfall-profile <profile>", "Phone waterfall profile: auto (input-aware), linkedin_url, email, or name_domain. Auto picks the cheapest cost-ordered provider set for each row's inputs (mobile match rate ~30-60%).")
         .option("--verify-phone", "Validate found phone numbers with ClearoutPhone (adds phone_line_type + phone_carrier; filter phone_line_type=mobile for mobile-only).")
-        .option("--allow-premium-lanes", "Opt in to premium high-cost lanes (e.g. >25cr/row phone reveal). Off by default: premium lanes are skipped so an unattended run can't bill-shock.")
+        .option("--allow-premium-lanes", "Opt in to managed lanes billing over 500 credits per call. Only linkedin_url has one (LeadMagic email_to_profile, 1225cr); it is off by default so an unattended run can't bill-shock. No effect on mobile_phone, work_email or verify_email.")
         .option("--phone-verification-credential-mode <mode>", "ClearoutPhone credential mode for phone verification: managed or user_api_key.")
         .option("--limit <n>", "Rows to queue.")
         .option("--all", "Queue all rows.")
@@ -10573,7 +11158,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--company-domain <domain>", "Company apex domain, e.g. acme.com.")
         .option("--company-name <name>", "Company name.")
         .option("--mode <mode>", "dry_run (default) previews the plan and spends nothing; live spends credits and returns the answer.")
-        .option("--max-credits <credits>", "Spend ceiling. Required for --mode live.")
+        .option("--max-credits <credits>", "Spend ceiling. Required for --mode live. Run the free dry_run first: it returns estimate.recommended_max_credits, the ceiling that lets the WHOLE resolved waterfall run, plus estimate.min_credits and a per-leg breakdown. When the resolved chain runs the guessed-address pass (the name+domain and first/last+domain profiles, not the LinkedIn-URL one) the block also carries estimate.pattern_guess_verification_credits — the verification checks that pass bills before any named provider is dialled. A lower ceiling does NOT stop the run: each lane priced above what is left of it is refused on its own (spend_cap_too_low) and the waterfall advances, so a cheaper lane further down the chain can still run and bill.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("find email", options, () => requestOxygen("/api/cli/find/run", { method: "POST", body: buildFindBody("email", options) }));
@@ -10587,7 +11172,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--company-name <name>", "Company name.")
         .option("--verify", "Verify the found number with ClearoutPhone — adds line_type/carrier and keeps the number on a non-verdict (only a genuine 'not valid' is discarded).")
         .option("--mode <mode>", "dry_run (default) previews the plan and spends nothing; live spends credits and returns the answer.")
-        .option("--max-credits <credits>", "Spend ceiling. Required for --mode live.")
+        .option("--max-credits <credits>", "Spend ceiling. Required for --mode live. Run the free dry_run first: it returns estimate.recommended_max_credits, the ceiling that lets the WHOLE resolved waterfall run, plus estimate.min_credits and a per-leg breakdown. A lower ceiling does NOT stop the run: each lane priced above what is left of it is refused on its own (spend_cap_too_low) and the waterfall advances, so a cheaper lane further down the chain can still run and bill.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("find phone", options, () => requestOxygen("/api/cli/find/run", { method: "POST", body: buildFindBody("phone", options) }));
@@ -10600,7 +11185,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--company-name <name>", "Company name.")
         .option("--company-linkedin-url <url>", "Company LinkedIn URL.")
         .option("--mode <mode>", "dry_run (default) previews the plan and spends nothing; live spends credits and returns the answer.")
-        .option("--max-credits <credits>", "Spend ceiling. Required for --mode live.")
+        .option("--max-credits <credits>", "Spend ceiling. Required for --mode live. Run the free dry_run first: it returns estimate.recommended_max_credits, the ceiling that lets the WHOLE resolved waterfall run, plus estimate.min_credits and a per-leg breakdown. A lower ceiling does NOT stop the run: each lane priced above what is left of it is refused on its own (spend_cap_too_low) and the waterfall advances, so a cheaper lane further down the chain can still run and bill.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("find linkedin", options, () => requestOxygen("/api/cli/find/run", { method: "POST", body: buildFindBody("linkedin", options) }));
@@ -10612,7 +11197,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--linkedin-url <url>", "Company LinkedIn URL.")
         .option("--fields <fields>", "Comma-separated company fields. Defaults to domain,linkedin_url,headcount,industry.")
         .option("--mode <mode>", "dry_run (default) previews the plan and spends nothing; live spends credits and returns the answer.")
-        .option("--max-credits <credits>", "Spend ceiling. Required for --mode live.")
+        .option("--max-credits <credits>", "Spend ceiling. Required for --mode live; 0 runs only the zero-credit lanes (the priced lanes are skipped as credit_ceiling_reached). Run the free dry_run first: it returns estimate.recommended_max_credits, the ceiling that funds every lane in the plan, and estimate.min_credits, what the plan costs if each field is answered by its first lane.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("find company", options, () => requestOxygen("/api/cli/find/run", { method: "POST", body: buildFindBody("company", options) }));
@@ -10621,11 +11206,11 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .command("verify")
         .description("Check whether emails you already have are safe to send to. dry_run previews the provider chain for free; live spends and needs --max-credits.")
         .addCommand(new Command("email")
-        .description("Verify one or more email addresses. MillionVerifier answers first; addresses on catch-all (accept-all) domains, which it can only flag as risky, escalate automatically to BounceBan to get a real answer. Returns valid / invalid / catch_all / unknown per address.")
+        .description("Verify one or more email addresses. MillionVerifier answers first; eligible catch-all (accept-all) addresses escalate to BounceBan when available. Returns valid / invalid / catch_all / unknown per address. If escalation cannot run, catch_all stays unconfirmed; escalation_unavailable_reason and next_action explain why. On the managed lane, Oxygen staff own dry provider balances, credential repair and hold release; workspace credits do not fix those blockers. A free preview reports an availability snapshot, not guaranteed live readiness. See https://oxygen-agent.com/docs/providers/email-verification and the oxygen-gtm MillionVerifier/BounceBan provider runbooks.")
         .argument("<emails...>", "One or more email addresses to verify.")
         .option("--mode <mode>", "dry_run (default) previews the plan and spends nothing; live spends credits and returns the answer.")
         .option("--approved", "Same as --mode live. Accepted because the global help footer names --approved as the way to authorize a credit-spending command.")
-        .option("--max-credits <credits>", "Spend ceiling for the whole run. Required for --mode live. Run the free dry_run first — it returns estimate.recommended_max_credits, the value that guarantees every catch-all address still gets escalated.")
+        .option("--max-credits <credits>", "Spend ceiling for the whole run. Required for --mode live. The free dry_run returns estimate.recommended_max_credits, which covers the estimated maximum subject to live provider availability and eligibility; it is a ceiling, not a charge or a guaranteed verdict. Re-verifying the exact same address in this workspace replays MillionVerifier's first pass free for up to 30 days, so a repeat run can report credits_used 0 — catch-all escalation is never cached, and its reservation is released in full when that call returns no verdict.")
         .option("--json", "Print a JSON envelope.")
         .action(async (emails, options) => {
         await handleAsyncAction("verify email", options, () => requestOxygen("/api/cli/verify/run", {
@@ -10658,6 +11243,102 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
             },
         }));
     }));
+    program
+        .command("supabase")
+        .description("Connect a read-only Supabase database and import selected base tables into durable Oxygen Tables. Catalog, preview, import, status, cancel, and retry all consume 0 credits; imports never write to Supabase.")
+        .addCommand(new Command("connect")
+        .description("Validate and encrypt a managed Supabase PostgreSQL URL. The database role must be read-only; Oxygen refuses writable credentials. Read the URL from stdin to keep it out of shell history and process arguments. Run `oxygen integrations connect supabase --json` first for copyable role setup SQL and the secure web path.")
+        .requiredOption("--database-url-stdin", "Read the Supabase PostgreSQL URL from stdin.")
+        .option("--schemas <schemas>", "Comma-separated user schemas (default: public). Managed/system schemas are refused.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("supabase connect", options, () => {
+            if (options.databaseUrlStdin !== true)
+                throw new Error("--database-url-stdin is required.");
+            const databaseUrl = readFileSync(0, "utf8").trim();
+            if (!databaseUrl)
+                throw new Error("No Supabase database URL was provided on stdin.");
+            return requestOxygen("/api/cli/integrations/connect", {
+                method: "POST",
+                body: {
+                    integration_id: "supabase",
+                    database_url: databaseUrl,
+                    ...(readOption(options.schemas) ? { schemas: readOption(options.schemas) } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("catalog")
+        .description("Inspect readable base tables, columns, PostgreSQL types, primary keys, and estimated rows through the saved read-only connection.")
+        .option("--connection-id <id>", "Use a specific Supabase connection; defaults to the active default.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("supabase catalog", options, () => requestOxygen("/api/cli/supabase/catalog", {
+            method: "POST",
+            body: readOption(options.connectionId) ? { connection_id: readOption(options.connectionId) } : {},
+        }));
+    }))
+        .addCommand(new Command("plan")
+        .description("Preview exact Oxygen Table creates/refreshes, row-limit posture, deletion semantics, and the schema fingerprint required to start. No writes and 0 credits.")
+        .option("--connection-id <id>", "Use a specific Supabase connection.")
+        .option("--tables <schema.tables>", "Comma-separated schema.table names; at most 50 per import. Omit to preview every readable table.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("supabase imports plan", options, () => {
+            const tables = parseSupabaseTableSelection(options.tables);
+            return requestOxygen("/api/cli/supabase/imports/plan", {
+                method: "POST",
+                body: {
+                    ...(readOption(options.connectionId) ? { connection_id: readOption(options.connectionId) } : {}),
+                    ...(tables ? { tables } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("import")
+        .description("Start the previously previewed snapshot/refresh as durable Postgres-backed work. Creates one Oxygen Table per new source; refreshes primary-keyed sources in place and marks missing source rows instead of deleting them. Consumes 0 credits.")
+        .requiredOption("--tables <schema.tables>", "Comma-separated schema.table names from the plan; at most 50 per import.")
+        .requiredOption("--catalog-fingerprint <sha256>", "Fingerprint returned by the latest plan; prevents importing against a changed schema.")
+        .option("--connection-id <id>", "Use a specific Supabase connection.")
+        .option("--project <id-or-slug>", "Create new Oxygen Tables in this project/folder.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("supabase imports start", options, () => {
+            const tables = parseSupabaseTableSelection(options.tables);
+            if (!tables)
+                throw new Error("--tables is required.");
+            return requestOxygen("/api/cli/supabase/imports", {
+                method: "POST",
+                body: {
+                    tables,
+                    catalog_fingerprint: readOption(options.catalogFingerprint),
+                    ...(readOption(options.connectionId) ? { connection_id: readOption(options.connectionId) } : {}),
+                    ...(readOption(options.project) ? { project: readOption(options.project) } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("get")
+        .description("Get aggregate and per-table status, row counts, failures, and deep-links for a Supabase import.")
+        .argument("<import_id>", "Supabase import id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (importId, options) => {
+        await handleAsyncAction("supabase imports get", options, () => requestOxygen(`/api/cli/supabase/imports/${encodeURIComponent(importId)}`));
+    }))
+        .addCommand(new Command("cancel")
+        .description("Request cancellation of every still-active child table run in an import.")
+        .argument("<import_id>", "Supabase import id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (importId, options) => {
+        await handleAsyncAction("supabase imports cancel", options, () => requestOxygen(`/api/cli/supabase/imports/${encodeURIComponent(importId)}/cancel`, { method: "POST", body: {} }));
+    }))
+        .addCommand(new Command("retry")
+        .description("Retry failed child table items without duplicating already-upserted source rows.")
+        .argument("<import_id>", "Supabase import id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (importId, options) => {
+        await handleAsyncAction("supabase imports retry", options, () => requestOxygen(`/api/cli/supabase/imports/${encodeURIComponent(importId)}/retry`, { method: "POST", body: {} }));
+    }));
     program
         .command("integrations")
         .description("Connect third-party tools such as PostHog, Slack, and HubSpot, and manage raw provider-webhook subscriptions. Start with `integrations list` to confirm any provider is supported, see its auth mode, and distinguish free connection setup from per-action credit estimates. Trigger-ready workspace events live under `workflows events list`. Local mailbox exports use `mailboxes import`, not this group.")
@@ -10763,7 +11444,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         await handleAsyncAction("integrations list", options, () => requestOxygen("/api/cli/integrations/composio/list"));
     }))
         .addCommand(new Command("connect")
-        .description("Connect an integration. OAuth toolkits return a redirect URL; API-key integrations accept --api-key. Run without credentials first for a 0-credit preview of the provider's exact fields (mode: needs_api_key): no credential is submitted, nothing is stored, and no provider call is made. Use repeatable --credential name=value when a provider also requires a host, subdomain, or other named value. To keep a secret out of shell history and process arguments, open the preview's web_url and submit it in Connections; --api-key is for controlled noninteractive use. Credential submission creates or replaces the connection immediately and needs no separate --approved flag. LinkedIn and WhatsApp return a Unipile hosted-auth URL instead (`oxygen senders connect` / `oxygen whatsapp connect` are the canonical paths).")
+        .description("Connect an integration. OAuth toolkits return a redirect URL, which grants nothing until you approve access on the provider's page; API-key integrations accept --api-key. Run without credentials first for a 0-credit preview of the provider's exact fields (mode: needs_api_key): no credential is submitted, nothing is stored, and no provider call is made. Use repeatable --credential name=value when a provider also requires a host, subdomain, or other named value. To keep a secret out of shell history and process arguments, open the preview's web_url and submit it in Connections; --api-key is for controlled noninteractive use. Credential submission creates or replaces the connection immediately and needs no separate --approved flag. LinkedIn and WhatsApp return a Unipile hosted-auth URL instead (`oxygen senders connect` / `oxygen whatsapp connect` are the canonical paths).")
         .argument("<integration_id>", "Integration id, such as 'slack' or 'serpapi'.")
         .option("--api-key <value>", "API key for controlled noninteractive use. Literal values can appear in shell history and process arguments; prefer the preview web_url for manual entry.")
         .option("--credential <name=value>", "Named provider credential field. Repeat for multi-field integrations (for example, PostHog: --credential subdomain=us).", collectRepeatable, [])
@@ -10885,7 +11566,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }));
     program.addCommand(new Command("senders")
-        .description("Manage the org's connected LinkedIn sender accounts for Sequencer: list, connect, sync, get details, disconnect, and tune rate limits.")
+        .description("Manage the org's connected LinkedIn sender accounts for Sequencer: list, connect, sync, get details, disconnect, and tune rate limits. This group is LinkedIn/WhatsApp accounts only; the cross-channel identity (one person's name and photo) that owns inboxes as well is `oxygen senders profiles`.")
         .addCommand(new Command("list")
         .description("List connected LinkedIn sender accounts with health status, rate limits, and today's usage.")
         .option("--status <status>", "Filter by sender status: active, paused, disconnected, restricted, or credentials_required.")
@@ -11103,7 +11784,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     })))
         .addCommand(new Command("profiles")
-        .description("Sender profiles: group a person's LinkedIn + WhatsApp senders and email inboxes into one sending identity — one name, one first/last name, one photo. A sequence can then send every channel from the same persona, and `oxygen managed-inboxes subscribe/add-inboxes --sender <id>` orders new mailboxes under that identity instead of making you retype it per mailbox. Manage: list, get, create, update, set-photo, attach/detach accounts, delete.")
+        .description("Sender profiles: group a person's LinkedIn + WhatsApp senders and email inboxes into one sending identity — one name, one first/last name, one photo. A sequence can then send every channel from the same persona, and `oxygen managed-inboxes subscribe/add-inboxes --sender <id>` orders new mailboxes under that identity instead of making you retype it per mailbox. Every email inbox always belongs to one of these profiles, so attaching moves an inbox and detaching one is refused. Manage: list, get, create, update, set-photo, attach/detach accounts, delete.")
         .addCommand(new Command("list")
         .description("List sender profiles with their per-channel account counts (LinkedIn / WhatsApp / inboxes).")
         .option("--status <status>", "Filter by status: active, paused, or archived.")
@@ -11141,14 +11822,14 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         await handleAsyncAction("senders profiles get", options, () => requestOxygen(`/api/cli/senders/profiles/${encodeURIComponent(id)}`));
     }))
         .addCommand(new Command("create")
-        .description("Create a sender profile: one person's sending identity — their LinkedIn/WhatsApp senders and email inboxes under one name and photo. --from-linkedin seeds the name + avatar from a LinkedIn account and attaches it; then assign inboxes and WhatsApp with --mailboxes / --senders. Without --from-linkedin, --name is required. Give the profile --first-name and --last-name too: those are the exact names the inbox vendor stamps when you order mailboxes with `oxygen managed-inboxes subscribe --sender <id>`, and the vendor has no way to change a name after provisioning.")
+        .description("Create a sender profile: one person's sending identity — their LinkedIn/WhatsApp senders and email inboxes under one name and photo. --from-linkedin seeds the name + avatar from a LinkedIn account and attaches it; then assign inboxes and WhatsApp with --mailboxes / --senders. Without --from-linkedin, --name is required. Give the profile --first-name and --last-name too: those are the exact names the inbox vendor stamps when you order mailboxes with `oxygen managed-inboxes subscribe --sender <id>`, and the vendor has no way to change a name after provisioning. Attaching a LinkedIn sender (--from-linkedin or --senders) gives the profile that account's LinkedIn photo, mirrored into Oxygen storage, unless you pass --avatar-url; a photo you upload later with set-photo --file always wins over the LinkedIn one.")
         .option("--name <name>", "Display name for the profile. Optional when --from-linkedin is given (derived from the LinkedIn account).")
         .option("--first-name <name>", "The person's first name, as it should appear on mailboxes ordered for this sender. Defaults to splitting --name / the LinkedIn name on the first space.")
         .option("--last-name <name>", "The person's last name, as it should appear on mailboxes ordered for this sender. Ordering managed inboxes for this sender needs both names; a one-word name leaves it blank and the order is refused rather than guessed.")
         .option("--from-linkedin <senderId>", "Seed the profile from this LinkedIn/WhatsApp sender account id: derives the name and MIRRORS the LinkedIn photo into Oxygen storage (LinkedIn's own URL expires, so a mirrored copy is what an inbox vendor can still fetch hours later) and attaches the account.")
         .option("--avatar-url <url>", "Use this image URL as the profile photo instead of the LinkedIn one. Must be a public https URL. An expiring link (e.g. media.licdn.com with e=<epoch>) is stored but marked non-durable and is NOT sent to an inbox vendor — use `set-photo --file` to host a permanent copy.")
         .option("--status <status>", "Initial status: active (default), paused, or archived.")
-        .option("--senders <ids>", "Comma-separated sender account ids (LinkedIn/WhatsApp) to attach.")
+        .option("--senders <ids>", "Comma-separated sender account ids (LinkedIn/WhatsApp) to attach. A LinkedIn sender also supplies the profile's photo when it has none of its own.")
         .option("--mailboxes <ids>", "Comma-separated email mailbox ids to attach.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
@@ -11188,12 +11869,12 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         }));
     }))
         .addCommand(new Command("set-photo")
-        .description("Set the reusable sender identity's profile picture for FUTURE managed-inbox orders made with --sender <id>. Pick exactly one source: --file (upload your own image; Oxygen hosts it permanently), --url (a public https image), --from-linkedin (re-mirror the photo from the attached LinkedIn account), or --clear. Hosting matters: an inbox vendor fetches the photo HOURS after an order, so an expiring LinkedIn CDN URL can ship the mailbox faceless. This updates Oxygen's sender profile only: it does not change already-provisioned mailbox photos or call the inbox provider. For a one-off typed-name order using profile_picture_url in --mailboxes JSON, use `oxygen managed-inboxes upload-avatar <path>` instead. Free — no credits.")
+        .description("Set the reusable sender identity's profile picture for FUTURE managed-inbox orders made with --sender <id>. Pick exactly one source: --file (upload your own image; Oxygen hosts it permanently), --url (a public https image), --from-linkedin (re-mirror the photo from the attached LinkedIn account), or --clear. Hosting matters: an inbox vendor fetches the photo HOURS after an order, so an expiring LinkedIn CDN URL can ship the mailbox faceless. This updates Oxygen's sender profile only: it does not change already-provisioned mailbox photos or call the inbox provider. For a one-off typed-name order using profile_picture_url in --mailboxes JSON, use `oxygen managed-inboxes upload-avatar <path>` instead. Precedence: a photo you upload (--file) or set with --url is yours and is never overwritten by Oxygen; a sender with a LinkedIn account attached and no photo of its own gets that LinkedIn photo automatically (existing senders are backfilled), so --clear on such a sender is temporary — upload your own photo to override LinkedIn's. If LinkedIn's CDN refuses the stored picture, Oxygen re-syncs the account and retries once; read back avatar_durable, where false means only an expiring link could be kept. Free — no credits.")
         .argument("<id>", "Sender profile id (from `oxygen senders profiles list`).")
         .option("--file <path>", "Upload a PNG, JPEG, or WebP from disk (max 8MB) and use it. Oxygen hosts the image permanently, so an inbox vendor can still fetch it at provisioning time.")
         .option("--url <url>", "Use an image already published at a public https URL. If the link expires (e.g. media.licdn.com with e=<epoch>) the photo is kept for Oxygen's own UI but marked non-durable and NEVER sent to an inbox vendor.")
-        .option("--from-linkedin", "Re-mirror the photo from this profile's attached LinkedIn account into Oxygen storage. Use it when the person changed their LinkedIn picture.")
-        .option("--clear", "Remove the photo. Mailboxes ordered afterwards ship without one.")
+        .option("--from-linkedin", "Re-mirror the photo from this profile's attached LinkedIn account into Oxygen storage. Use it when the person changed their LinkedIn picture. If the CDN refuses the stored picture, the account is re-synced and the mirror retried once; when it still fails, the expiring link is kept, avatar_durable reads false, and the worker retries later.")
+        .option("--clear", "Remove the photo. Mailboxes ordered afterwards ship without one. On a sender with a LinkedIn account attached this is temporary — the LinkedIn photo is adopted again on the next sync; upload your own photo to override it instead.")
         .option("--json", "Print a JSON envelope.")
         .action(async (id, options) => {
         await handleAsyncAction("senders profiles set-photo", options, async () => {
@@ -11233,9 +11914,9 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("attach")
-        .description("Attach senders and/or inboxes to a profile. An account belongs to one profile at a time — attaching moves it.")
+        .description("Attach senders and/or inboxes to a profile. An account belongs to one profile at a time — attaching moves it. Attaching a LinkedIn sender to a profile without a photo of its own gives it that account's LinkedIn photo (mirrored into Oxygen storage); an uploaded or URL-set photo is never replaced. Read back has_photo and avatar_durable in the result.")
         .argument("<id>", "Sender profile id.")
-        .option("--senders <ids>", "Comma-separated sender account ids (LinkedIn/WhatsApp) to attach.")
+        .option("--senders <ids>", "Comma-separated sender account ids (LinkedIn/WhatsApp) to attach. A LinkedIn sender also supplies the profile's photo when it has none of its own.")
         .option("--mailboxes <ids>", "Comma-separated email mailbox ids to attach.")
         .option("--json", "Print a JSON envelope.")
         .action(async (id, options) => {
@@ -11248,7 +11929,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         }));
     }))
         .addCommand(new Command("detach")
-        .description("Detach senders and/or inboxes from a profile, returning them to the unassigned pool.")
+        .description("Detach LinkedIn/WhatsApp senders from a profile, returning them to the unassigned pool. --mailboxes is refused: an email inbox always belongs to a sender, so there is no unassigned pool for it — move it with `senders profiles attach <other-profile> --mailboxes <id>`, which reassigns it.")
         .argument("<id>", "Sender profile id.")
         .option("--senders <ids>", "Comma-separated sender account ids to detach.")
         .option("--mailboxes <ids>", "Comma-separated email mailbox ids to detach.")
@@ -11263,7 +11944,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         }));
     }))
         .addCommand(new Command("delete")
-        .description("Delete a sender profile. Its accounts detach (return to the pool); they are never deleted.")
+        .description("Delete a sender profile. Refused while the profile still owns inboxes — move them to another profile first; LinkedIn/WhatsApp accounts detach (return to the pool) and are never deleted.")
         .argument("<id>", "Sender profile id.")
         .option("--json", "Print a JSON envelope.")
         .action(async (id, options) => {
@@ -11473,7 +12154,46 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     })));
     program.addCommand(new Command("engagement")
-        .description("Capture LinkedIn intent from one known post (harvest needs its public URL or the composite social_id from `oxygen posts get`), and react or comment on it. Recurring capture — a post's engagers on a cadence, 'who viewed my profile', new followers, new connections — is a live table: arm it with `oxygen linkedin intent setup` and operate it with `oxygen feeds list|pause|resume|run`. For recurring competitor-profile monitoring that discovers future posts, start with `oxygen recipes list competitor --json`. Harvests run as a slow, durable drip under a conservative read budget.")
+        .description("Capture LinkedIn intent from one known post (harvest needs its public URL or the composite social_id from `oxygen posts get`), and react or comment on it. Recurring capture — a post's engagers on a cadence, 'who viewed my profile', new followers, new connections — is a live table: arm it with `oxygen linkedin intent setup` and operate it with `oxygen feeds list|pause|resume|run`. For daily monitoring across profiles and their recent post engagers, start with `oxygen tables watcher preview --help` (free credit review; one editable table). Harvests run as a slow, durable drip under a conservative read budget.")
+        .addCommand(new Command("engagers")
+        .description("Read one post's reactors and commenters right now as a de-duplicated people list ready to enroll. Pages both sources up to --max-pages (default 5, max 20) x 100 per page; `truncated: true` in the envelope means a cap stopped a source that still had more — raise --max-pages, or use `oxygen engagement harvest` for a post too big to read in one request. Nothing is sent and no credits are spent, but every page is one LinkedIn read against the sender account. --post is the composite social_id from `oxygen posts get` (NOT the activity URN).")
+        .requiredOption("--post <social_id>", "Composite post social_id from `oxygen posts get` (NOT the activity URN).")
+        .option("--account <ref>", "Sender account that reads (sender id, connection id, or Unipile account id). Omit for the org default.")
+        .option("--limit <n>", "Engagers per PAGE (default 100, which is also the provider maximum). Per source you get --limit x --max-pages.")
+        .option("--max-pages <n>", "Pages to walk per source, 1-20 (default 5, so 500 reactors + 500 commenters).")
+        .option("--no-reactions", "Skip reactors.")
+        .option("--no-comments", "Skip commenters.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("engagement engagers", options, async () => {
+            const post = readOption(options.post);
+            if (!post)
+                throw new Error("--post is required (the composite social_id from `oxygen posts get`).");
+            const account = readOption(options.account);
+            const limit = readPositiveInteger(options.limit);
+            const maxPages = readPositiveInteger(options.maxPages);
+            const params = new URLSearchParams({ post });
+            if (account)
+                params.set("account", account);
+            if (limit !== undefined)
+                params.set("limit", String(limit));
+            // Forwarded as-is: the route owns the 1-20 range so an
+            // out-of-range value fails loudly instead of silently reading
+            // fewer pages than the caller asked for.
+            if (maxPages !== undefined)
+                params.set("max_pages", String(maxPages));
+            if (options.reactions === false)
+                params.set("include_reactions", "false");
+            if (options.comments === false)
+                params.set("include_comments", "false");
+            const data = await requestOxygen(`/api/cli/linkedin/engagement?${params.toString()}`);
+            // Ahead of the payload, and only for a human: a machine caller
+            // reads truncated/partial_reason off the envelope itself.
+            if (!options.json)
+                writeEngagersReceipt(data);
+            return data;
+        });
+    }))
         .addCommand(new Command("harvest")
         .description("Start (or re-arm) a harvest of a post's engagers into a workspace table you can enroll into a sequence. Engagers drip into the table over many ticks; poll `engagement status` to watch it fill. No messages are sent. Cookieless harvests spend Oxygen credits per scraper page and require --max-credits.")
         .requiredOption("--post <social_id_or_url>", "Composite post social_id from `oxygen posts get` (NOT the activity URN), or the public LinkedIn post URL for cookieless.")
@@ -11613,7 +12333,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("status")
-        .description("Show the canonical intent tables, their linked-table deep-links, and the capture feeds filling them.")
+        .description("Show the canonical intent tables, their linked-table deep-links, and the capture feeds filling them. Workspace-wide: it lists every sender's captures and takes no --account; filter by the sender_account_id on each capture instead.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("linkedin intent status", options, () => requestOxygen("/api/cli/linkedin/intent"));
@@ -11624,7 +12344,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         // cycle. One verb carrying both postures would make the safe default
         // ambiguous on the surface a founder reads first.
         .addCommand(new Command("autoenroll")
-        .description("Authorize the captures armed by `linkedin intent setup` to enroll the people they capture into a sequence — the step that turns captured rows into outreach. PREVIEWS BY DEFAULT and writes nothing: it prints the resolved sender and its effective daily caps, the sequence, per-capture create-vs-patch, the live audience split (already 1st-degree / needs an invite / suppressed / already owned by another sender), the resolved spend + enroll caps and where each came from, and a 7-day send forecast. Re-run with --approved to arm a STANDING grant: every later cycle enrolls newly captured people under those caps without asking again, including people you have never seen. This play is a drip, not a blast — a connections import walks LinkedIn on a metered budget (15 relations reads a day by default, ~50 people a read), so a real network lands over days, and a sender on the warm-up ramp is floored at 5 invites and 5 messages a day for its first three days no matter what caps you set. Revoke at any time with `--disable`.")
+        .description("Authorize the captures armed by `linkedin intent setup` to enroll the people they capture into a sequence — the step that turns captured rows into outreach. PREVIEWS BY DEFAULT and writes nothing: it prints the resolved sender and its effective daily caps, the sequence, per-capture create-vs-patch, the live audience split (already 1st-degree / needs an invite / suppressed / already owned by another sender, and — while a capture still baselines — how many are recorded rather than contacted), anything that would make --approved fail before it writes, the resolved spend + enroll caps and where each came from, and a 7-day send forecast. Re-run with --approved to arm a STANDING grant: every later cycle enrolls newly captured people under those caps without asking again, including people you have never seen. This play is a drip, not a blast — a connections import walks LinkedIn on a metered budget (15 relations reads a day by default, ~50 people a read), so a real network lands over days, and a sender on the warm-up ramp is floored at 5 invites and 5 messages a day for its first three days no matter what caps you set. Revoke at any time with `--disable`.")
         .requiredOption("--account <ref>", "Connected LinkedIn sender whose captures are authorized (sender id, connection id, or Unipile account id).")
         .option("--sequence <ref>", "Sequence (id or slug) the captured people are enrolled into. Required to arm: a standing grant has to name the journey it puts people in.")
         .option("--kinds <csv>", "Captures to authorize: connections, followers, profile_viewers, own_posts, post. Defaults to every capture `linkedin intent setup` already provisioned for this sender; naming a kind it never provisioned creates that capture.")
@@ -11973,7 +12693,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--domain <domains>", "Email only: comma-separated counterpart domains to include.")
         .option("--exclude-domain <domains>", "Email only: comma-separated counterpart domains to exclude.")
         .option("--mailbox-id <ids>", "Email only: comma-separated mailbox ids.")
-        .option("--search <text>", "Filter by attendee name or last-message text. Cross-channel.")
+        .option("--search <text>", "Fuzzy search (typos, word order, prefixes) over names, addresses, subjects and the text of every message in EVERY non-warmup conversation: all channels unless --channel narrows, archived and sent-only threads included. --segment, --unanswered and the Primary tab's negative-tier exclusion are ignored while set; explicit facets such as --status still narrow.")
         .option("--include-archived", "Include archived conversations.")
         .option("--limit <n>", "Maximum conversations to return (1-200). Defaults to 50.")
         .option("--cursor <cursor>", "channel=all only: the previous page's next_cursor — resumes the merged stream after that row.")
@@ -12102,7 +12822,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--sender-account-id <ids>", "DMs only: comma-separated LinkedIn/WhatsApp sender account ids.")
         .option("--since <iso>", "Only conversations whose last message is on/after this ISO date/timestamp. Cross-channel.")
         .option("--until <iso>", "Only conversations whose last message is on/before this ISO date/timestamp. Cross-channel.")
-        .option("--search <text>", "Filter by attendee name or last-message text. Cross-channel.")
+        .option("--search <text>", "Fuzzy search (typos, word order, prefixes) over names, addresses, subjects and the text of every message in EVERY non-warmup conversation: all channels unless --channel narrows, archived and sent-only threads included. --segment, --unanswered and the Primary tab's negative-tier exclusion are ignored while set; explicit facets such as --status still narrow.")
         .option("--include-archived", "Also mark archived conversations read.")
         .option("--unanswered", "Only sweep conversations awaiting your reply (the last message is inbound) — the same filter as `inbox list --unanswered`, so the scope is exactly that list.")
         .option("--yes", "Apply the sweep. Without this flag, returns a preview of the unread count only.")
@@ -12882,6 +13602,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--max-new-enrollments-per-day <n>", "Daily drip cap on NEW first-touch leads the planner starts (positive integer).")
         .option("--sequence-prioritization <mode>", "Under a tight daily budget, serve 'followups' or 'new_leads' first.")
         .option("--esp-matching <mode>", "Native-email ESP matching: 'prefer' (DEFAULT) biases toward a mailbox on the recipient's own provider, falling back to any; 'off' rotates mailboxes freely; 'strict' requires a same-provider mailbox and defers the send when none exists.")
+        .option("--esp-routing-file <path>", "Path to a JSON file holding the WHOLE native-email routing policy: { mode?, routes?, exclude? }. `routes` is keyed by the RECIPIENT's provider and its values are relative send shares per sending provider, so { \"google\": { \"microsoft\": 100 } } sends Google-hosted recipients from Microsoft inboxes. `exclude` bars a sending domain outright: [{ \"domain\": \"burned.example\", \"from_recipients\": [\"google\"] }]. Replaces --esp-matching and the file is the complete policy, not a patch.")
         .option("--sender-failover <mode>", "What happens when an enrollment's LinkedIn/WhatsApp sender goes unavailable: 'wait' (default) resumes when the sender recovers; 'rebind' moves UNTOUCHED enrollments (no thread, no pending invite, no lead binding) to the least-loaded healthy sender in the pool after ~5h of confirmed outage.")
         .option("--email-min-gap-minutes <n>", "Minimum minutes between two live emails from the SAME mailbox for this sequence (Instantly's 'time gap between emails'; integer 0-720, 0 = none). A humanization FLOOR only: Oxygen already spaces each mailbox's sends evenly across its send window (window length ÷ per-mailbox daily cap, e.g. 9h ÷ 15 = 36 min, tightening through the day to catch up on any lost slot), so it only binds when it exceeds the derived spacing — it also floors the late-day catch-up, so 12 keeps every gap ≥12 min. It never bypasses the daily caps or the send window. To send MORE per day, raise --max-emails-per-mailbox-per-day, add mailboxes, or widen the send window.")
         .option("--opportunity-value <usd>", "Estimated USD value of one positive-reply opportunity (>= 0). Analytics-only: sequence stats multiply it by the positive-reply count to report pipeline $ (stats.opportunities). Never gates a send or spends a credit.")
@@ -12984,6 +13705,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--max-new-enrollments-per-day <n>", "Daily drip cap on NEW first-touch leads the planner starts (positive integer).")
         .option("--sequence-prioritization <mode>", "Under a tight daily budget, serve 'followups' or 'new_leads' first.")
         .option("--esp-matching <mode>", "Native-email ESP matching: 'prefer' (DEFAULT) biases toward a mailbox on the recipient's own provider, falling back to any; 'off' rotates mailboxes freely; 'strict' requires a same-provider mailbox and defers the send when none exists.")
+        .option("--esp-routing-file <path>", "Path to a JSON file holding the WHOLE native-email routing policy: { mode?, routes?, exclude? }. `routes` is keyed by the RECIPIENT's provider and its values are relative send shares per sending provider, so { \"google\": { \"microsoft\": 100 } } sends Google-hosted recipients from Microsoft inboxes. `exclude` bars a sending domain outright: [{ \"domain\": \"burned.example\", \"from_recipients\": [\"google\"] }]. Replaces --esp-matching and the file is the complete policy, not a patch.")
         .option("--sender-failover <mode>", "What happens when an enrollment's LinkedIn/WhatsApp sender goes unavailable: 'wait' (default) resumes when the sender recovers; 'rebind' moves UNTOUCHED enrollments (no thread, no pending invite, no lead binding) to the least-loaded healthy sender in the pool after ~5h of confirmed outage.")
         .option("--email-min-gap-minutes <n>", "Minimum minutes between two live emails from the SAME mailbox for this sequence (Instantly's 'time gap between emails'; integer 0-720, 0 = none). A humanization FLOOR only: Oxygen already spaces each mailbox's sends evenly across its send window (window length ÷ per-mailbox daily cap, e.g. 9h ÷ 15 = 36 min, tightening through the day to catch up on any lost slot), so it only binds when it exceeds the derived spacing — it also floors the late-day catch-up, so 12 keeps every gap ≥12 min. It never bypasses the daily caps or the send window. To send MORE per day, raise --max-emails-per-mailbox-per-day, add mailboxes, or widen the send window.")
         .option("--opportunity-value <usd>", "Estimated USD value of one positive-reply opportunity (>= 0). Analytics-only: sequence stats multiply it by the positive-reply count to report pipeline $ (stats.opportunities). Never gates a send or spends a credit.")
@@ -13669,18 +14391,63 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("remove")
-        .description("Remove a lead provider id from the org do-not-contact list (re-enable contact).")
-        .requiredOption("--lead <provider_id>", "The lead provider id to un-suppress.")
-        .option("--json", "Print a JSON envelope.")
-        .action(async (options) => {
-        await handleAsyncAction("suppressions remove", options, () => {
-            const lead = readOption(options.lead);
-            if (!lead)
-                throw new Error("--lead is required.");
-            return requestOxygen(`/api/cli/suppressions?lead_provider_id=${encodeURIComponent(lead)}`, {
-                method: "DELETE",
+        .description("Remove one lead provider id (--lead), or every identity of one merged person (--subject-id), from the org do-not-contact list (re-enable contact). A subject id is stamped on each identifier of an imported contact: `hubspot:contacts:<id>` from `suppressions hubspot sync`, `manual:<uuid>` returned by `suppressions import-person`. Read it as metadata.dnc_subject_id in `suppressions list` (LinkedIn rows only) or in `suppressions addresses|phones|companies --json`, which is where an email- or phone-only contact appears.")
+        .option("--lead <provider_id>", "The lead provider id to un-suppress. Mutually exclusive with --subject-id.")
+        .option("--subject-id <id>", "DNC subject id (metadata.dnc_subject_id). Clears that person's email, phone, LinkedIn, and company suppressions in one transaction.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        const subjectId = readOption(options.subjectId);
+        if (!subjectId) {
+            await handleAsyncAction("suppressions remove", options, () => {
+                const lead = readOption(options.lead);
+                if (!lead)
+                    throw new Error("Pass --lead <provider_id> or --subject-id <id>.");
+                return requestOxygen(`/api/cli/suppressions?lead_provider_id=${encodeURIComponent(lead)}`, {
+                    method: "DELETE",
+                });
             });
-        });
+            return;
+        }
+        try {
+            if (readOption(options.lead)) {
+                throw new Error("Pass either --lead or --subject-id, not both.");
+            }
+            const data = await requestOxygen(`/api/cli/suppressions?subject_id=${encodeURIComponent(subjectId)}`, { method: "DELETE" });
+            if (options.json) {
+                writeJson(success("suppressions remove", data));
+            }
+            else {
+                // Same compact multi-ledger receipt style as `suppressions import`:
+                // the per-channel counts plus up to 10 cleared identifiers (the full
+                // list is always in the --json envelope).
+                const parsed = (data ?? {});
+                const identities = Array.isArray(parsed.removed_identities) ? parsed.removed_identities : [];
+                const removedCount = parsed.removed_count ?? 0;
+                writeJson({
+                    subject_id: parsed.subject_id ?? subjectId,
+                    removed_count: removedCount,
+                    removed_emails: parsed.removed?.email ?? 0,
+                    removed_phones: parsed.removed?.phone ?? 0,
+                    removed_linkedin: parsed.removed?.linkedin ?? 0,
+                    removed_companies: parsed.removed?.company ?? 0,
+                    removed_identities: identities.slice(0, 10),
+                    // Counted off removed_count, not the echoed array: the API caps
+                    // that list too, so --json is NOT a way to see the rest. The
+                    // counts above are the exact record of what was cleared.
+                    ...(removedCount > Math.min(identities.length, 10)
+                        ? {
+                            removed_identities_note: `Showing ${Math.min(identities.length, 10)} of ${removedCount} cleared identifiers; the counts above are exact.`,
+                        }
+                        : {}),
+                    ...(parsed.note ? { note: parsed.note } : {}),
+                    deep_link: parsed.deepLink,
+                });
+            }
+            writeCreditsReceipt(data);
+        }
+        catch (error) {
+            emitCliFailure("suppressions remove", error);
+        }
     }))
         .addCommand(new Command("import")
         .description("Bulk-import a do-not-contact blocklist from a file (newline / comma / whitespace separated, max 5000). An entry with '@' goes on the per-address email list; a bare domain (e.g. acme.com) blocks email to that whole domain; a LinkedIn profile URL or member id (ACo...) lands on the people do-not-contact list; any other URL is rejected. A domain block is a sharp tool, so --reason is REQUIRED when the file contains any domains; otherwise manual is the default. Idempotent. Consumes 0 credits.")
@@ -13776,6 +14543,12 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("import-person")
+        // Deliberately NOT extended with the subjects[] pointer: this help text
+        // is already 199 chars, and the generated CLI reference cell truncates a
+        // description past 200 to its FIRST sentence — appending anything drops
+        // the "domain is company-wide, never inferred from --email" warning from
+        // the public table. The receipt itself carries `subjects[]`, and
+        // `suppressions remove --help` names where subject ids come from.
         .description("Import one person as one DNC subject with any combination of email, LinkedIn, E.164 phone, and an explicitly supplied company domain. The domain is company-wide and is never inferred from --email.")
         .option("--name <name>", "Optional contact display name.")
         .option("--email <address>", "Email address to suppress.")
@@ -14274,24 +15047,63 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     })));
     program.addCommand(new Command("mailboxes")
-        .description("Native email sending pool: register/refresh Google/Microsoft mailboxes (including secure local credential-file transfer), pause/disable inboxes, connect EmailGuard monitoring, and inspect/control OXYGEN Warm-up. Fresh managed InboxKit Google/Microsoft/Azure orders activate exact-scope warm-up automatically after provisioning under their approved default-on add-on. Google reuses the managed credential just in time; Microsoft/Azure uses native export. Standalone warm-up plans and credit caps are for BYOK/imported mailboxes, managed opt-outs, or later separate enrollment. OXYGEN Warm-up never owns campaign dispatch. Safe import preflight: run `oxygen mailboxes compatibility --catalog-only --json`, then `oxygen mailboxes import --file <path> --validate-only --json` (add the credential source flags shown by import help when the file contains credentials).")
+        .description("Native email sending pool: register/refresh Google/Microsoft mailboxes (including secure local credential-file transfer), pause/disable inboxes, connect EmailGuard monitoring, and inspect/control OXYGEN Warm-up. Fresh managed InboxKit Google/Microsoft/Azure orders activate exact-scope warm-up automatically after provisioning under their approved default-on add-on. Google reuses the managed credential just in time; Microsoft/Azure uses native export. Standalone warm-up plans and credit caps are for BYOK/imported mailboxes, managed opt-outs, or later separate enrollment. OXYGEN Warm-up never owns campaign dispatch. Every inbox here always belongs to a sender profile (the person it sends as) — list, create, and attach those with `oxygen senders profiles`. Safe import preflight: run `oxygen mailboxes compatibility --catalog-only --json`, then `oxygen mailboxes import --file <path> --validate-only --json` (add the credential source flags shown by import help when the file contains credentials).")
         .addCommand(new Command("list")
-        .description("List the org's sending mailboxes with provider, status, warmup state, source (managed = bought through Oxygen, byok = bring-your-own), worker-owned connectionRepair and warmupRepair state, and a pool overview (including counts by source). Read each mailbox's warmupTruth for warm-up (state, last_send, pause, dispatch, next_action with the exact command); warmupState is only the stored rail token and reads `error` for a provider-paused seat. mode=automatic means OXYGEN owns the next bounded retry — do not ask for browser consent or disable/re-enable an existing warm-up seat. To see only Google/Microsoft mailboxes that still need OAuth connection, including attempt budgets and manual remedies, use `oxygen mailboxes oauth-health --json`.")
+        .description("List the org's sending mailboxes with provider, status, warmup state, source (managed = bought through Oxygen, byok = bring-your-own), worker-owned connectionRepair and warmupRepair state, and a pool overview (including counts by source). Read each mailbox's warmupTruth for warm-up (state, last_send, pause, dispatch, next_action with the exact command); warmupState is only the stored rail token and reads `error` for a provider-paused seat. mode=automatic means OXYGEN owns the next bounded retry — do not ask for browser consent or disable/re-enable an existing warm-up seat. To see only Google/Microsoft mailboxes that still need OAuth connection, including attempt budgets and manual remedies, use `oxygen mailboxes oauth-health --json`. Read the fleet from `summary` — `summary.by_warmup`, `by_status`, `by_provider`, `by_auth_mode`, `by_transport`, and `by_source` already aggregate every mailbox, so you never need to iterate the `mailboxes` array to count them. `summary.warmup` adds the normalized pool counts — by_truth_state, by_next_action, enrolled, stalled (enrolled with a measured zero warm-up sends), and needs_action — and `--warmup <states>`, `--next-action <codes>`, and `--stalled` narrow the list to exactly those mailboxes, so \"which of my inboxes are not sending\" is one command rather than a local transform over every row. Without `--json` this prints a readable pool: the counts, then every mailbox that owes an action with its cause and the exact command to run.")
         .option("--status <status>", "Filter by status: active, paused, disabled, or provisioning (ordered, still being set up).")
         .option("--tag <tags>", "Comma-separated workspace tags — matches mailboxes carrying ANY of these tags (see `oxygen tags list`).")
-        .option("--json", "Print a JSON envelope.")
+        .option("--warmup <states>", "Show only mailboxes whose warm-up is in one of these states (comma-separated): warming, active, paused, error, disabled, pending, not_enrolled, unknown.")
+        .option("--next-action <codes>", "Show only mailboxes whose warm-up needs one of these next steps (comma-separated): none, resume_warmup, reconnect_warmup, enable_warmup, connect_oauth, fix_dns, wait, contact_support.")
+        .option("--stalled", "Show only mailboxes enrolled in warm-up with zero recorded sends (warmupTruth.dispatch.sent null or 0) — the seats you are paying for that are silent. In practice these are the `pending` truth state; an `error` seat has usually sent some mail before it stopped, so it is not stalled.")
+        .option("--json", "Print a JSON envelope. The full payload carries per-mailbox daily warm-up metrics, so a large fleet is megabytes — narrow it with --stalled / --warmup / --next-action, or read the default human view, which already aggregates the pool.")
         .action(async (options) => {
-        await handleAsyncAction("mailboxes list", options, () => {
-            const params = new URLSearchParams();
-            const status = readOption(options.status);
-            if (status)
-                params.set("status", status);
-            const tags = splitCommaList(options.tag);
-            if (tags.length > 0)
-                params.set("tag", tags.join(","));
-            const suffix = params.toString();
-            return requestOxygen(`/api/cli/mailboxes${suffix ? `?${suffix}` : ""}`);
+        const params = new URLSearchParams();
+        const status = readOption(options.status);
+        if (status)
+            params.set("status", status);
+        const tags = splitCommaList(options.tag);
+        if (tags.length > 0)
+            params.set("tag", tags.join(","));
+        const warmupStates = splitCommaList(options.warmup);
+        if (warmupStates.length > 0)
+            params.set("warmup", warmupStates.join(","));
+        const nextActions = splitCommaList(options.nextAction);
+        if (nextActions.length > 0)
+            params.set("next_action", nextActions.join(","));
+        // Only ever sent as `true`. Omitted when the flag is absent so the
+        // server never has to decide what an unasked-for `stalled=false` meant.
+        if (options.stalled)
+            params.set("stalled", "true");
+        const suffix = params.toString();
+        // What this CLI asked for, kept as flags in query order: a server too
+        // old to echo `filters` back still must not let a match count read as
+        // the whole pool. Every facet narrows the same counts, so every facet
+        // is here — status and tag included.
+        const filterFlags = [];
+        if (status)
+            filterFlags.push(`--status ${status}`);
+        if (tags.length > 0)
+            filterFlags.push(`--tag ${tags.join(",")}`);
+        if (warmupStates.length > 0)
+            filterFlags.push(`--warmup ${warmupStates.join(",")}`);
+        if (nextActions.length > 0)
+            filterFlags.push(`--next-action ${nextActions.join(",")}`);
+        if (options.stalled)
+            filterFlags.push("--stalled");
+        // Bypasses handleAsyncAction the way `tables link` does: --json stays
+        // the byte-identical envelope, and a terminal gets a pool a person can
+        // read instead of the raw blob it used to print.
+        const result = await requestOxygen(`/api/cli/mailboxes${suffix ? `?${suffix}` : ""}`).catch((error) => {
+            emitCliFailure("mailboxes list", error);
+            return null;
         });
+        if (!result)
+            return;
+        if (options.json) {
+            emitSuccess("mailboxes list", result, options);
+            return;
+        }
+        writeMailboxPoolOverview(result, { filtered: suffix.length > 0, filterFlags });
     }))
         .addCommand(new Command("get")
         .description("Get one sending mailbox's configuration/readiness detail (provider, status, daily cap, warmup state, auth mode, and source — managed vs bring-your-own) plus a one-row pool summary. This is not sent/replied/bounced performance; use `oxygen sequences analytics` for native Sequence attribution by mailbox/domain. An ineligible native-send transport includes transport_reason + transport_hint; it does not by itself block OXYGEN Warm-up or EmailGuard monitoring. <mailbox> accepts a mailbox id or email address.")
@@ -14330,13 +15142,13 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("health")
-        .description("Fleet email-health: the sending pool rolled up by external deliverability reputation (healthy/degraded/critical/unknown), per-mailbox scores, connected health providers, and DIRECTIONAL recommendations. Pure read — 0 credits; never pauses a mailbox.")
+        .description("Fleet email-health: the sending pool rolled up by external deliverability reputation (healthy/degraded/critical/unknown), per-mailbox scores, connected health providers, and DIRECTIONAL recommendations — plus OXYGEN's OWN evidence for the last 7 days, which needs no provider connected: the bounce notifications each mailbox received classified as provider rejection / dead address / mailbox full / delay (a Gmail reputation block shows up as provider_rejected), distinct recipients that first hard-bounced, sequence sends OXYGEN logged (source=sequence only), warm-up day, health score and stop cause, the advisory daily cap that warm-up age supports, and the same rollup per sending domain ranked worst-first. Notifications whose body was never stored count as signals.dsn7d.unclassified, which means OXYGEN could not look — not that nothing was wrong. Read health_coverage to see how many mailboxes an external provider has actually scored. Start from the two fleet reads instead of scanning the mailbox array: warmup.byCause (why warm-up stopped, counted once for the whole pool) and signals.capOverRecommendedMailboxes (mailboxes whose configured cap is above the one warm-up supports — per mailbox, compare dailyCap with recommendedDailyCap; the gap is flagged as the cap_exceeds_readiness warning). Every count is scoped, and the scope is stamped into the payload as signals.window (7d) and signals.sendSource (sequence sends only), on the fleet object and on every mailbox: a 0 means nothing was recorded in that window for that send source, NOT that the fleet is un-blocklisted everywhere. Pure read — 0 credits; never pauses a mailbox or changes a cap.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("mailboxes health", options, () => requestOxygen("/api/cli/mailboxes/health"));
     }))
         .addCommand(new Command("compatibility")
-        .description("Read-only compatibility report for every selected mailbox: generic origin class, real infrastructure tier (including InboxKit Azure), OXYGEN native-send connection quality, OXYGEN Warm-up path, EmailGuard monitoring path, and exact next actions. Read automatic_repair for native send and warmup_automatic_repair for an existing warm-up seat: mode=automatic means OXYGEN owns the next bounded retry. Native send distinguishes destination-bound OAuth, provider-managed API transport, admin delegation, and authorization_required. Use --catalog-only for the compact workspace-independent import contract. JSON data.compatibility contains checked rows; data.import_methods and data.import_fields describe accepted transfer inputs; data.provider_matrix is the current public product matrix; data.non_transferable_auth names credentials that must be reconnected; data.summary rolls up states; data.web_url opens the pool. Downstream states distinguish credential_required, consent_required, and vendor_blocked. Never decrypts a credential or calls a downstream provider.")
+        .description("Read-only compatibility report per mailbox — select with --mailboxes <address,…> (omit for the whole pool; filter here, not in a script): generic origin class, real infrastructure tier (including InboxKit Azure), OXYGEN native-send connection quality, OXYGEN Warm-up path, EmailGuard monitoring path, and exact next actions. Read automatic_repair for native send and warmup_automatic_repair for an existing warm-up seat: mode=automatic means OXYGEN owns the next bounded retry. Native send distinguishes destination-bound OAuth, provider-managed API transport, admin delegation, and authorization_required. Use --catalog-only for the compact workspace-independent import contract. JSON data.compatibility contains checked rows; data.import_methods and data.import_fields describe accepted transfer inputs; data.provider_matrix is the current public product matrix; data.non_transferable_auth names credentials that must be reconnected; data.summary rolls up states; data.web_url opens the pool. Downstream states distinguish credential_required, consent_required, and vendor_blocked. Never decrypts a credential or calls a downstream provider.")
         .option("--mailboxes <list>", "Comma-separated mailbox ids or addresses. Omit for the whole pool.")
         .option("--catalog-only", "Return only the bounded import-method, field, auth-boundary, and public provider catalogs; do not read or return workspace mailbox rows.")
         .option("--json", "Print a JSON envelope.")
@@ -14358,11 +15170,11 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("import")
-        .description("Register (or refresh) sending mailboxes in bulk. Use --validate-only with a local file for a non-mutating, no-network preflight; without it, import is a 0-credit state mutation whose upsert is idempotent by mailbox address. CSV/JSON/JSONL/XLSX identity files from any vendor use --file plus optional --vendor. Compatible Google app-password exports use --from credentials --vendor <source>. Connected Zapmail inventories use --from zapmail. In credential files, app_password is Google-only; Microsoft password fields are discarded locally. OAuth grants, MFA/TOTP seeds, and delegation keys never transfer from customer files: fresh managed InboxKit Google orders reuse the vendor-held credential just in time for automatic warmup, while fresh managed Microsoft/Azure orders use native InboxKit Sequencer export; opted-out/separate managed enrollment uses standalone `warmup enable`; eligible non-InboxKit Microsoft warmup uses the Outlook OAuth fallback (`mailboxes warmup microsoft`); EmailGuard remains vendor_blocked for Microsoft. Google app passwords supplied through an authorized credential import are sent only in the request body, encrypted server-side, and never returned.")
+        .description("Register (or refresh) sending mailboxes in bulk. Use --validate-only with a local file for a non-mutating, no-network preflight; without it, import is a 0-credit state mutation whose upsert is idempotent by mailbox address. CSV/JSON/JSONL/XLSX identity files from any vendor use --file plus optional --vendor. Compatible Google app-password exports use --from credentials --vendor <source>. Connected Zapmail inventories use --from zapmail. In credential files, app_password is Google-only; Microsoft password fields are discarded locally. OAuth grants, MFA/TOTP seeds, and delegation keys never transfer from customer files: fresh managed InboxKit Google orders reuse the vendor-held credential just in time for automatic warmup, while fresh managed Microsoft/Azure orders use native InboxKit Sequencer export; opted-out/separate managed enrollment uses standalone `warmup enable`; eligible non-InboxKit Microsoft warmup uses the Outlook OAuth fallback (`mailboxes warmup microsoft`); EmailGuard remains vendor_blocked for Microsoft. Google app passwords supplied through an authorized credential import are sent only in the request body, encrypted server-side, and never returned. Every imported inbox is attached to a sender profile: --sender <id> names the person, a row's first/last or display name finds or creates them, otherwise OXYGEN creates a profile named from the address for you to correct.")
         .addHelpText("after", [
         "",
         "Ordinary identity file contract (CSV / JSON / JSONL / XLSX):",
-        "  Canonical fields: email_address, provider, workspace_external_id?, infrastructure_platform?, tenant_id?. Common vendor aliases such as Email, From Email, ESP, Mailbox ID, and Entra Tenant ID are mapped locally. Credentials are rejected.",
+        "  Canonical fields: email_address, provider, workspace_external_id?, infrastructure_platform?, tenant_id?, first_name?, last_name?, display_name?, sender_profile_id?. Common vendor aliases such as Email, From Email, ESP, Mailbox ID, Entra Tenant ID, Given Name, Surname, and From Name are mapped locally. Credentials are rejected.",
         "",
         "All local file imports:",
         "  Limits: 500 rows / 5 MB for identity and credential files.",
@@ -14380,6 +15192,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--vendor <slug>", "Non-secret source provenance (for example instantly, mailforge, or smartlead). Required with --from credentials; optional for identity files.")
         .option("--connection <id>", "Zapmail connection id (--from zapmail). Defaults to the org's active Zapmail connection.")
         .option("--provider <provider>", "Zapmail pool to pull (--from zapmail): google or microsoft. Zapmail's mailbox list is provider-scoped, so the Microsoft pool is only reachable with --provider microsoft; Microsoft mailboxes get their Entra tenant id stamped on import.")
+        .option("--sender <profileId>", "Sender profile every imported inbox belongs to (`oxygen senders profiles list` for ids, `create` for a new person). A row's own sender_profile_id or first/last name wins over it; without either, OXYGEN creates a profile named from the address.")
         .option("--validate-only", "Parse, normalize, and policy-check a local file, then return non-secret aggregate counts without authentication, network access, provider calls, or workspace writes.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
@@ -14389,6 +15202,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
             const vendor = readOption(options.vendor);
             const connection = readOption(options.connection);
             const provider = readOption(options.provider);
+            const sender = readOption(options.sender);
             const validateOnly = options.validateOnly === true;
             if (from &&
                 from !== "zapmail" &&
@@ -14412,6 +15226,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
                         source: "zapmail",
                         ...(connection ? { connection_id: connection } : {}),
                         ...(provider ? { service_provider: provider } : {}),
+                        ...(sender ? { sender_profile_id: sender } : {}),
                     },
                 });
             }
@@ -14447,6 +15262,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
                     ...(sourceProvider
                         ? { source_provider: sourceProvider }
                         : {}),
+                    ...(sender ? { sender_profile_id: sender } : {}),
                     mailboxes,
                 },
             });
@@ -14696,7 +15512,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--arm", "Arm the standing permission. Requires --max-credits; previews unless --approved.")
         .option("--disarm", "Turn it off. Existing subscriptions are untouched. 0 credits, no approval needed.")
         .option("--run", "Enrol one bounded batch now.")
-        .option("--dry-run", "With --run: report what would be enrolled without connecting or charging.")
+        .option("--dry-run", "With --run: report what would be enrolled without connecting or charging. Mailboxes held back by OXYGEN's own managed capacity are reported once under platform_condition (owner: oxygen) rather than as per-mailbox skips; skip_summary counts the rest by reason.")
         .option("--max-credits <n>", "Per-billing-cycle credit ceiling this permission may spend (required with --arm).")
         .option("--approved", "Actually arm (otherwise --arm returns a preview).")
         .option("--json", "Print a JSON envelope.")
@@ -14958,7 +15774,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("resume")
-        .description("Resume paused warmup at each mailbox's recorded rail (OXYGEN Warm-up, or TrulyInbox for inboxes still warming there). A mailbox on a rail Oxygen no longer drives reports unsupported instead of being retargeted. Targets the whole pool unless --mailboxes is given.")
+        .description("Resume paused warmup at each mailbox's recorded rail (OXYGEN Warm-up, or TrulyInbox for inboxes still warming there). 0 Oxygen credits; the existing subscription is unchanged. This changes warmup state and uses the last stored analytics snapshot; run warmup status afterward for fresh provider data. Running status alone does not prove a new successful send. A mailbox on a rail Oxygen no longer drives reports unsupported instead of being retargeted. Targets the whole pool unless --mailboxes is given.")
         .option("--mailboxes <list>", "Comma-separated mailbox ids or addresses. Omit for the whole pool.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
@@ -16418,6 +17234,7 @@ Full trigger schema: oxygen workflows schema --subject trigger --json
     registerVisualCommands(program, handleAsyncAction);
     registerFunctionsCommands(program, handleAsyncAction);
     registerUgcCommands(program, handleAsyncAction);
+    registerKnowledgeRepositoryCommands(program, handleAsyncAction);
     return program;
 }
 /**
@@ -18453,11 +19270,15 @@ function readFeedBindBody(table, options) {
         ...(options.approved ? { approved: true } : {}),
     };
 }
-function readSignalsSearchPlanBody(options) {
+function readSignalsSearchPlanBody(options, promptArg) {
+    // The prompt may arrive as --prompt or as the positional argument; the flag wins.
+    const promptSource = options.prompt ?? promptArg;
     const targetCount = readPositiveInt(options.targetCount);
     const filters = readSignalSearchFilters(options);
     return {
-        prompt: readFileIfPresent(options.prompt),
+        // Omit when neither was given so the request still reaches the server, which
+        // answers with a clean `prompt is required.` instead of crashing readFileIfPresent.
+        ...(promptSource !== undefined ? { prompt: readFileIfPresent(promptSource) } : {}),
         family: options.family,
         ...(readOption(options.scope) ? { scope: readOption(options.scope) } : {}),
         ...(targetCount !== undefined ? { target_count: targetCount } : {}),
@@ -18465,8 +19286,10 @@ function readSignalsSearchPlanBody(options) {
         ...(options.estimate ? { estimate: true } : {}),
     };
 }
-function readSignalsSearchRunBody(options) {
-    const prompt = options.prompt ? readFileIfPresent(options.prompt) : null;
+function readSignalsSearchRunBody(options, promptArg) {
+    // The prompt may arrive as --prompt or as the positional argument; the flag wins.
+    const promptSource = options.prompt ?? promptArg;
+    const prompt = promptSource ? readFileIfPresent(promptSource) : null;
     const plan = options.planJson ? readSearchPlanJson(options.planJson) : null;
     if (!prompt && !plan) {
         throw new OxygenError("invalid_request", "Pass --prompt or --plan-json.", { exitCode: 1 });
@@ -18538,11 +19361,15 @@ function readSignalSearchFilters(options) {
     }
     return Object.keys(filters).length > 0 ? filters : null;
 }
-function readCompaniesSearchPlanBody(options) {
+function readCompaniesSearchPlanBody(options, promptArg) {
+    // The prompt may arrive as --prompt or as the positional argument; the flag wins.
+    const promptSource = options.prompt ?? promptArg;
     const targetCount = readPositiveInt(options.targetCount);
     const filters = readCompanySearchFilters(options);
     return {
-        prompt: readFileIfPresent(options.prompt),
+        // Omit when neither was given so the request still reaches the server, which
+        // answers with a clean `prompt is required.` instead of crashing readFileIfPresent.
+        ...(promptSource !== undefined ? { prompt: readFileIfPresent(promptSource) } : {}),
         ...(targetCount !== undefined ? { target_count: targetCount } : {}),
         ...(options.sourceIntent ? { source_intent: options.sourceIntent } : {}),
         ...(filters ? { filters } : {}),
@@ -18550,8 +19377,10 @@ function readCompaniesSearchPlanBody(options) {
         ...(options.materializePreview ? { materialize_preview: true } : {}),
     };
 }
-function readCompaniesSearchRunBody(options) {
-    const prompt = options.prompt ? readFileIfPresent(options.prompt) : null;
+function readCompaniesSearchRunBody(options, promptArg) {
+    // The prompt may arrive as --prompt or as the positional argument; the flag wins.
+    const promptSource = options.prompt ?? promptArg;
+    const prompt = promptSource ? readFileIfPresent(promptSource) : null;
     const plan = options.planJson ? readSearchPlanJson(options.planJson) : null;
     if (!prompt && !plan) {
         throw new OxygenError("invalid_request", "Pass --prompt or --plan-json.", { exitCode: 1 });
@@ -18993,6 +19822,7 @@ async function importRows(table, options) {
     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({
@@ -19014,6 +19844,7 @@ async function importRows(table, options) {
         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);
@@ -19033,10 +19864,11 @@ async function importRows(table, options) {
         batchCount: writeRequestCount,
         batchSize: effectiveBatchSize,
         ...(effectiveBatchSize !== batchSize ? { requestedBatchSize: batchSize } : {}),
-        ...(requestTooLargeRetries > 0 ? {
-            requestTooLargeRetries,
-            minimumBatchSizeUsed,
-        } : {}),
+        // 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") } : {}),
     };
@@ -19165,38 +19997,58 @@ function remapImportRows(rows, sourceKeyMap) {
     });
 }
 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: {
-                table: input.tableRef,
-                rows: input.rows,
-                ...(input.upsertKey ? { key: input.upsertKey } : {}),
-                ...(!input.upsertKey && input.requestId ? { request_id: input.requestId } : {}),
-            },
+            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 = 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 combineImportBatchWriteSummaries(first, second, 1);
+        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 : [];
@@ -19209,11 +20061,12 @@ function summarizeImportBatchWrite(result, batchSize) {
         warningsTruncated: result.warningsTruncated === true || warningCount > batchWarnings.length,
         writeRequestCount: 1,
         requestTooLargeRetries: 0,
+        byteSplits: 0,
         minimumBatchSizeUsed: batchSize,
         lastResult: result,
     };
 }
-function combineImportBatchWriteSummaries(first, second, extraRequestTooLargeRetries) {
+function combineImportBatchWriteSummaries(first, second, extra) {
     const warnings = [...first.warnings, ...second.warnings].slice(0, 20);
     const warningCount = first.warningCount + second.warningCount;
     return {
@@ -19224,7 +20077,8 @@ function combineImportBatchWriteSummaries(first, second, extraRequestTooLargeRet
         warnings,
         warningsTruncated: first.warningsTruncated || second.warningsTruncated || warningCount > warnings.length,
         writeRequestCount: first.writeRequestCount + second.writeRequestCount,
-        requestTooLargeRetries: first.requestTooLargeRetries + second.requestTooLargeRetries + extraRequestTooLargeRetries,
+        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,
     };
@@ -19778,12 +20632,33 @@ async function listTableRuns(options) {
         runCount: runs.length,
         output: outputPath ?? null,
         ...(outputPath ? {} : { content: formatted.content }),
+        // An empty default listing says which finished runs it hid; keep that
+        // pointer when the history is formatted instead of returned as an envelope.
+        ...(typeof result.hint === "string"
+            ? { hidden_run_count: result.hidden_run_count ?? null, hint: result.hint, next_actions: result.next_actions ?? [] }
+            : {}),
         ...(typeof result.web_url === "string" ? { web_url: result.web_url } : {}),
     };
 }
-const TABLE_BUNDLE_SCHEMA_VERSION = 1;
+// 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);
@@ -19793,96 +20668,198 @@ async function exportTableBundle(table, options) {
     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;
-    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;
+    try {
+        if (stream) {
+            await writeBundleLine(stream, JSON.stringify({
+                schemaVersion: TABLE_BUNDLE_SCHEMA_VERSION,
+                exportedAt,
+                table: tableSummary,
+                columns,
+            }));
         }
-        for (const row of page.rows ?? [])
-            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 && rows.length !== 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: rows.length,
-                missing: expectedTotal - rows.length,
-                pages: pageCount,
-            },
-            exitCode: 1,
-        });
-    }
-    const tableId = readRecordString(tableMeta, "id");
-    const tableSlug = readRecordString(tableMeta, "slug");
-    const projectSlug = readRecordString(tableMeta, "projectSlug");
-    const bundle = {
-        schemaVersion: TABLE_BUNDLE_SCHEMA_VERSION,
-        exportedAt: new Date().toISOString(),
-        table: {
-            id: tableId ?? null,
-            slug: tableSlug ?? null,
-            name: readRecordString(tableMeta, "displayName") ?? readRecordString(tableMeta, "name") ?? null,
-            projectSlug: projectSlug ?? null,
-        },
-        columns,
-        rows,
-        totals: {
-            rowCount: rows.length,
+        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 (options.output) {
-        writeFileSync(options.output, `${JSON.stringify(bundle, null, 2)}\n`);
+        };
+        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;
     }
-    const summary = {
-        table_id: tableId ?? null,
-        table_slug: tableSlug ?? null,
-        schema_version: TABLE_BUNDLE_SCHEMA_VERSION,
-        column_count: columns.length,
-        row_count: rows.length,
-        pages: pageCount,
-        page_size: pageSize,
-        output: options.output ?? null,
-        ...(tableId ? { web_url: tableWebUrl(tableId) } : tableSlug ? { web_url: tableWebUrl(tableSlug) } : {}),
-    };
-    // When piping to stdout, also emit the full bundle so it can be redirected
-    // into a file. With --output, the file is the source of truth; keep the
-    // stdout response a small summary so it's readable.
-    return options.output ? summary : { ...summary, bundle };
 }
 async function importTableBundle(// skipcq: JS-R1005
-options) {
+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 raw = readFileSync(resolve(path), "utf8");
-    const bundle = parseBundleFile(raw);
-    const columns = bundle.columns.map(bundleColumnToCreateInput);
-    if (columns.length === 0) {
+    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);
@@ -19940,13 +20917,14 @@ options) {
             ?? (created ? readRecordString(created, "slug") : null);
         createdTable = true;
     }
-    const stagedRows = bundle.rows.map((row) => stripRowForImport(row, validColumnKeys));
     // In upsert mode every row must carry the key value; otherwise the upsert
-    // route rejects the whole batch midway. Fail fast with a clear message before
-    // writing anything so we never leave a half-imported table behind for a
-    // predictable data problem.
-    if (upsertKey) {
-        const missingIndex = stagedRows.findIndex((row) => row[upsertKey] === undefined || row[upsertKey] === null);
+    // 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 });
         }
@@ -19956,28 +20934,34 @@ options) {
         tableId: newTableId,
         key: upsertKey ?? null,
         batchSize: effectiveBatchSize,
+        binaryName,
     });
     let processed = 0;
     let insertedCount = 0;
     let updatedCount = 0;
-    for (let offset = 0; offset < stagedRows.length; offset += effectiveBatchSize) {
-        const batch = stagedRows.slice(offset, offset + effectiveBatchSize);
-        if (batch.length === 0)
-            continue;
+    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) {
-                const response = await requestOxygen("/api/cli/tables/rows/upsert", {
-                    method: "POST",
-                    body: { table: newTableId, key: upsertKey, rows: batch, return: "summary" },
-                });
-                insertedCount += readCount(response.insertedCount);
-                updatedCount += readCount(response.updatedCount);
+                insertedCount += result.insertedCount;
+                updatedCount += result.updatedCount;
             }
             else {
-                await requestOxygen("/api/cli/tables/rows", {
-                    method: "POST",
-                    body: { table: newTableId, rows: batch },
-                });
                 insertedCount += batch.length;
             }
             processed += batch.length;
@@ -19994,13 +20978,13 @@ options) {
             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}/${stagedRows.length} rows. ${recovery}`, {
+            throw new OxygenError("bundle_import_incomplete", `Bundle import stopped after ${processed}/${bundle.rowCount} rows. ${recovery}`, {
                 details: {
                     table_id: newTableId,
                     table_slug: newTableSlug,
-                    rows_total: stagedRows.length,
+                    rows_total: bundle.rowCount,
                     rows_processed: processed,
-                    failed_batch_offset: offset,
+                    failed_batch_offset: processed,
                     failed_batch_size: batch.length,
                     mode: upsertKey ? "upsert" : "insert",
                     ...(upsertKey ? { key: upsertKey } : {}),
@@ -20019,6 +21003,12 @@ options) {
         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 }
             : {}),
@@ -20034,7 +21024,10 @@ options) {
 function buildBundleResumeCommand(input) {
     const fileArg = /\s/.test(input.file) ? `"${input.file}"` : input.file;
     const parts = [
-        "oxygen tables import-bundle",
+        // 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>"}`,
@@ -20083,6 +21076,183 @@ function bundleColumnToCreateInput(column) {
             : {}),
     };
 }
+// 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 {
@@ -20099,9 +21269,12 @@ function parseBundleFile(text) {
     }
     const record = parsed;
     const schemaVersion = typeof record.schemaVersion === "number" ? record.schemaVersion : 1;
-    if (schemaVersion !== TABLE_BUNDLE_SCHEMA_VERSION) {
+    // 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_SCHEMA_VERSION, got: schemaVersion },
+            details: { supported: TABLE_BUNDLE_SUPPORTED_SCHEMA_VERSIONS, got: schemaVersion },
             exitCode: 1,
         });
     }
@@ -20325,14 +21498,24 @@ function readRecord(value, key) {
     const entry = value[key];
     return isRecord(entry) ? entry : null;
 }
+// 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 `https://oxygen-agent.com/tables/${encodeURIComponent(tableIdOrSlug)}`;
+    return `${defaultApiUrl().replace(/\/+$/, "")}/tables/${encodeURIComponent(tableIdOrSlug)}`;
 }
 function formatImportFileSizeLimit(tier) {
     const limits = PLAN_LIMITS[tier].import;
     const megabytes = Math.round(limits.maxFileBytes / (1024 * 1024));
     return `${megabytes} MB`;
 }
+// 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
@@ -23359,6 +24542,28 @@ function readCsvOption(value) {
         .map((entry) => entry.trim())
         .filter(Boolean);
 }
+function parseSupabaseTableSelection(value) {
+    const entries = readCsvOption(value);
+    if (entries.length === 0)
+        return undefined;
+    const seen = new Set();
+    return entries.map((entry) => {
+        const separator = entry.indexOf(".");
+        const schema = separator > 0 ? entry.slice(0, separator).trim() : "";
+        const table = separator > 0 ? entry.slice(separator + 1).trim() : "";
+        if (!schema || !table) {
+            throw new OxygenError("invalid_request", `Expected schema.table, received ${entry}.`, {
+                details: { value: entry }, exitCode: 1,
+            });
+        }
+        const key = `${schema}\0${table}`;
+        if (seen.has(key)) {
+            throw new OxygenError("invalid_request", `Duplicate Supabase table: ${entry}.`, { exitCode: 1 });
+        }
+        seen.add(key);
+        return { schema, table };
+    });
+}
 // Assemble the directory listing profile payload shared by `directory update`
 // and `admin directory enable`. --profile-json provides the base object (and
 // the only way to null-clear fields); explicit flags override it.
@@ -24341,6 +25546,27 @@ function readPositiveNumber(value) {
     }
     return parsed;
 }
+/**
+ * A spend ceiling where ZERO IS VALID and meaningful: `find company
+ * --max-credits 0` asks for the lanes that cost nothing (crustdata's identify
+ * lane resolves domain↔LinkedIn for 0 credits) and skips every priced one.
+ * readPositiveNumber rejected it client-side, so the free lanes were
+ * unreachable from the CLI at all (Plain T-111). Fractional ceilings stay legal
+ * — lane estimates are fractional — so this is not the whole-number reader.
+ */
+function readCreditCeilingOrZero(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return undefined;
+    const parsed = Number(trimmed);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new OxygenError("invalid_number", "Expected a number of 0 or more.", {
+            details: { value },
+            exitCode: 1,
+        });
+    }
+    return parsed;
+}
 /**
  * A whole count (days, rows, windows). Its positive-number sibling accepts 2.5,
  * which for a scan bound is always a typo — rejected here so it costs no round trip,
@@ -24392,19 +25618,6 @@ function readNonNegativeNumber(value) {
     }
     return parsed;
 }
-function readNonNegativeInt(value) {
-    const trimmed = value?.trim();
-    if (!trimmed)
-        return undefined;
-    const parsed = Number(trimmed);
-    if (!Number.isSafeInteger(parsed) || parsed < 0) {
-        throw new OxygenError("invalid_number", "Expected a non-negative integer.", {
-            details: { value },
-            exitCode: 1,
-        });
-    }
-    return parsed;
-}
 // Folds the sequence-level email send controls (--max-emails-per-mailbox-per-day,
 // --send-window-file) into a partial `settings` object. Returns undefined when
 // neither flag is set so the field is omitted from the request body entirely.
@@ -24465,6 +25678,12 @@ function readSequenceSettings(options) {
     const espMatching = readOption(options.espMatching);
     if (espMatching)
         settings.esp_matching = espMatching;
+    // The file is the whole policy: settings merge by top-level key, so a partial
+    // document would silently drop the routes or exclusions it omits.
+    const espRoutingPath = readOption(options.espRoutingFile);
+    if (espRoutingPath) {
+        settings.esp_matching = readJsonFileValue(resolve(espRoutingPath), "--esp-routing-file");
+    }
     const senderFailover = readOption(options.senderFailover);
     if (senderFailover)
         settings.sender_failover = senderFailover;