@oxygen-agent/cli 1.225.28 → 1.233.8

package/README.md

@@ -34,4 +34,4 @@ oxygen update
 
 For product documentation, visit https://oxygen-agent.com/docs. For support, visit https://oxygen-agent.com.
 
-Version: 1.225.28
+Version: 1.233.8

package/dist/index.js

@@ -428,9 +428,66 @@ function buildCrmSyncImportBody(provider, options) {
         ...(options.approved ? { approved: true } : {}),
     };
 }
-function buildCrmSyncStatusPath(runId) {
+function buildCrmSyncConfigureBody(options) {
+    return {
+        provider: options.provider,
+        object: options.object,
+        mode: resolveCrmSetupMode(options),
+        ...(readOption(options.direction) ? { direction: readOption(options.direction) } : {}),
+        ...(readOption(options.cron) ? { cron: readOption(options.cron) } : {}),
+        ...(readOption(options.timezone) ? { timezone: readOption(options.timezone) } : {}),
+        ...(readPositiveInt(options.maxRows) !== undefined ? { max_rows_per_cycle: readPositiveInt(options.maxRows) } : {}),
+        ...(readPositiveNumber(options.maxCredits) !== undefined ? { max_credits: readPositiveNumber(options.maxCredits) } : {}),
+        ...(options.approved ? { approved: true } : {}),
+    };
+}
+function buildCrmSyncRunBody(options) {
+    return {
+        provider: options.provider,
+        object: options.object,
+        mode: resolveCrmSetupMode(options),
+        ...(readPositiveInt(options.maxRows) !== undefined ? { max_rows_per_cycle: readPositiveInt(options.maxRows) } : {}),
+        ...(readPositiveNumber(options.maxCredits) !== undefined ? { max_credits: readPositiveNumber(options.maxCredits) } : {}),
+        ...(options.approved ? { approved: true } : {}),
+    };
+}
+function buildCrmSyncEnableBody(options) {
+    return {
+        provider: options.provider,
+        object: options.object,
+        ...(readOption(options.direction) ? { direction: readOption(options.direction) } : {}),
+        ...(readOption(options.cron) ? { cron: readOption(options.cron) } : {}),
+        ...(readOption(options.timezone) ? { timezone: readOption(options.timezone) } : {}),
+        ...(readPositiveInt(options.maxRows) !== undefined ? { max_rows_per_cycle: readPositiveInt(options.maxRows) } : {}),
+        ...(readPositiveNumber(options.maxCredits) !== undefined ? { max_credits: readPositiveNumber(options.maxCredits) } : {}),
+        ...(options.approved ? { approved: true } : {}),
+        // Commander maps --no-run-now to runNow:false (default true); only send the
+        // opt-out so the route's default (run an immediate first cycle) holds.
+        ...(options.runNow === false ? { run_now: false } : {}),
+    };
+}
+function buildCrmSyncDisableBody(options) {
+    return { provider: options.provider, object: options.object };
+}
+function buildCrmSyncConfigStatusPath(options) {
+    const runId = readOption(options.runId);
+    const provider = readOption(options.provider);
+    const object = readOption(options.object);
+    const hasPair = provider !== null && object !== null;
+    if (runId !== null && (provider !== null || object !== null)) {
+        throw new OxygenError("conflicting_flags", "Pass either --run-id or --provider/--object, not both.", { exitCode: 1 });
+    }
+    if (runId === null && !hasPair) {
+        throw new OxygenError("missing_target", "Pass --run-id for a single run, or --provider and --object for a standing sync config.", { exitCode: 1 });
+    }
     const params = new URLSearchParams();
-    params.set("run_id", runId);
+    if (runId !== null) {
+        params.set("run_id", runId);
+    }
+    else {
+        params.set("provider", provider);
+        params.set("object", object);
+    }
     return `/api/cli/crm/sync/status?${params.toString()}`;
 }
 function buildCrmSyncLinksPath(object, rowId) {
@@ -1625,7 +1682,7 @@ export function createProgram() {
         await handleAsyncAction("crm automation audit", options, () => requestOxygen(buildCrmAutomationAuditPath(options)));
     })))
         .addCommand(new Command("sync")
-        .description("Import records from a connected CRM (HubSpot/Attio) into Oxygen CRM objects, and inspect import runs and provider links.")
+        .description("Bidirectionally sync a connected CRM (HubSpot/Attio) with Oxygen CRM objects: import records, configure a standing two-way sync, run a reconciliation cycle, and inspect runs and provider links.")
         .addCommand(new Command("import")
         .description("Import provider records into an Oxygen CRM object as a durable workflow run. Defaults to dry-run.")
         .argument("<provider>", "Connected CRM to import from: hubspot or attio.")
@@ -1642,13 +1699,84 @@ export function createProgram() {
             method: "POST",
             body: buildCrmSyncImportBody(provider, options),
         }));
