@oxygen-agent/cli 1.922.14 → 1.936.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";
@@ -456,6 +460,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 +581,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 +1668,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 +3640,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 +3677,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 +3695,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 +3799,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 +3895,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) => {
@@ -5034,7 +5074,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) => {
@@ -6280,11 +6320,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 +6382,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 +6392,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 +6440,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 +6457,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 +6479,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 +6493,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 +6513,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 +6525,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 +6546,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 +6570,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) => {
@@ -8756,7 +8831,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 +8843,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 +9308,48 @@ 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("--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;
+        }
+        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 } : {}) },
+            }
+            : 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.")
@@ -10450,7 +10563,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 +10572,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 +10586,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 +10599,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,7 +10611,7 @@ 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("--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) => {
@@ -10510,7 +10623,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .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.")
         .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("--json", "Print a JSON envelope.")
@@ -11330,7 +11443,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.")
@@ -12411,7 +12524,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 +12876,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 +12978,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 +13203,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 +13221,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 +13327,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) => {
@@ -14147,7 +14276,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`.")
         .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.")
@@ -14870,7 +14999,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 +15041,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 +15098,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 +15108,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 +16314,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 +16415,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;
 }
 /**
@@ -23463,7 +23595,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) } : {}),

package/dist/ugc-commands.d.ts

@@ -0,0 +1,6 @@
+import { Command } from "commander";
+type Handle = (command: string, options: {
+    json?: boolean;
+}, action: () => Promise<unknown>) => Promise<void>;
+export declare function registerUgcCommands(program: Command, handle: Handle): void;
+export {};