@oxygen-agent/cli 1.922.14 → 1.948.1

package/dist/index.js

@@ -7,6 +7,10 @@ import { createInterface } from "node:readline/promises";
 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 { 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";
@@ -196,8 +200,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)
@@ -439,6 +448,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
@@ -456,6 +492,29 @@ function writeDryRunNotice(data) {
         process.stderr.write(`${block.message}\n`);
     if (typeof block.next_step === "string")
         process.stderr.write(`${block.next_step}\n`);
+    // The server's next_step quotes the MANAGED price, because the live gate's
+    // `billedTool` reads the descriptor and never the credential mode. On a
+    // customer's own key that number is not what anyone pays, so say so instead
+    // of leaving a managed credit estimate as the last word on a BYOK preview.
+    // The `--max-credits` ceiling in that line is still required by the gate, so
+    // the command stays copy-pasteable rather than being edited into a 400.
+    const byok = readByokCredentialMode(data);
+    if (byok) {
+        process.stderr.write(`That estimate is the managed-key price. This run uses credential_mode ${byok}, so Oxygen charges no credits for it — your provider bills you directly. The live gate still requires --max-credits as a ceiling.\n`);
+    }
+}
+/**
+ * The tool run's credential mode when the call is NOT on Oxygen's managed key
+ * — the one fact that decides whether a quoted credit estimate means anything.
+ * Null for managed runs and for payloads with no billing block at all.
+ */
+function readByokCredentialMode(data) {
+    const result = asPayloadRecord(asPayloadRecord(data)?.result);
+    const billing = asPayloadRecord(asPayloadRecord(result?.meta)?.billing);
+    const mode = billing?.credential_mode;
+    if (typeof mode !== "string" || mode.length === 0 || mode === "managed")
+        return null;
+    return mode;
 }
 // An `oxy_live_` key can only ever answer for the one workspace it is bound to,
 // so `orgs list` returns a single row and `orgs use` refuses — both truthfully,
@@ -554,7 +613,12 @@ function writeCreditsReceipt(data) {
         return;
     }
     if (typeof block.estimated_credits === "number") {
-        process.stderr.write(`estimated ${block.estimated_credits.toLocaleString("en-US")} credits for a live run${remaining !== null ? `, ${remaining} available` : ""}\n`);
+        // A BYOK preview spends zero Oxygen credits, so quoting the managed
+        // estimate as "for a live run" is simply wrong; name the mode instead.
+        const byok = readByokCredentialMode(data);
+        process.stderr.write(byok
+            ? `estimated 0 Oxygen credits for a live run on your own key (${byok})${remaining !== null ? `, ${remaining} available` : ""}\n`
+            : `estimated ${block.estimated_credits.toLocaleString("en-US")} credits for a live run${remaining !== null ? `, ${remaining} available` : ""}\n`);
     }
 }
 // A disabled workflow is a customer's automation at zero, and `status:
@@ -1636,6 +1700,8 @@ function buildPublishingPostsListPath(options) {
         approval_status: options.approvalStatus,
         tag: options.tag,
         provider: options.provider,
+        sender_account_id: options.sender,
+        cursor: options.cursor,
         limit: options.limit,
     };
     for (const [key, value] of Object.entries(filters)) {
@@ -3606,7 +3672,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
     }));
     program
         .command("projects")