+    }))
+        .addCommand(new Command("configure")
+        .description("Configure a standing bidirectional sync for one CRM object pair. Defaults to dry-run, which returns a real preview of the next cycle.")
+        .requiredOption("--provider <provider>", "Connected CRM: hubspot or attio.")
+        .requiredOption("--object <object>", "Provider object: hubspot contacts|companies, or attio people|companies.")
+        .option("--direction <direction>", "Sync direction: inbound, outbound, or bidirectional. Defaults to bidirectional.")
+        .option("--cron <cron>", "Cron expression for the scheduled reconciliation cadence, e.g. '*/15 * * * *'.")
+        .option("--timezone <tz>", "IANA timezone the cron schedule runs in, e.g. America/New_York. Defaults to UTC.")
+        .option("--max-rows <n>", "Per-cycle row cap. The real volume brake on provider writes (BYOK writes cost 0 Oxygen credits).")
+        .option("--max-credits <n>", "Managed-credit + external-quota cap per cycle.")
+        .option("--approved", "Confirm a live configuration after inspecting a dry run.")
+        .option("--dry-run", "Preview the configuration and next cycle without writing. Default.")
+        .option("--live", "Write the configuration. Requires --approved and --max-credits.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("crm sync configure", options, () => requestOxygen("/api/cli/crm/sync/configure", {
+            method: "POST",
+            body: buildCrmSyncConfigureBody(options),
+        }));
+    }))
+        .addCommand(new Command("run")
+        .description("Run one bidirectional reconciliation cycle for a configured CRM object pair as a durable workflow run. Defaults to dry-run.")
+        .requiredOption("--provider <provider>", "Connected CRM: hubspot or attio.")
+        .requiredOption("--object <object>", "Provider object: hubspot contacts|companies, or attio people|companies.")
+        .option("--max-rows <n>", "Per-cycle row cap. The real volume brake on provider writes (BYOK writes cost 0 Oxygen credits).")
+        .option("--max-credits <n>", "Managed-credit + external-quota cap for this cycle.")
+        .option("--approved", "Confirm a live cycle after inspecting a dry run.")
+        .option("--dry-run", "Preview the cycle without pulling or pushing. Default.")
+        .option("--live", "Run the live reconciliation cycle. Requires --approved and --max-credits.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("crm sync run", options, () => requestOxygen("/api/cli/crm/sync/run", {
+            method: "POST",
+            body: buildCrmSyncRunBody(options),
+        }));
+    }))
+        .addCommand(new Command("enable")
+        .description("Enable continuous (scheduled) bidirectional sync for one CRM object pair: arms the cron trigger + the standing write permission, and runs an immediate first cycle. Always live — requires --approved, --max-credits, and --max-rows.")
+        .requiredOption("--provider <provider>", "Connected CRM: hubspot or attio.")
+        .requiredOption("--object <object>", "Provider object: hubspot contacts|companies, or attio people|companies.")
+        .option("--direction <direction>", "Sync direction: inbound, outbound, or bidirectional. Defaults to bidirectional.")
+        .option("--cron <cron>", "Cron expression for the cadence, e.g. '*/15 * * * *'. Defaults to every 15 minutes.")
+        .option("--timezone <tz>", "IANA timezone the cron runs in. Defaults to UTC.")
+        .requiredOption("--max-rows <n>", "Per-cycle row cap — the volume brake on provider writes (required).")
+        .requiredOption("--max-credits <n>", "Managed-credit + external-quota cap per cycle (required).")
+        .option("--approved", "Confirm enabling scheduled provider writes after inspecting a dry run.")
+        .option("--no-run-now", "Do not run an immediate first cycle after enabling.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("crm sync enable", options, () => requestOxygen("/api/cli/crm/sync/enable", {
+            method: "POST",
+            body: buildCrmSyncEnableBody(options),
+        }));
+    }))
+        .addCommand(new Command("disable")
+        .description("Disable the scheduled sync for one CRM object pair: stops the cron trigger and revokes the standing write permission. The standing config (direction, cadence, mappings, watermarks) is preserved for re-enable.")
+        .requiredOption("--provider <provider>", "Connected CRM: hubspot or attio.")
+        .requiredOption("--object <object>", "Provider object: hubspot contacts|companies, or attio people|companies.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("crm sync disable", options, () => requestOxygen("/api/cli/crm/sync/disable", {
+            method: "POST",
+            body: buildCrmSyncDisableBody(options),
+        }));
     }))
         .addCommand(new Command("status")
-        .description("Show the status of a CRM import workflow run.")
-        .argument("<run_id>", "Import workflow run id.")
+        .description("Show a CRM sync status: pass --run-id for one workflow run, or --provider/--object for the standing sync config (cadence, watermarks, last-cycle counts).")
+        .argument("[run_id]", "Workflow run id. Equivalent to --run-id.")
+        .option("--run-id <id>", "Workflow run id to read a single run.")
+        .option("--provider <provider>", "Connected CRM (hubspot|attio) for a standing-config read. Use with --object.")
+        .option("--object <object>", "Provider object for a standing-config read. Use with --provider.")
         .option("--json", "Print a JSON envelope.")
         .action(async (runId, options) => {
-        await handleAsyncAction("crm sync status", options, () => requestOxygen(buildCrmSyncStatusPath(runId)));
+        const resolved = {
+            ...options,
+            ...(runId !== undefined && readOption(options.runId) === null ? { runId } : {}),
+        };
+        await handleAsyncAction("crm sync status", resolved, () => requestOxygen(buildCrmSyncConfigStatusPath(resolved)));
     }))
         .addCommand(new Command("links")
         .description("Show provider record links (HubSpot/Attio ids) mapped to one Oxygen CRM record.")
@@ -1908,6 +2036,15 @@ export function createProgram() {
                 ...(options.includeArchived ? { include_archived: true } : {}),
             },
         }));