-        .description("Manage table projects. Inspect contents with `oxygen tables list --project <project>`.")
+        .description("Manage table folders (projects). Inspect contents with `oxygen tables list --project <project>`.")
         .addCommand(new Command("list")
         .description("List table projects in the current tenant database.")
         .option("--json", "Print a JSON envelope.")
@@ -3643,11 +3709,12 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("delete")
-        .description("Delete an empty non-General table project. Defaults to dry-run; --live requires --confirm.")
+        .description("Delete a non-General folder and its tables. Restoring any deleted table with `oxygen tables restore` before the purge date also restores the folder. Defaults to dry-run; --live requires --confirm and the preview's table IDs.")
         .argument("<project>", "Project slug or id.")
         .option("--dry-run", "Preview whether the project can be deleted without writing. Default.")
         .option("--live", "Delete the project after inspecting the dry-run preview. Requires --confirm.")
         .option("--confirm", "Confirm the live delete.")
+        .option("--expected-table-ids <ids>", "Comma-separated table IDs from the preview. Required for nonempty folders; refuses if contents changed.")
         .option("--json", "Print a JSON envelope.")
         .action(async (project, options) => {
         await handleAsyncAction("projects delete", options, () => {
@@ -3660,6 +3727,9 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
                 body: {
                     mode,
                     ...(mode === "live" ? { confirm: true } : {}),
+                    ...(options.expectedTableIds !== undefined
+                        ? { expected_table_ids: splitCommaList(options.expectedTableIds) }
+                        : {}),
                 },
             });
         });
@@ -3761,6 +3831,8 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--approval-status <status>", "Filter by draft, needs_approval, approved, or rejected.")
         .option("--tag <tag>", "Only posts carrying this workspace tag.")
         .option("--provider <provider>", "Filter by provider: linkedin, x, instagram, tiktok, facebook, or youtube.")
+        .option("--sender <sender_account_id>", "Only posts belonging to this connected sender in the active workspace.")
+        .option("--cursor <cursor>", "Continue from next_cursor with the same filters.")
         .option("--limit <n>", "Maximum posts to return.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
@@ -3855,7 +3927,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         }));
     }))
         .addCommand(new Command("delete")
-        .description("Delete a never-attempted post from the queue (draft, scheduled, or queued with no publish attempts). A post that was ever attempted — published, publishing, failed, or re-armed after a provider error — is refused: cancel it instead, so its attempt history is kept. To remove a LinkedIn post that already went live, use `oxygen posts delete`.")
+        .description("Permanently delete the OXYGEN copy and its settled history, keeping the live platform post intact. Supports never-attempted draft/scheduled/queued posts, settled canceled unpublished posts, and settled published copies. Published deletions stay excluded from background discovery. Cancel failed or re-armed posts first. In-flight publishing, replies, amplification, and active amplification spend accounting remain protected. Live LinkedIn deletion is a separate action using `oxygen posts delete`.")
         .argument("<post_id>", "Scheduled post id.")
         .option("--json", "Print a JSON envelope.")
         .action(async (postId, options) => {
@@ -4973,7 +5045,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.")
@@ -4987,14 +5060,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.")
@@ -5022,10 +5096,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
@@ -5034,7 +5108,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .addCommand(new Command("create")
         .description("Create a real Postgres-backed workspace table. Free — 0 Oxygen credits. To create a table and import a file in one step, use `tables import --create <name>`.")
         .argument("<name>", "Display name for the table.")
-        .requiredOption("--columns-json <json>", 'JSON array of column definitions, e.g. [{"key":"name","label":"Name","dataType":"text"},{"key":"domain","label":"Domain","dataType":"text"}]. Inspect an existing shape with `oxygen tables describe <table>`.')
+        .requiredOption("--columns-json <json>", 'Required nonempty JSON array of column definitions, e.g. [{"key":"name","label":"Name","dataType":"text"},{"key":"domain","label":"Domain","dataType":"text"}]. Inspect an existing shape with `oxygen tables describe <table>`.')
         .option("--project <project>", "Project id or slug. Defaults to General.")
         .option("--json", "Print a JSON envelope.")
         .action(async (name, options) => {
@@ -5438,6 +5512,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.")
@@ -6280,11 +6411,46 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
     program
         .command("knowledge")
         .description("Company knowledge wiki: slug-addressed pages, a [[wikilink]] graph, and a decision log.")
+        .addCommand(new Command("folders")
+        .description("Browse, create, and move nested folders for knowledge pages; slugs and wikilinks stay stable.")
+        .addCommand(new Command("list")
+        .description("List workspace folders and page locations, including empty folders. Read-only, 0 credits.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("knowledge folders list", options, () => requestOxygen("/api/cli/knowledge/folders"));
+    }))
+        .addCommand(new Command("create")
+        .description("Create a persistent knowledge folder, optionally inside another folder.")
+        .requiredOption("--name <name>", "Folder name.")
+        .option("--parent <folder_id>", "Parent folder UUID from knowledge folders list. Omit for root.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("knowledge folders create", options, () => requestOxygen("/api/cli/knowledge/folders/create", {
+            method: "POST",
+            body: {
+                name: options.name,
+                ...(readOption(options.parent) ? { parentId: readOption(options.parent) } : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("move")
+        .description("Move a folder and its contents to another folder or the workspace root.")
+        .argument("<id>", "Folder UUID from knowledge folders list.")
+        .requiredOption("--parent <folder_id|root>", "Destination folder UUID, or root.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (id, options) => {
+        await handleAsyncAction("knowledge folders move", options, () => requestOxygen("/api/cli/knowledge/folders/move", {
+            method: "POST",
+            body: { id, parentId: options.parent === "root" ? null : options.parent },
+        }));
+    })))
         .addCommand(new Command("page")
         .description("Knowledge wiki pages (slug-addressed, revision-guarded).")
         .addCommand(new Command("upsert")
         .description("Create or update a knowledge wiki page.")
         .option("--slug <slug>", "Stable page slug to create or address. Omit to create by title.")
+        .option("--folder <folder_id>", "Folder UUID, or root to remove folder placement. Omit to preserve the current folder.")
+        .option("--create-only", "Fail if the page already exists instead of updating it.")
         .option("--id <page_id>", "Existing page UUID to update. Omit to create.")
         .option("--type <type>", "Page type (positioning, competitor, research_note, playbook, strategy, other). Defaults to other on create.")
         .option("--title <title>", "Page title. Required on create.")
@@ -6307,7 +6473,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("get")
-        .description("Read one knowledge wiki page by slug or UUID.")
+        .description("Read one knowledge wiki page by slug or UUID. Read-only, 0 credits.")
         .argument("<slug_or_id>", "Page slug or UUID.")
         .option("--json", "Print a JSON envelope.")
         .action(async (slugOrId, options) => {
@@ -6317,7 +6483,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         }));
     }))
         .addCommand(new Command("list")
-        .description("List knowledge wiki pages.")
+        .description("List knowledge wiki pages. Read-only, 0 credits.")
         .option("--type <type>", "Filter by page type.")
         .option("--status <status>", "Filter by draft, active, or archived.")
         .option("--tags <csv>", "Comma-separated tags that must be present.")
@@ -6365,7 +6531,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("revisions")
-        .description("List the revision history of a knowledge wiki page, newest first.")
+        .description("List the revision history of a knowledge wiki page, newest first. Read-only, 0 credits.")
         .argument("<slug_or_id>", "Page slug or UUID.")
         .option("--limit <n>", "Maximum revisions to return.")
         .option("--json", "Print a JSON envelope.")
@@ -6382,7 +6548,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("revision")
-        .description("Read one full revision snapshot of a knowledge wiki page.")
+        .description("Read one full revision snapshot of a knowledge wiki page. Read-only, 0 credits.")
         .argument("<slug_or_id>", "Page slug or UUID.")
         .argument("<revision>", "Revision number.")
         .option("--json", "Print a JSON envelope.")
@@ -6404,7 +6570,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     })))
         .addCommand(new Command("search")
-        .description("Full-text search across knowledge wiki pages, ranked by relevance.")
+        .description("Search wiki pages by meaning and keywords. Read-only, 0 credits. Plain language uses hybrid retrieval when available; check match_type and semantic_status. Quotes, OR, and exclusions stay lexical. If the platform-funded embedding allowance is unavailable, keyword search still works.")
         .argument("<query>", "Search text. Supports quoted phrases, OR, and -exclude.")
         .option("--type <type>", "Filter by page type.")
         .option("--status <status>", "Filter by draft, active, or archived.")
@@ -6418,7 +6584,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         }));
     }))
         .addCommand(new Command("index")
-        .description("Compact wiki index: each page's slug, one-liner, tags, link degree, plus type/status counts over the whole wiki. Lists the 200 most recently updated pages by default.")
+        .description("Compact wiki index: each page's slug, one-liner, tags, link degree, plus type/status counts over the whole wiki. Lists the 200 most recently updated pages by default. Read-only, 0 credits. semantic.budget is Oxygen's platform-funded embedding safety allowance; its dollar and query counters are Oxygen's spend, never charges against your credits.")
         .option("--limit <n>", "Maximum pages to list. Defaults to 200; hard cap is 1000. Counts always cover the whole wiki.")
         .option("--all", "List every page instead of the most recently updated window.")
         .option("--json", "Print a JSON envelope.")
@@ -6438,7 +6604,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("graph")
-        .description("Knowledge graph of pages and their [[wikilink]] edges. Pass --center to render one page's local neighborhood instead of the whole graph.")
+        .description("Knowledge graph of pages and their [[wikilink]] edges. Pass --center to render one page's local neighborhood instead of the whole graph. Read-only, 0 credits.")
         .option("--max-nodes <n>", "Maximum nodes to include in the graph.")
         .option("--center <slug_or_id>", "Center the graph on one page and show only its neighborhood (local mode).")
         .option("--depth <n>", "Local-graph hop depth (1-3, default 1). Only applies with --center.")
@@ -6450,7 +6616,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         }));
     }))
         .addCommand(new Command("lint")
-        .description("Structural wiki health report: orphans (unfilled seed stubs excluded), dead-ends, unresolved links, contradictions (disputed pages, conflicting trust tags, competing live-copy pages), missing canonicals, untagged pages, duplicate titles, oversized hubs, unfilled seed stubs (total plus the most-linked-to), researchable stubs, decisions missing a reversal condition, stale pages (untouched or superseded by newer sources), oversized bodies, and aged proposals.")
+        .description("Read-only structural wiki health report, 0 credits: orphans (unfilled seed stubs excluded), dead-ends, unresolved links, contradictions (disputed pages, conflicting trust tags, competing live-copy pages), missing canonicals, untagged pages, duplicate titles, oversized hubs, unfilled seed stubs (total plus the most-linked-to), researchable stubs, decisions missing a reversal condition, stale pages (untouched or superseded by newer sources), oversized bodies, and aged proposals.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("knowledge lint", options, () => requestOxygen("/api/cli/knowledge/lint"));
@@ -6471,7 +6637,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .addCommand(new Command("log")
         .description("Knowledge decision and activity log.")
         .addCommand(new Command("list")
-        .description("List knowledge log entries, newest first.")
+        .description("List knowledge log entries, newest first. Read-only, 0 credits.")
         .option("--cursor <cursor>", "Pagination cursor from a previous page.")
         .option("--limit <n>", "Maximum log entries to return.")
         .option("--json", "Print a JSON envelope.")
@@ -6495,7 +6661,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         }));
     })))
         .addCommand(new Command("proposals")
-        .description("Draft change proposals against wiki pages, awaiting human review.")
+        .description("Draft change proposals against wiki pages, awaiting human review. Read-only, 0 credits.")
         .option("--status <status>", "open, decided, or all. Defaults to open.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
@@ -7393,10 +7559,11 @@ 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("--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.")
@@ -7430,6 +7597,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) {
@@ -7447,7 +7644,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) {
@@ -7472,6 +7671,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 });
@@ -7577,7 +7785,7 @@ 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.")
@@ -7610,18 +7818,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.", {
@@ -8464,7 +8681,8 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .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.")
+        .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.")
@@ -8482,14 +8700,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.")
@@ -8517,10 +8736,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")
@@ -8756,7 +8975,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         }));
     }))
         .addCommand(new Command("balance")
-        .description("Show the current plan, subscription entitlement, and managed credit balance: available and reserved credits, FIXED credits committed to recurring per-resource charges, and the FLEXIBLE free-to-spend remainder. `renewals_past_due` lists infrastructure renewals (managed-inbox domains, warm-ups) OXYGEN could NOT charge this month, what they cost, and the exact top-up that clears them — nothing is cancelled and billing retries automatically after a top-up. `warnings` also flags a recurring_shortfall when your connected infrastructure costs more per month than the plan grants. After failed-payment grace expires, mutations stop while read/export and billing recovery remain available. Recovery: https://oxygen-agent.com/billing. Policy: https://oxygen-agent.com/docs/safety/billing.")
+        .description("Show the current plan, subscription entitlement, and managed credit balance: available and reserved credits, FIXED credits committed to recurring per-resource charges, and the FLEXIBLE free-to-spend remainder. `next_renewal` answers \"will I be charged?\": read `will_charge` first — true only when this workspace's own Stripe plan is going to charge its card, in which case `charge_at` and the plan's monthly list price in money say when and roughly how much (the exact amount, with any promotion code or tax, is on the invoice); `period_ends_at` is the trial or period end either way, `cancellation_scheduled` says whether a cancellation is already set, and `stop_command` names the one command that changes it (`billing cancel`, undone by `billing resume`) or is null when nothing here can stop it (staff-invoiced, billed through another workspace, not active). `renewals_past_due` lists infrastructure renewals (managed-inbox domains, warm-ups) OXYGEN could NOT charge this month, what they cost, and the exact top-up that clears them — nothing is cancelled and billing retries automatically after a top-up. `warnings` also flags a recurring_shortfall when your connected infrastructure costs more per month than the plan grants. After failed-payment grace expires, mutations stop while read/export and billing recovery remain available. Recovery: https://oxygen-agent.com/billing. Policy: https://oxygen-agent.com/docs/safety/billing.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("billing balance", options, () => requestOxygen("/api/cli/billing/balance"));
@@ -8768,7 +8987,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         await handleAsyncAction("billing commitments", options, () => requestOxygen("/api/cli/billing/commitments"));
     }))
         .addCommand(new Command("seats")
-        .description("Show sending capacity per channel: how many seats are purchased, how many are grandfathered, how many senders are connected, and how many are left. Sending seats are what let you CONNECT a sender — a LinkedIn account, WhatsApp number, phone number, or email mailbox — and they are billed in dollars on their own subscription, separate from your plan and separate from credits. You do not need a plan to buy seats. A grandfathered value of null means unlimited for that channel. Email mailbox allocation is read from this workspace's own database; when it cannot be read, the email seat's allocated/available/can_connect read null and `email_sender_allocation` is `tenant_unavailable`. Read-only, 0 Oxygen credits.")
+        .description("Show sending capacity per channel: how many seats are purchased, how many are grandfathered, how many senders are connected, and how many are left. Sending seats are what let you CONNECT a sender — a LinkedIn account, WhatsApp number, phone number, or email mailbox — and they are billed in dollars on their own subscription, separate from your plan and separate from credits. You do not need a plan to buy seats. Seats belong to the billing owner: a workspace linked to another organization's plan with `orgs billing-link` connects senders against that organization's seats and buys them there. A grandfathered value of null means unlimited for that channel. Email mailbox allocation is read from this workspace's own database; when it cannot be read, the email seat's allocated/available/can_connect read null and `email_sender_allocation` is `tenant_unavailable`. Read-only, 0 Oxygen credits.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("billing seats", options, () => requestOxygen("/api/cli/billing/seats"));
@@ -9233,10 +9452,60 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("primary-providers")
-        .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. Read-only — never calls a provider. Staff only.")
+        .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) => {
-        await handleAsyncAction("admin primary-providers", options, () => requestOxygen("/api/cli/admin/primary-providers"));
+        const stages = readCsvOption(options.stages);
+        if (stages.length > 0 && !options.refresh) {
+            // Fail with the envelope rather than reading a board the caller
+            // believes it just refreshed.
+            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
+            ? {
+                method: "POST",
+                // The route budgets maxDuration = 300 and the balance stage
+                // walks every fetcher sequentially at 15s each, so the
+                // default 120s client budget aborts a refresh the server
+                // 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 } : {}),
+                    ...(options.force ? { force: true } : {}),
+                },
+            }
+            : undefined).catch((error) => {
+            emitCliFailure("admin primary-providers", error);
+            failed = true;
+            return null;
+        });
+        // Only a transport failure ends the command silently; an empty
+        // payload still gets rendered (or enveloped) rather than exiting 0
+        // with nothing printed.
+        if (failed)
+            return;
+        if (options.json) {
+            emitSuccess("admin primary-providers", board, options);
+            return;
+        }
+        // Without this the default invocation printed ~1,500 lines of raw
+        // JSON while the MCP tool printed a worst-first summary of the same
+        // payload — same board, two different products.
+        process.stdout.write(`${renderPrimaryProviderBoard(board, { binary: binaryName })}\n`);
     }))
         .addCommand(new Command("spend")
         .description("Global managed-provider spend limiter: burn, ceilings, breakers. Staff only.")
@@ -10342,11 +10611,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: {
@@ -10450,7 +10728,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
     }));
     program
         .command("find")