+    }))
+        .addCommand(new Command("tidy-suggest")
+        .description("Read-only tidy analysis for a workspace table: duplicate columns, formatting issues, hide candidates, and value-sanity findings.")
+        .argument("<table>", "Table id or slug.")
+        .option("--limit <n>", "Maximum rows to sample for the analysis. Defaults to and is capped at 5000.")
+        .option("--categories <csv>", "Comma-separated subset of duplicates,formatting,hide,valueSanity. Defaults to all four.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleTablesTidySuggestAction(table, options);
     }))
         .addCommand(new Command("activity")
         .description("Show background runs active on a workspace table right now, with a worker-queue health rollup.")
@@ -2816,6 +2953,29 @@ export function createProgram() {
             method: "POST",
             body: { table, column },
         }));
+    }))
+        .addCommand(new Command("reorder")
+        .description("Move a workspace column to a new position, by absolute index or relative to another column.")
+        .argument("<table>", "Table id or slug.")
+        .argument("<column>", "Column id or key to move.")
+        .option("--position <n>", "Target zero-based index for the column.")
+        .option("--before <column>", "Place the column immediately before this column id or key.")
+        .option("--after <column>", "Place the column immediately after this column id or key.")
+        .option("--dry-run", "Return the would-be position without persisting the reorder.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, column, options) => {
+        await handleAsyncAction("columns reorder", options, async () => {
+            const position = await resolveColumnReorderPosition(table, options);
+            return requestOxygen("/api/cli/tables/columns/reorder", {
+                method: "POST",
+                body: {
+                    table,
+                    column,
+                    position,
+                    ...(options.dryRun ? { dry_run: true } : {}),
+                },
+            });
+        });
     }));
     program
         .command("action-column")