-        .description("One-shot contact and company lookups over enrichment waterfalls (no table). dry_run previews for free; live spends and needs --max-credits.")
+        .description("One-shot contact and company lookups over enrichment waterfalls (no table). dry_run previews the plan for free (which lanes would run, in order, and what each costs — not the answer); live spends and needs --max-credits.")
         .addCommand(new Command("email")
         .description("Find a person's work email via an input-aware multi-provider waterfall: a LinkedIn URL, name+domain, or first/last+domain each select the best provider profile, with an email-pattern pre-step and verification. dry_run shows the resolved profile + chain for free.")
         .option("--linkedin-url <url>", "Person LinkedIn profile URL (strongest signal).")
@@ -10459,7 +10737,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--last-name <name>", "Person last name.")
         .option("--company-domain <domain>", "Company apex domain, e.g. acme.com.")
         .option("--company-name <name>", "Company name.")
-        .option("--mode <mode>", "dry_run (default) or live. live spends credits.")
+        .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("--json", "Print a JSON envelope.")
         .action(async (options) => {
@@ -10473,7 +10751,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--company-domain <domain>", "Company apex domain.")
         .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) or live. live spends credits.")
+        .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("--json", "Print a JSON envelope.")
         .action(async (options) => {
@@ -10486,7 +10764,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--company-domain <domain>", "Company apex domain.")
         .option("--company-name <name>", "Company name.")
         .option("--company-linkedin-url <url>", "Company LinkedIn URL.")
-        .option("--mode <mode>", "dry_run (default) or live. live spends credits.")
+        .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("--json", "Print a JSON envelope.")
         .action(async (options) => {
@@ -10498,8 +10776,8 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--name <name>", "Company name.")
         .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) or live. live spends credits.")
-        .option("--max-credits <credits>", "Spend ceiling. Required for --mode live.")
+        .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; 0 runs only the zero-credit lanes (the priced lanes are skipped as credit_ceiling_reached).")
         .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) }));
@@ -10508,11 +10786,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; 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. An address whose escalation could not run keeps catch_all — record it as unconfirmed, never verified — and its escalation_unavailable_reason plus next_action say why and what to do: provider_account_dry on the managed lane is Oxygen's BounceBan balance, not your workspace credits, and you were not charged for it.")
         .argument("<emails...>", "One or more email addresses to verify.")
-        .option("--mode <mode>", "dry_run (default) or live. live spends credits.")
+        .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. Run the free dry_run first — it returns estimate.recommended_max_credits, the value that guarantees every catch-all address still gets escalated. 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 — the 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", {
@@ -11330,7 +11608,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("delete")
-        .description("Delete a LinkedIn post the connected account authored — a REAL, irreversible public write. Refuses without --approved (exit 7). --post is the composite social_id returned when the post was created (or by `oxygen posts get`), NOT the activity URN. To remove a post that is still only SCHEDULED in Oxygen, use `oxygen publishing posts delete` instead.")
+        .description("Delete a LinkedIn post the connected account authored — a REAL, irreversible public write. Refuses without --approved (exit 7). --post is the composite social_id returned when the post was created (or by `oxygen posts get`), NOT the activity URN. To remove only the OXYGEN copy, including a settled published copy, while keeping LinkedIn intact, use `oxygen publishing posts delete`.")
         .requiredOption("--post <social_id>", "Composite post social_id from `oxygen posts get` (the id returned when the post was created).")
         .option("--account <ref>", "Sender account that authored the post (sender id, connection id, or Unipile account id). Omit for the org default.")
         .option("--approved", "Actually delete the post. Without it the command refuses and deletes nothing.")
@@ -11360,7 +11638,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.")
@@ -12411,7 +12728,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
     program.addCommand(new Command("messages")
         .description("Cross-channel message corpus: every individual email + LinkedIn + WhatsApp message as one searchable stream (Postgres full-text search over bodies, keyset paginated by recency), plus reply-rate/campaign analytics. Message-level, unlike inbox (conversation-level triage).")
         .addCommand(new Command("query")
-        .description("Query messages across channels newest first, or relevance-ranked when -q is set. --channel all merges email + LinkedIn + WhatsApp (narrow with --channels); a campaign filter (--sequence-id) restricts to email. Filter by direction, account, contact, status, and date range.")
+        .description("Query messages across channels newest first, or relevance-ranked when -q is set. --channel all merges email + LinkedIn + WhatsApp (narrow with --channels); a campaign filter (--sequence-id) restricts to email. Filter by direction, account, contact, status, and date range. Scope: the Messages store (Unibox conversations, every native email since v1.927.0 linked to its campaign; earlier sends without a provider thread id are not). The complete send ledger of a sequence is `sequences events --kind sent`; its counts are `sequences stats`.")
         .option("-q, --query <text>", "Full-text search over message bodies (relevance-ranked).")
         .option("--channel <channel>", "Channel: all (merged, default), email, linkedin, or whatsapp.")
         .option("--channels <list>", "channel=all only: comma-separated channels to include (email,linkedin,whatsapp). Empty = all three.")
@@ -12763,14 +13080,14 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--email-definition-file <path>", "Path to a JSON file with the email content spec (subjects/bodies/delays/subsequences) compiled to an Instantly campaign on start.")
         .option("--max-credits <n>", "Credit cap for the LinkedIn track (also set when starting).")
         .option("--max-live-sends <n>", "External-action ceiling for 0-credit email/WhatsApp/CRM-task tracks (positive integer). Required to start any of them live.")
-        .option("--max-emails-per-mailbox-per-day <n>", "Per-mailbox daily email cap (positive integer) applied across the sending pool.")
+        .option("--max-emails-per-mailbox-per-day <n>", "Per-mailbox daily email cap (positive integer) applied across the sending pool; also sets each mailbox's send pace (send window ÷ cap, catching up when a slot is missed). Daily capacity = this cap × sendable mailboxes; `sequences stats` reports it under daily_budget.")
         .option("--send-window-file <path>", "Path to a JSON file with the sequence-level email send window: { timezone, days?, start, end, timezone_mode?, recipient_timezone_column? }.")
         .option("--max-emails-per-day <n>", "Sequence-wide daily live-send fleet cap (positive integer) across every sender/mailbox.")
         .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("--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 gap that only WIDENS the derived per-mailbox spacing — it never bypasses the daily caps or the send window.")
+        .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.")
         .option("--mailboxes <ids>", "Per-sequence sending-account allowlist for native email (Instantly's 'Accounts to use'): comma-separated mailbox ids. Native email sends rotate ONLY over these mailboxes instead of the whole pool. Omit for the whole pool. Note: a narrow allowlist plus --esp-matching strict can starve sends when no allowed same-provider mailbox exists (surfaced as blocked defer reasons in stats).")
         .option("--sender-profiles <ids>", "Send from these sender profiles (unified LinkedIn/WhatsApp/inbox identities): comma-separated profile ids. The server resolves each into its senders + inboxes. Live start is blocked if a selected profile lacks an account for a channel the journey uses.")
@@ -12865,14 +13182,14 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--clear-email", "Remove the email binding from the sequence (draft only).")
         .option("--max-credits <n>", "Credit cap for the LinkedIn track (draft only).")
         .option("--max-live-sends <n>", "Draft-time external-action ceiling for 0-credit email/WhatsApp/CRM-task tracks (positive integer). After first start, change it through `sequences start`.")
-        .option("--max-emails-per-mailbox-per-day <n>", "Per-mailbox daily email cap (positive integer) applied across the sending pool.")
+        .option("--max-emails-per-mailbox-per-day <n>", "Per-mailbox daily email cap (positive integer) applied across the sending pool; also sets each mailbox's send pace (send window ÷ cap, catching up when a slot is missed). Daily capacity = this cap × sendable mailboxes; `sequences stats` reports it under daily_budget.")
         .option("--send-window-file <path>", "Path to a JSON file with the sequence-level email send window: { timezone, days?, start, end, timezone_mode?, recipient_timezone_column? }.")
         .option("--max-emails-per-day <n>", "Sequence-wide daily live-send fleet cap (positive integer) across every sender/mailbox.")
         .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("--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 gap that only WIDENS the derived per-mailbox spacing — it never bypasses the daily caps or the send window.")
+        .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.")
         .option("--mailboxes <ids>", "Per-sequence sending-account allowlist for native email (Instantly's 'Accounts to use'): comma-separated mailbox ids. Native email sends rotate ONLY over these mailboxes instead of the whole pool. Note: a narrow allowlist plus --esp-matching strict can starve sends when no allowed same-provider mailbox exists (surfaced as blocked defer reasons in stats).")
         .option("--sender-profiles <ids>", "Send from these sender profiles (unified LinkedIn/WhatsApp/inbox identities): comma-separated profile ids. The server resolves each into its senders + inboxes. Live start is blocked if a selected profile lacks an account for a channel the journey uses.")
@@ -13090,7 +13407,9 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .description("List a launched campaign's table-backed contacts with full source variables, durable engagement stage, and factual or assigned sender. Contacts removed from this campaign are hidden; source rows remain intact.")
         .argument("<sequence>", "Sequence id or slug.")
         .option("--contact-state <state>", "Filter: all, not_contacted, contacted, connected, replied, or positive_reply.", "all")
-        .option("--limit <n>", "Maximum contacts to return (1-500).", "100")
+        .option("--limit <n>", "Maximum contacts per page (1-500). Page with --cursor (next_cursor from the previous page) or --offset.", "100")
+        .option("--cursor <c>", "Pagination cursor from the previous page's next_cursor.")
+        .option("--offset <n>", "Skip this many contacts before the page (0-based); an absolute alternative to --cursor.")
         .option("--json", "Print a JSON envelope.")
         .action(async (sequence, options) => {
         await handleAsyncAction("sequences contacts", options, () => {
@@ -13106,6 +13425,20 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
                 contact_state: contactState,
                 limit: String(limit),
             });
+            const cursor = readOption(options.cursor);
+            if (cursor)
+                params.set("cursor", cursor);
+            const offsetRaw = readOption(options.offset);
+            if (offsetRaw !== null) {
+                const offset = Number(offsetRaw);
+                if (!Number.isInteger(offset) || offset < 0) {
+                    throw new OxygenError("invalid_offset", "--offset must be a non-negative integer.", {
+                        details: { offset: offsetRaw },
+                        exitCode: 2,
+                    });
+                }
+                params.set("offset", String(offset));
+            }
             return requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}/contacts?${params.toString()}`);
         });
     }))
@@ -13198,7 +13531,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("stats")
-        .description("Show one sequence's persisted launch status and current operational state separately, including reasons, open work, lifetime sent/terminal-failed/deferral counts, and the funnel.")
+        .description("Show one sequence's persisted launch status and current operational state separately, including reasons, open work, lifetime sent/terminal-failed/deferral counts, and the funnel. daily_budget carries today's sends against the caps; operational.reasons carries why work is waiting (outside_send_window, mailbox_spacing, daily_send_cap_reached, ...). For a per-day send series use `sequences analytics --sequence <id> --range <window>`.")
         .argument("<sequence>", "Sequence id or slug.")
         .option("--json", "Print a JSON envelope.")
         .action(async (sequence, options) => {
@@ -13540,18 +13873,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.")
@@ -13647,6 +14025,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.")
@@ -14147,7 +14531,7 @@ 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).")
         .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). 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.")
         .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.")
@@ -14201,7 +14585,7 @@ 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"));
@@ -14870,7 +15254,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("status")
-        .description("Read warmup analytics back from the rail each mailbox is enrolled on and update its state in the pool. 0 Oxygen credits and no campaign sends, but it pauses a mailbox whose warmup has run away. Targets the whole pool unless --mailboxes is given.")
+        .description("Read warmup analytics back from the rail each mailbox is enrolled on and refresh each mailbox's warmupTruth (state, last send, pause reason, dispatch counters, next_action). A read: 0 Oxygen credits, no campaign sends, no change to your configuration; the one write OXYGEN may make is its own breaker pausing a mailbox proven to be dispatching far above its ramp. Targets the whole pool unless --mailboxes is given. For a per-mailbox read without a rail sync, use `oxygen mailboxes get <address> --json`.")
         .option("--mailboxes <list>", "Comma-separated mailbox ids or addresses to sync. Omit to sync the whole pool.")
         .option("--provider <name>", "Optional machine routing filter. Omit it for OXYGEN Warm-up; pass trulyinbox only to read inboxes still warming on the retired rail.")
         .option("--dry-run", "Skip the provider call (mailboxes marked pending).")
@@ -14912,9 +15296,9 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         }));
     })));
     program.addCommand(new Command("deliverability")
-        .description("External email deliverability: fleet reputation health and DIRECTIONAL inbox-placement (spam) tests via EmailGuard, Zapmail, or an explicitly configured SendKit dev canary. This group creates one-off placement probes; for continuous EmailGuard account monitoring use `oxygen mailboxes emailguard connect`. Placement tests are approval-gated paid runs (managed bills Oxygen credits; BYOK = 0 Oxygen credits — Zapmail BYOK bills your Zapmail wallet ~$2/test). SendKit is never auto-selected or generally available: it is a 0-credit, one-test canary for the configured eligible connected sender only.")
+        .description("External email deliverability: fleet reputation health and DIRECTIONAL inbox-placement (spam) tests via EmailGuard, Zapmail, or an explicitly configured SendKit dev canary. Start with `placement-test list` and `placement-test get` to inspect existing results for 0 credits without creating or sending a test. For continuous EmailGuard account monitoring use `oxygen mailboxes emailguard connect`. Placement tests are approval-gated paid runs (managed bills Oxygen credits; BYOK = 0 Oxygen credits — Zapmail BYOK bills your Zapmail wallet ~$2/test). SendKit is never auto-selected or generally available: it is a 0-credit, one-test canary for the configured eligible connected sender only.")
         .addCommand(new Command("placement-test")
-        .description("Directional inbox-placement (spam) tests: create, separately approve EmailGuard's exact seed send, then poll results.")
+        .description("Inspect saved directional inbox-placement results with list/get (0 credits; no test email is sent). New tests use preview and approval through run/send.")
         .addCommand(new Command("run")
         .description("Create a placement test for one sending mailbox. Without --approved this returns a cost PREVIEW. EmailGuard creation returns exact seeds + phrase but sends nothing; next run `placement-test send <id>` to preview and approve that external email. Zapmail owns its probe delivery and completes async (2-24h). SendKit requires explicit --provider sendkit plus --subject and --body, and is available only for the configured dev canary with an eligible connected sender. Its approval creates AND sends one probe with no separate send step: preview first, then re-run the same mailbox, provider, subject, and body with --approved --max-credits 0 --plan <plan_hash>.")
         .argument("<mailbox>", "Sending mailbox address to test (e.g. ada@send.acme.com).")
@@ -14969,7 +15353,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         }));
     }))
         .addCommand(new Command("list")
-        .description("List recent directional inbox-placement tests with status, health provider, billing mode, seed set, score, and credits used.")
+        .description("Inspect recent directional inbox-placement tests, their status, results, and credits used. The returned web link opens Accounts; use get for an exact result link. Costs 0 credits and never creates or sends a test; active tests may refresh their observations.")
         .option("--limit <n>", "Max rows (default 50, cap 200).")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
@@ -14979,7 +15363,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("get")
-        .description("Get one directional inbox-placement test by id — status, health provider, seed inboxes, per-provider results, and score. Zapmail results land async (2-24h); keep polling while status is awaiting_results.")
+        .description("Inspect one saved directional inbox-placement test by id: status, seed counts, per-provider results, and a web result link. Costs 0 credits and never creates or sends a test; active tests may refresh their observations. Zapmail results land async (2-24h); keep polling while status is awaiting_results.")
         .argument("<id>", "Placement test id.")
         .option("--json", "Print a JSON envelope.")
         .action(async (id, options) => {
@@ -16185,7 +16569,7 @@ Full trigger schema: oxygen workflows schema --subject trigger --json
         }
     }))
         .addCommand(new Command("mcp")
-        .description("Publish workflows as dynamic MCP tools (oxygen_workflow_<slug>) — the 'Clay Functions' pattern.")
+        .description("Expose hosted Workflows as dynamic MCP tools (oxygen_workflow_<slug>). For reusable table Functions, use oxygen functions.")
         .addCommand(new Command("enable")
         .description("Publish an active workflow as a callable MCP tool so any MCP client can run it. The published tool appears to MCP clients as oxygen_workflow_<slug>.")
         .argument("<workflow>", "Workflow id, slug, or name.")
@@ -16286,6 +16670,9 @@ Full trigger schema: oxygen workflows schema --subject trigger --json
         await handleAsyncAction("skills install", options, () => installAgentSkills(options));
     }));
     applyOxygenHelp(program, binaryName);
+    registerVisualCommands(program, handleAsyncAction);
+    registerFunctionsCommands(program, handleAsyncAction);
+    registerUgcCommands(program, handleAsyncAction);
     return program;
 }
 /**
@@ -18321,11 +18708,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 } : {}),
@@ -18333,8 +18724,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 });
@@ -18406,11 +18799,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 } : {}),
@@ -18418,8 +18815,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 });
@@ -23463,7 +23862,10 @@ function buildContextAssetUpsertBody(options) {
 function buildKnowledgePageUpsertBody(options) {
     const tags = readCsvOption(options.tags);
     const expectedRevision = readPositiveInt(options.expectedRevision);
+    const folder = readOption(options.folder);
     return {
+        ...(folder ? { folderId: folder === "root" ? null : folder } : {}),
+        ...(options.createOnly ? { createOnly: true } : {}),
         ...(readOption(options.slug) ? { slug: readOption(options.slug) } : {}),
         ...(readOption(options.id) ? { id: readOption(options.id) } : {}),
         ...(readOption(options.type) ? { type: readOption(options.type) } : {}),
@@ -24206,6 +24608,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,