@@ -4430,6 +4590,7 @@ export function createProgram() {
         .addCommand(new Command("connect")
         .description("Get a Unipile hosted-auth URL to connect a new LinkedIn account (or reconnect with --reconnect). Open the URL in a browser to complete authentication.")
         .option("--reconnect <connection_id>", "Reconnect an existing connection instead of creating a new one. Accepts a connection id.")
+        .option("--sales-nav", "Request Classic + Sales Navigator access during Unipile hosted authentication.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("senders connect", options, () => {
@@ -4438,6 +4599,7 @@ export function createProgram() {
                 method: "POST",
                 body: {
                     ...(reconnect ? { reconnect_connection_id: reconnect } : {}),
+                    ...(options.salesNav ? { sales_nav: true } : {}),
                 },
             });
         });
@@ -4497,8 +4659,9 @@ export function createProgram() {
         .option("--relations-reads-per-day <n>", "Daily cap on relations/connections list reads (scrape protection).")
         .option("--messages-reads-per-day <n>", "Daily cap on chat and message-history reads.")
         .option("--searches-per-day <n>", "Daily cap on LinkedIn search executions.")
+        .option("--sales-nav-search-results-per-day <n>", "Daily cap on Sales Navigator search result rows fetched.")
         .option("--api-reads-per-day <n>", "Daily cap on all other LinkedIn API reads.")
-        .option("--total-reads-per-day <n>", "Daily cap across all read types.")
+        .option("--total-reads-per-day <n>", "Daily cap across all read units.")
         .option("--min-spacing-seconds <n>", "Minimum seconds between actions.")
         .option("--spacing-jitter-seconds <n>", "Random jitter seconds added to action spacing.")
         .option("--timezone <tz>", "IANA timezone the daily action counters reset in, e.g. America/New_York.")
@@ -4552,9 +4715,12 @@ export function createProgram() {
     program.addCommand(new Command("engagement")
         .description("Harvest a LinkedIn post's engagers (reactors + commenters) into an enrollable CRM static list. The harvest runs as a slow, durable background drip under a dedicated conservative read budget — it never bursts and never starves the sequencer's own reads.")
         .addCommand(new Command("harvest")
-        .description("Start (or re-arm) a harvest of a post's engagers into a CRM static list you can enroll into a sequence. Engagers drip into the list over many ticks; poll `engagement status` to watch it fill. No messages are sent and no Oxygen credits are charged.")
-        .requiredOption("--post <social_id>", "Composite post social_id from `oxygen posts get` (NOT the activity URN).")
+        .description("Start (or re-arm) a harvest of a post's engagers into a CRM static list you can enroll into a sequence. Engagers drip into the list 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.")
         .requiredOption("--list <slug>", "CRM static list slug to fill (created or reused over the people object).")
+        .option("--source <source>", "cookieless|unipile. Defaults to cookieless when a public post URL is supplied.")
+        .option("--post-url <url>", "Public LinkedIn post URL for cookieless harvesting when --post is a social id.")
+        .option("--max-credits <credits>", "Required for cookieless harvesting; caps managed scraper spend for this armed run.")
         .option("--recurring", "Keep re-polling the newest pages for new engagers (default: one walk).")
         .option("--account <ref>", "Sender account that reads (sender id, connection id, or Unipile account id). Omit for the org default.")
         .option("--no-reactions", "Skip reactors.")
@@ -4565,11 +4731,17 @@ export function createProgram() {
             const post = readOption(options.post);
             const list = readOption(options.list);
             const account = readOption(options.account);
+            const source = readOption(options.source);
+            const postUrl = readOption(options.postUrl);
+            const maxCredits = readPositiveNumber(options.maxCredits);
             return requestOxygen("/api/cli/linkedin/engagement/harvest", {
                 method: "POST",
                 body: {
                     ...(post ? { post } : {}),
                     ...(list ? { list } : {}),
+                    ...(source ? { source } : {}),
+                    ...(postUrl ? { post_url: postUrl } : {}),
+                    ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}),
                     ...(options.recurring ? { recurring: true } : {}),
                     ...(account ? { account } : {}),
                     // commander sets reactions/comments=false for --no-* flags.
@@ -4743,13 +4915,15 @@ export function createProgram() {
         .option("--responses-only", "Email only: only conversations with an inbound reply (never sent-only threads).")
         .option("--bucket <bucket>", "Email only: primary or others (superseded by --segment).")
         .option("--segment <segment>", "Email only: top-tab folder — primary, others, sent, warmup, or dmarc.")
-        .option("--status <keys>", "Email only: comma-separated status keys (e.g. interested,meeting_booked).")
+        .option("--status <keys>", "Comma-separated status keys (e.g. interested,meeting_booked). Cross-channel — filters email + LinkedIn + WhatsApp by the shared taxonomy.")
+        .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("--sequence-id <ids>", "Email only: comma-separated campaign (sequence) ids.")
         .option("--provider <providers>", "Email only: comma-separated providers (google,microsoft).")
         .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.")
+        .option("--search <text>", "Filter by attendee name or last-message text. Cross-channel.")
         .option("--include-archived", "Include archived conversations.")
         .option("--limit <n>", "Maximum conversations to return (1-200). Defaults to 50.")
         .option("--json", "Print a JSON envelope.")
@@ -4771,6 +4945,8 @@ export function createProgram() {
                 ["segment", "segment"],
                 ["channels", "channels"],
                 ["status", "status"],
+                ["since", "since"],
+                ["until", "until"],
                 ["sequenceId", "sequence_id"],
                 ["provider", "provider"],
                 ["domain", "domain"],
@@ -4853,26 +5029,31 @@ export function createProgram() {
         .description("Run analysis on a conversation now: status + sentiment + a drafted reply (Oxygen's default model). The worker also does this automatically on inbound conversations.")
         .argument("<conversation>", "Conversation id, Unipile chat id, or (email) Zapbox thread id.")
         .option("--channel <channel>", "Inbox channel: email (default), linkedin, or whatsapp.")
+        .option("--force", "Re-analyze even if the conversation was already classified (an explicit paid re-classification; spends one managed credit). Without it, an already-analyzed email is a free no-op. DMs always re-analyze.")
         .option("--json", "Print a JSON envelope.")
         .action(async (conversation, options) => {
         await handleAsyncAction("inbox analyze", options, () => {
             const channel = readOption(options.channel) ?? "email";
             return requestOxygen(`/api/cli/inbox/${encodeURIComponent(conversation)}/analyze`, {
                 method: "POST",
-                body: { channel },
+                body: { channel, ...(options.force ? { force: true } : {}) },
             });
         });
     }))
         .addCommand(new Command("archive")
-        .description("Archive an email conversation (triage it out of the inbox). --unarchive restores it.")
-        .argument("<conversation>", "Conversation id or Zapbox thread id.")
+        .description("Archive a conversation (triage it out of the inbox). --unarchive restores it. --channel linkedin/whatsapp archives a DM.")
+        .argument("<conversation>", "Conversation id, Unipile chat id, or (email) Zapbox thread id.")
+        .option("--channel <channel>", "Inbox channel: email (default), linkedin, or whatsapp.")
         .option("--unarchive", "Restore the conversation instead of archiving it.")
         .option("--json", "Print a JSON envelope.")
         .action(async (conversation, options) => {
-        await handleAsyncAction("inbox archive", options, () => requestOxygen(`/api/cli/inbox/${encodeURIComponent(conversation)}/archive`, {
-            method: "POST",
-            body: { channel: "email", archived: !options.unarchive },
-        }));
+        await handleAsyncAction("inbox archive", options, () => {
+            const channel = readOption(options.channel) ?? "email";
+            return requestOxygen(`/api/cli/inbox/${encodeURIComponent(conversation)}/archive`, {
+                method: "POST",
+                body: { channel, archived: !options.unarchive },
+            });
+        });
     }))
         .addCommand(new Command("sync")
         .description("Force a backstop inbox sync from Unipile for all active sender accounts (pulls recent chats + messages into the unibox).")
@@ -4941,6 +5122,36 @@ export function createProgram() {
                 body: { channel, confirm: Boolean(options.yes) },
             });
         });
+    }))
+        .addCommand(new Command("bulk")
+        .description("Bulk-apply one triage action — set-status / archive / unarchive — across up to 100 hand-picked conversations (the ids `inbox list` returns) in one call. Without --yes, previews the matched/would-change counts (no mutation). With --yes, applies it. --channel scopes the ids (email default; run once per channel).")
+        .requiredOption("--action <action>", "set-status, archive, or unarchive.")
+        .requiredOption("--ids <ids>", "Comma-separated conversation ids (the uuids `inbox list` returns). Max 100.")
+        .option("--status <key>", "Required for --action set-status: the status label key to set (e.g. interested).")
+        .option("--channel <channel>", "Inbox channel the ids belong to: email (default), linkedin, or whatsapp.")
+        .option("--yes", "Apply the action. Without this flag, returns a preview of the counts only.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("inbox bulk", options, () => {
+            // CLI uses hyphenated `set-status` for ergonomics; the API wants `set_status`.
+            const action = (readOption(options.action) ?? "").replace(/-/g, "_");
+            const channel = readOption(options.channel) ?? "email";
+            const status = readOption(options.status);
+            const ids = (readOption(options.ids) ?? "")
+                .split(",")
+                .map((id) => id.trim())
+                .filter(Boolean);
+            return requestOxygen("/api/cli/inbox/bulk", {
+                method: "POST",
+                body: {
+                    action,
+                    channel,
+                    conversation_ids: ids,
+                    ...(status ? { status } : {}),
+                    ...(options.yes ? { approved: true } : {}),
+                },
+            });
+        });
     }))
         .addCommand(new Command("labels")
         .description("Manage inbox status labels (the Instantly-style system set + custom labels).")
@@ -9582,6 +9793,132 @@ function formatSequenceVariants(data) {
     lines.push("");
     return lines.join("\n");
 }
+// `columns reorder` accepts either an absolute --position or a relative
+// --before/--after naming a sibling column. The relative form is resolved
+// client-side into an absolute index against the table's current column order
+// (fetched via /api/cli/tables/describe — the same describe the other column
+// commands read) so the server only ever receives a single numeric position.
+// Exactly one of the three flags must be supplied.
+async function resolveColumnReorderPosition(table, options) {
+    const before = readOption(options.before);
+    const after = readOption(options.after);
+    const explicit = readNonNegativeInt(options.position);
+    const provided = [explicit !== undefined, Boolean(before), Boolean(after)].filter(Boolean).length;
+    if (provided === 0) {
+        throw new OxygenError("invalid_request", "Provide --position <n>, --before <column>, or --after <column>.", { exitCode: 1 });
+    }
+    if (provided > 1) {
+        throw new OxygenError("invalid_request", "Pass only one of --position, --before, or --after.", { exitCode: 1 });
+    }
+    if (explicit !== undefined)
+        return explicit;
+    const reference = (before ?? after);
+    const describe = await requestOxygen("/api/cli/tables/describe", { method: "POST", body: { table } });
+    const columns = describe.columns ?? [];
+    const index = columns.findIndex((candidate) => candidate.id === reference || candidate.key === reference);
+    if (index < 0) {
+        throw new OxygenError("invalid_request", `Column "${reference}" was not found on table "${table}".`, { details: { table, column: reference }, exitCode: 1 });
+    }
+    // --before lands the column at the reference's index; --after lands it one slot later.
+    return before ? index : index + 1;
+}
+// `tables tidy-suggest` is a read-only analysis (no credits, no writes): it
+// surfaces duplicate columns, formatting inconsistencies, hide candidates, and
+// value-sanity findings so the caller can pick which reversible cleanup to run
+// next. --json returns the raw report envelope; the default rendering compacts
+// the four sections for a terminal reader and echoes the deep-link.
+async function handleTablesTidySuggestAction(table, options) {
+    try {
+        const limit = readPositiveInt(options.limit);
+        const categories = readCsvOption(options.categories);
+        const data = await requestOxygen("/api/cli/tables/tidy/suggest", {
+            method: "POST",
+            body: {
+                table,
+                ...(limit ? { limit } : {}),
+                ...(categories.length ? { categories } : {}),
+            },
+        });
+        if (options.json) {
+            writeJson(success("tables tidy-suggest", data));
+            return;
+        }
+        process.stdout.write(formatTidySuggestions(data));
+    }
+    catch (error) {
+        const failure = toFailure("tables tidy-suggest", error);
+        writeJson(failure);
+        writeMaxCreditsHint(error);
+        process.exitCode = error instanceof OxygenError ? error.exitCode : 1;
+    }
+}
+function formatTidyCount(value) {
+    return typeof value === "number" && Number.isFinite(value) ? String(value) : "0";
+}
+function formatTidyPercent(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return "—";
+    return `${(value * 100).toFixed(0)}%`;
+}
+function formatTidySuggestions(data) {
+    const styles = ansi(output.isTTY === true && !process.env.NO_COLOR);
+    const duplicates = Array.isArray(data.duplicateColumns) ? data.duplicateColumns : [];
+    const formatting = Array.isArray(data.formattingIssues) ? data.formattingIssues : [];
+    const hide = Array.isArray(data.hideSuggestions) ? data.hideSuggestions : [];
+    const valueSanity = Array.isArray(data.valueSanity) ? data.valueSanity : [];
+    const lines = [
+        "",
+        `${styles.bold("Table tidy suggestions")} ${styles.dim(`(sampled ${formatTidyCount(data.sampledRows)} of ${formatTidyCount(data.rowCount)} rows)`)}`,
+    ];
+    lines.push("", styles.bold(`Duplicate columns (${duplicates.length})`));
+    if (duplicates.length === 0) {
+        lines.push(`  ${styles.dim("None")}`);
+    }
+    else {
+        for (const dup of duplicates) {
+            const loser = dup.loserKey ?? dup.loserColumnId ?? "?";
+            const survivor = dup.survivorKey ?? dup.survivorColumnId ?? "?";
+            lines.push(`  ${loser} ${styles.dim("→ duplicate of")} ${survivor} ${styles.dim(`(${formatTidyPercent(dup.similarity)} match, ${dup.recommendation ?? "review"})`)}`);
+        }
+    }
+    lines.push("", styles.bold(`Formatting issues (${formatting.length})`));
+    if (formatting.length === 0) {
+        lines.push(`  ${styles.dim("None")}`);
+    }
+    else {
+        for (const issue of formatting) {
+            const sampleCount = Array.isArray(issue.sampleRowIds) ? issue.sampleRowIds.length : 0;
+            const column = issue.columnKey ?? issue.columnId ?? "?";
+            lines.push(`  ${column} ${styles.dim(`— ${issue.issue ?? "issue"}`)}${issue.detail ? `: ${issue.detail}` : ""} ${styles.dim(`(${sampleCount} sample row(s))`)}`);
+        }
+    }
+    lines.push("", styles.bold(`Hide suggestions (${hide.length})`));
+    if (hide.length === 0) {
+        lines.push(`  ${styles.dim("None")}`);
+    }
+    else {
+        for (const suggestion of hide) {
+            const column = suggestion.columnKey ?? suggestion.columnId ?? "?";
+            lines.push(`  ${column} ${styles.dim(`— ${suggestion.reason ?? "hide"} (${formatTidyPercent(suggestion.fillRate)} filled)`)}`);
+        }
+    }
+    lines.push("", styles.bold(`Value-sanity findings (${valueSanity.length})`));
+    if (valueSanity.length === 0) {
+        lines.push(`  ${styles.dim("None")}`);
+    }
+    else {
+        for (const finding of valueSanity) {
+            const column = finding.columnKey ?? finding.columnId ?? "?";
+            lines.push(`  ${column} ${styles.dim(`row ${finding.rowId ?? "?"} — ${finding.reason ?? "check value"}`)}`);
+        }
+    }
+    const link = data.deepLink ?? data.web_url ?? data.url;
+    if (link) {
+        lines.push("", styles.dim(`View table: ${link}`));
+    }
+    lines.push("");
+    return lines.join("\n");
+}
 function formatWhoami(identity, context) {
     const styles = ansi(output.isTTY === true && !process.env.NO_COLOR);
     const email = identity.user.email ?? identity.user.id;
@@ -10036,6 +10373,7 @@ options) {
     setLimit("relations_reads_per_day", options.relationsReadsPerDay);
     setLimit("messages_reads_per_day", options.messagesReadsPerDay);
     setLimit("searches_per_day", options.searchesPerDay);
+    setLimit("sales_nav_search_results_per_day", options.salesNavSearchResultsPerDay);
     setLimit("api_reads_per_day", options.apiReadsPerDay);
     setLimit("total_reads_per_day", options.totalReadsPerDay);
     setLimit("min_action_spacing_seconds", options.minSpacingSeconds);