@oxygen-agent/cli 1.1011.493 → 1.1011.607

package/dist/index.js

@@ -2,9 +2,17 @@ import { knowledgeIndexReadContract, knowledgePageReadContract } from "@oxygen/s
 import { DATABASE_ATTACH_CONTRACT, DATABASE_MIGRATE_CONTRACT, DATABASE_QUERY_CONTRACT } from "@oxygen/shared/contracts/database";
 import { DATABASE_QUERY_FLAG_OVERLAY } from "./database-query-flags.js";
 import { LINKEDIN_SENT_INVITES_QUERY_CONTRACT } from "@oxygen/shared/contracts/linkedin-invites-list";
+import { PIPEDRIVE_CATALOG_QUERY_CONTRACT, pipedriveCatalogQueryParams } from "@oxygen/shared/contracts/pipedrive-catalog";
+import { registerCrmFileReadCommands } from "./crm-file-read-commands.js";
+import { WHATSAPP_ACCOUNTS_READ_CONTRACT } from "@oxygen/shared/contracts/whatsapp-reads";
+import { WHATSAPP_ACCOUNT_FLAGS, whatsappAccountQuery } from "./whatsapp-account-flags.js";
+import { BILLING_OWNER_READ_CONTRACT } from "@oxygen/shared/contracts/billing-owner-read";
+import { publishingAmplificationListQueryContract, publishingAmplificationActionsQueryContract, publishingNotesQueryContract, publishingRevisionsQueryContract, publishingAnalyticsQueryContract, publishingReadQueryParams, } from "@oxygen/shared/contracts/publishing-reads";
+import { COPILOT_SESSIONS_LIST_CONTRACT } from "@oxygen/shared/contracts/copilot-sessions";
 import { registerCrmSupportFlags, readCrmNoteEditFields, readCrmPhotoFields, readCrmFileLabel, buildCrmObjectsPath, buildCrmConnectionsPath } from "./crm-support-flags.js";
 import { addToolCatalogSearchWindowFlag, readToolCatalogSearchWindow } from "./tool-catalog-search-window.js";
 import { createToolCatalogDetailCommand } from "./tool-catalog-detail-command.js";
+import { LIMITS_READ_QUERY_CONTRACT, limitsReadQueryIssue } from "@oxygen/shared/contracts/limits-read";
 import { execFileSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
 import { closeSync, createReadStream, createWriteStream, existsSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
@@ -35,9 +43,12 @@ import { SEQUENCE_LIFECYCLES, sequenceDisplayStatus } from "@oxygen/shared/seque
 import { operationPath } from "@oxygen/shared/contracts/operations";
 import { SENDER_LIMITS_SET_OPERATION } from "@oxygen/shared/contracts/sender-limits";
 import { addContractFlags, readContractFlags } from "./contract-flags.js";
+import { addFeedReadFlags, feedReadWindowParams } from "./feed-read-flags.js";
 import { TABLE_QUERY_GRID_CONTRACT } from "@oxygen/shared/contracts/table-query-grid";
 import { INTEGRATION_CONNECT_ACCOUNT_CONTRACT } from "@oxygen/shared/contracts/integration-connect";
 import { CRM_ENRICHMENT_READ_CONTRACT } from "@oxygen/shared/contracts/crm-enrichment-read";
+import { INBOX_DRAFTS_READ_CONTRACT } from "@oxygen/shared/contracts/inbox-drafts-read";
+import { SEQUENCE_LIST_PROJECTION_CONTRACT } from "@oxygen/shared/contracts/sequence-list";
 import { buildSenderLimitsBody, parseWorkingDaysOption, SENDER_LIMITS_FLAG_OVERLAY } from "./sender-limits-flags.js";
 import { readColumnDecisionFlags } from "./column-decision-options.js";
 import { MANAGED_DATA_SUPPLIERS } from "@oxygen/shared/data-suppliers";
@@ -2964,6 +2975,13 @@ function buildPublishingAnalyticsPath(base, params) {
     const suffix = [query.toString(), ...lists].filter(Boolean).join("&");
     return suffix ? `${base}?${suffix}` : base;
 }
+function publishingReadQueryPath(path, contract, options) {
+    const [base = path, existing] = path.split("?", 2);
+    const query = new URLSearchParams(existing);
+    for (const [key, value] of publishingReadQueryParams(contract, readContractFlags(options, contract)))
+        query.set(key, value);
+    return query.size ? `${base}?${query}` : base;
+}
 const PUBLISHING_ANALYTICS_ACCOUNT_HELP = "An account key from the summary's accounts list, or a LinkedIn sender id from `oxygen senders list`. Repeatable.";
 /** Repeated and/or comma-separated `--account` values, trimmed and de-duplicated. */
 function readPublishingAnalyticsAccounts(values) {
@@ -3953,6 +3971,7 @@ export function createProgram() {
             };
         });
     });
+    const billingOwnerReadFlags = { organization: { flag: "expected-organization", valueName: "<organization>" } };
     program
         .command("orgs")
         .description("Switch between the organizations (workspaces) you belong to, and share one paid plan across them. If this workspace has no plan of its own, `orgs billing-link` puts it on a plan you already pay for somewhere else instead of buying a second subscription.")
@@ -3976,11 +3995,15 @@ export function createProgram() {
         .action(async (organization, options) => {
         await handleOrgUseAction(organization, options, "orgs select");
     }))
-        .addCommand(new Command("billing-owners")
+        .addCommand(addContractFlags(new Command("billing-owners"), BILLING_OWNER_READ_CONTRACT, billingOwnerReadFlags)
         .description("List the organizations that could pay for this workspace: which of the organizations you belong to can cover another workspace's credits, and for each of the rest, why it cannot. Read-only, 0 Oxygen credits.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
-        await handleAsyncAction("orgs billing-owners", options, () => requestOxygen("/api/cli/orgs/billing-owners"));
+        await handleAsyncAction("orgs billing-owners", options, () => {
+            const fields = readContractFlags(options, BILLING_OWNER_READ_CONTRACT, billingOwnerReadFlags);
+            const query = new URLSearchParams(Object.entries(fields).map(([key, value]) => [key, String(value)]));
+            return requestOxygen(`/api/cli/orgs/billing-owners${query.size ? `?${query}` : ""}`);
+        });
     }))
         .addCommand(new Command("billing-link")
         .description("Cover a workspace with a plan you already pay for in another organization (one plan, many workspaces) instead of buying a second subscription. Omit --owner when exactly one of your organizations can pay and Oxygen will use it; `orgs billing-owners` lists them all. You must be an admin of BOTH organizations, the workspace being linked must not hold a live subscription of its own, and an org-bound key (oxy_live_…) can only link the workspace it is bound to. Credit billing moves, workspace data access does not; plan gates and sending seats then resolve through the owner, so the linked workspace connects senders against the owner's seats and seats are bought there. `plan_tier` in the response is the plan the workspace now runs on; `free` means the owner holds no active paid plan, so connecting senders stays blocked. From the owner, `billing usage --group-by workspace` reports the credits each linked workspace spent.")
@@ -4995,12 +5018,12 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
             body: buildPublishingBoostBody(postId, options),
         }));
     }))
-        .addCommand(new Command("revisions")
-        .description("List a post's content history: every revision with its number, title, text, author, and time.")
+        .addCommand(addContractFlags(new Command("revisions"), publishingRevisionsQueryContract)
+        .description("List a post's content history: newest-first revisions with their number, title, text, author, and time.")
         .argument("<post_id>", "Scheduled post id.")
         .option("--json", "Print a JSON envelope.")
         .action(async (postId, options) => {
-        await handleAsyncAction("publishing posts revisions", options, () => requestOxygen(`/api/cli/publishing/posts/${encodeURIComponent(postId)}/revisions`));
+        await handleAsyncAction("publishing posts revisions", options, () => requestOxygen(publishingReadQueryPath(`/api/cli/publishing/posts/${encodeURIComponent(postId)}/revisions`, publishingRevisionsQueryContract, options)));
     }))
         .addCommand(new Command("restore")
         .description("Roll a post's TEXT back to an earlier revision (see `publishing posts revisions`). The current text is snapshotted as a new revision first, so a restore is itself undoable. Refused once the post is publishing, published, or canceled — to bring a canceled post back, use `publishing posts uncancel`.")
@@ -5016,12 +5039,12 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
             return requestOxygen(`/api/cli/publishing/posts/${encodeURIComponent(postId)}/revisions/${revision}/restore`, { method: "POST" });
         });
     }))
-        .addCommand(new Command("notes")
+        .addCommand(addContractFlags(new Command("notes"), publishingNotesQueryContract)
         .description("List the internal review notes on a post. Notes are workspace-only — they are never published.")
         .argument("<post_id>", "Scheduled post id.")
         .option("--json", "Print a JSON envelope.")
         .action(async (postId, options) => {
-        await handleAsyncAction("publishing posts notes", options, () => requestOxygen(`/api/cli/publishing/posts/${encodeURIComponent(postId)}/comments`));
+        await handleAsyncAction("publishing posts notes", options, () => requestOxygen(publishingReadQueryPath(`/api/cli/publishing/posts/${encodeURIComponent(postId)}/comments`, publishingNotesQueryContract, options)));
     }))
         .addCommand(new Command("note")
         .description("Leave an internal review note on a post, or reply to one with --parent. Never published.")
@@ -5305,26 +5328,26 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
             accounts: readPublishingAnalyticsAccounts(options.account),
         })));
     }))
-        .addCommand(new Command("post")
+        .addCommand(addContractFlags(new Command("post"), publishingAnalyticsQueryContract)
         .description("One post's stored daily metric series, totals, growth curve, 24h/7d benchmarks against the workspace median, and earned-media value. EMV is impressions-derived; absent impressions return a reason instead of a made-up number. Read-only: no provider call, 0 credits.")
         .argument("<post_id>", "Scheduled post id.")
         .option("--since <date>", "ISO date to start the series from.")
         .option("--json", "Print a JSON envelope.")
         .action(async (postId, options) => {
-        await handleAsyncAction("publishing analytics post", options, () => requestOxygen(buildPublishingAnalyticsPath(`/api/cli/publishing/analytics/posts/${encodeURIComponent(postId)}`, { since: readOption(options.since) })));
+        await handleAsyncAction("publishing analytics post", options, () => requestOxygen(publishingReadQueryPath(buildPublishingAnalyticsPath(`/api/cli/publishing/analytics/posts/${encodeURIComponent(postId)}`, { since: readOption(options.since) }), publishingAnalyticsQueryContract, options)));
     }))
-        .addCommand(new Command("account")
+        .addCommand(addContractFlags(new Command("account"), publishingAnalyticsQueryContract)
         .description("Stored per-account metric series (followers) for connected LinkedIn and X publishing accounts, read once a day in the background. Read-only: no provider call, 0 credits.")
         .option("--provider <provider>", "Channel to read: linkedin or x. Omit for every connected channel.")
         .option("--since <date>", "ISO date to start the series from.")
         .option("--account <key>", PUBLISHING_ANALYTICS_ACCOUNT_HELP, collectRepeatable, [])
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
-        await handleAsyncAction("publishing analytics account", options, () => requestOxygen(buildPublishingAnalyticsPath("/api/cli/publishing/analytics/account", {
+        await handleAsyncAction("publishing analytics account", options, () => requestOxygen(publishingReadQueryPath(buildPublishingAnalyticsPath("/api/cli/publishing/analytics/account", {
             provider: readOption(options.provider),
             since: readOption(options.since),
             accounts: readPublishingAnalyticsAccounts(options.account),
-        })));
+        }), publishingAnalyticsQueryContract, options)));
     }))
         .addCommand(new Command("emv")
         .description("Set the workspace CPM used for earned-media value, per channel. EMV stays null on any channel whose provider does not expose impressions.")
@@ -5352,11 +5375,11 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
     }))
         .addCommand(new Command("amplification")
         .description("Standing auto-engagement policies: the sender accounts you name react to and comment on every post in scope, paced and capped. Default OFF — a new policy is created disabled, and arming it is a separate, deliberate call.")
-        .addCommand(new Command("list")
+        .addCommand(addContractFlags(new Command("list"), publishingAmplificationListQueryContract)
         .description("List amplification policies with their scope, caps, and enabled state.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
-        await handleAsyncAction("publishing amplification list", options, () => requestOxygen("/api/cli/publishing/amplification"));
+        await handleAsyncAction("publishing amplification list", options, () => requestOxygen(publishingReadQueryPath("/api/cli/publishing/amplification", publishingAmplificationListQueryContract, options)));
     }))
         .addCommand(new Command("create")
         .description("Create an amplification policy. It arms REAL public engagement from other people's connected accounts and, once enabled, draws credits each cycle (creating it spends nothing), so it is refused (exit 7) without --approved, --max-credits and --acknowledge-risk — that grant is recorded with who/when/what scope. The policy is created DISABLED: run `amplification enable` when you actually want it to run.")
@@ -5449,13 +5472,13 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
             method: "DELETE",
         }));
     }))
-        .addCommand(new Command("actions")
+        .addCommand(addContractFlags(new Command("actions"), publishingAmplificationActionsQueryContract)
         .description("The policy's action ledger: what each participant account did (or is about to do) on which post, with status and cost.")
         .argument("<policy_id>", "Amplification policy id.")
         .option("--status <status>", "Filter by planned, dispatched, failed, or skipped.")
         .option("--json", "Print a JSON envelope.")
         .action(async (policyId, options) => {
-        await handleAsyncAction("publishing amplification actions", options, () => requestOxygen(buildPublishingAnalyticsPath(`/api/cli/publishing/amplification/${encodeURIComponent(policyId)}/actions`, { status: readOption(options.status) })));
+        await handleAsyncAction("publishing amplification actions", options, () => requestOxygen(publishingReadQueryPath(buildPublishingAnalyticsPath(`/api/cli/publishing/amplification/${encodeURIComponent(policyId)}/actions`, { status: readOption(options.status) }), publishingAmplificationActionsQueryContract, options)));
     })))
         .addCommand(new Command("ideas")
         .description("The content backlog: ideas parked for later, with no publish time and no AI spend.")
@@ -6796,16 +6819,16 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
     })))
         .addCommand(new Command("pipedrive")
         .description("Import a Pipedrive saved people filter into a new Oxygen table, optionally suppressing a Pipedrive do-not-contact filter first. Connect Pipedrive with an API token first: `oxygen integrations connect pipedrive --api-key <token>`.")
-        .addCommand(new Command("filters")
-        .description("List the connected Pipedrive account's saved people/organization filters and its person/organization fields (custom-field keys included). Reads definitions only; no persons, rows, or writes. Free — 0 Oxygen credits, uses your Pipedrive API quota.")
-        .option("--query <text>", "Optional filter-name search.")
+        .addCommand(addContractFlags(new Command("filters")
+        .description("Read connected Pipedrive saved filters and custom-field definitions; no people imported. Four BYOK fees may apply. Use --approved with --max-credits to authorize this read; refusal returns the required cap without provider calls."), PIPEDRIVE_CATALOG_QUERY_CONTRACT, {
+        query: { valueName: "<text>" },
+        approved: { noNegate: true },
+        max_credits: { valueName: "<n>" },
+    })
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("tables pipedrive filters", options, () => {
-            const params = new URLSearchParams();
-            const query = readOption(options.query);
-            if (query)
-                params.set("query", query);
+            const params = pipedriveCatalogQueryParams(readContractFlags(options, PIPEDRIVE_CATALOG_QUERY_CONTRACT, { approved: { noNegate: true } }));
             const suffix = params.toString();
             return requestOxygen(`/api/cli/tables/pipedrive-import${suffix ? `?${suffix}` : ""}`);
         });
@@ -7116,11 +7139,11 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(addContractFlags(new Command("query"), TABLE_QUERY_GRID_CONTRACT, {
-        format: { valueName: "<format>", help: "Read the web grid projection ('grid'): defaults to 50 rows, capped at 200, with table, limit, cursor and optional --include-stats/--include-fill. Omit for a filtered row query." },
+        format: { valueName: "<format>", help: "Grid cell previews/state: default 50, cap 200, optional stats/fill/window. Omit for raw filters, fields, search, sorts or offsets." },
     })
-        .description("Query raw table rows or use --format grid for display previews, cell state and native cursors. Output is a JSON envelope; for a typed rendering of raw rows use `tables export <table> --format table`. Grid takes table/limit/cursor; rowCountMode labels registry/exact/skipped. Optional stats/fill may be unavailable.")
+        .description("Read raw Table rows or --format grid cell previews/state with grid.nextCursor, in a JSON envelope. Use tables preview --summary-only for fill rates; tables export <table> --format table renders raw rows. Grid supports stats/fill/window options and refuses raw selectors.")
         .argument("<table>", "Table id or slug.")
-        .option("--limit <n>", "Maximum rows to return. Defaults to 100; hard cap is 1000.")
+        .option("--limit <n>", "Raw: default 100, native cap 2000. Grid: default 50, cap 200.")
         .option("--cursor <cursor>", "Pagination cursor returned by a previous query. Walks forward one page at a time; mutually exclusive with --offset.")
         .option("--offset <n>", "Skip this many rows and start there — jump straight to a row without paging to it. Mutually exclusive with --cursor.")
         .option("--fields <columns>", "Comma-separated column keys or ids to include.")
@@ -7929,7 +7952,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         return requestOxygen(`/api/cli/tables/auto-run?${params.toString()}`);
     })))
         .addCommand(new Command("set")
-        .description("Enable a standing auto-run: automatically queue the given columns for rows written to this table (imports, inserts, upserts). A queued cell that already has a value is skipped unless --force, so an upsert that touches an existing, filled row is not charged again. Rows a LinkedIn capture writes are subscribed separately and only when newly inserted — for profile viewers, `viewers enrichment --on`. Default off.")
+        .description("Enable a standing auto-run: automatically queue the given columns for rows written to this table (imports, inserts, upserts), including workflow audience upserts and own-follower capture. A queued cell that already has a value is skipped unless --force, so an upsert that touches an existing, filled row is not charged again. Profile viewers use their separate `viewers enrichment --on` subscription. Default off.")
         .argument("<table>", "Table id or slug.")
         .requiredOption("--columns <csv>", "Comma-separated column keys to auto-run on newly written rows (tool, AI, formula, enrichment, bind, or lookup columns).")
         .option("--sources <csv>", "Which write sources trigger the auto-run: any of import, insert, upsert, send. Defaults to all when omitted.")
@@ -8040,23 +8063,23 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
     program
         .command("feeds")
         .description("Live tables: bind a scheduled provider harvest (a FEED) to a table so it keeps filling itself on a cadence, then inspect, pause, resume, run, or unbind it. A feed is part of Tables, not a new primitive — `oxygen tables webhook` is the inbound (push) half of the same ledger.")
-        .addCommand(new Command("list")
-        .description("List table feeds for the workspace, newest first. Read-only.")
+        .addCommand(addFeedReadFlags(new Command("list")
+        .description("List table feeds for the workspace, newest first. Optional summary/full windows resume with next-offset; exact settings use feeds get --projection value. Read-only.")
         .argument("[table]", "Optional table id or slug to filter by.")
         .option("--table <table>", "Table id or slug. Equivalent to the positional argument.")
         .option("--transport <transport>", "pull (scheduled provider harvest) or push (inbound webhook).")
         .option("--status <status>", "Filter by active or disabled.")
         .option("--state <state>", "Filter by run state: idle, running, error, or exhausted.")
-        .option("--limit <n>", "Maximum feeds to return. Defaults to 100.")
+        .option("--limit <n>", "Maximum feeds to return (1-200). Defaults to 50.")
         .option("--include-cursor", "Include the opaque provider page token in the cursor block.")
         .option("--json", "Print a JSON envelope.")
-        .action((table, options) => handleAsyncAction("feeds list", options, () => requestOxygen(feedsListPath(options, table)))))
-        .addCommand(new Command("get")
-        .description("Get one table feed: cadence and next run, per-cycle caps, cursor counters, last cycle, and last error. Read-only.")
+        .action((table, options) => handleAsyncAction("feeds list", options, () => requestOxygen(feedsListPath(options, table))))))
+        .addCommand(addFeedReadFlags(new Command("get")
+        .description("Get one table feed. Optional summary or lossless value JSON windows recover every public setting; resume value-cursor with the same feed/path/include-cursor. Read-only.")
         .argument("<feed>", "Feed id or endpoint id.")
         .option("--include-cursor", "Include the opaque provider page token in the cursor block.")
         .option("--json", "Print a JSON envelope.")
-        .action((feed, options) => handleAsyncAction("feeds get", options, () => requestOxygen(feedsGetPath(feed, options)))))
+        .action((feed, options) => handleAsyncAction("feeds get", options, () => requestOxygen(feedsGetPath(feed, options)))), true))
         .addCommand(new Command("bind")
         .description("Bind a feed to a table: a scheduled provider harvest (pull), with --schema-json a typed-or-rejected push feed, or with --source rb2b the web-intent feed landing RB2B website-visit reveals as rows. A pull feed freezes the provider request into an existing table, then optionally arms a cadence so the table refills itself; arming a cadence on a paid provider is a STANDING spend grant — it requires --every, --max-credits, and --approved together, and without --every the feed is stored disarmed until you set one. A push feed is free: it returns a webhook URL and a secret shown once, refuses a delivery that does not match the schema with HTTP 422 (recorded in `oxygen feeds deliveries`, nothing written), and can create its table from the schema with --create <name>. `--source rb2b` is the web intent feed: OXYGEN already receives your RB2B website-visit reveals and records each one as a website_visit Signal, and this feed ALSO lands them as rows you can enrich, score, and sequence. It has no address, no schema, and no cadence to configure — the reveal shape is fixed — so binding is free and each reveal costs 0 credits on arrival. If RB2B is not connected to this workspace yet, rows only start once it is; there is no self-serve connect step yet.")
         .argument("[table]", "Table id or slug that receives the rows. Required for a pull feed; a push or web-intent feed takes it or --create <name>.")
@@ -9451,11 +9474,13 @@ Examples:
         .command("recipes")
         .description("Business-case GTM playbooks: proven plays with prerequisites, credit posture, and approval gates spelled out. Whole-motion operator playbooks (TAM sourcing, LinkedIn content strategy, inbound-led outbound, signal-based outbound) are the oxygen-playbooks skill: oxygen skills get oxygen-playbooks --json.")
         .addCommand(new Command("list")
-        .description("List recipes, optionally filtered by text, business-case category, journey stage, or audience.")
-        .argument("[query]", "Search text (matches slug/title/business case/tags).")
+        .description("Find a GTM play for a goal: recipes ranked by relevance to your words; --view summary for a compact index. Filter by business-case category, journey stage, or audience.")
+        .argument("[query]", "Your goal in plain words, e.g. \"more pipeline from linkedin\" (ranked against title, trigger phrases, tags, and business case).")
         .option("--category <category>", "Business-case category (e.g. start-here, pipeline-from-zero).")
         .option("--stage <stage>", "Journey stage: day-1, day-7, day-30, or ongoing.")
         .option("--audience <audience>", "founder, gtm-operator, or agency-operator.")
+        .option("--view <view>", "summary (compact index to choose a play from) or full (default: every field).")
+        .option("--limit <n>", "Return at most n recipes (1-50), after ranking.")
         .option("--json", "Print a JSON envelope.")
         .action(async (query, options) => {
         await handleAsyncAction("recipes list", options, () => {
@@ -9471,6 +9496,12 @@ Examples:
             const audience = readOption(options.audience);
             if (audience)
                 params.set("audience", audience);
+            const view = readOption(options.view);
+            if (view)
+                params.set("view", view);
+            const limit = readOption(options.limit);
+            if (limit)
+                params.set("limit", limit);
             const qs = params.toString() ? `?${params.toString()}` : "";
             return requestOxygen(`/api/cli/recipes${qs}`);
         });
@@ -11180,11 +11211,22 @@ Examples:
         .command("limits")
         .description("Plan-tier limits, spend-safety defaults, per-channel sending limits, and storage capacity posture.")
         .addHelpText("after", "\nRun `oxygen limits show --json` to see your current plan's API and webhook rates, Table and workspace storage headroom, and the next scheduled change. The $999 and $1,999 rows-per-Table increases remain held until capacity testing passes.\n")
-        .addCommand(new Command("show")
-        .description("Compare every plan size: price, monthly credits, volume bonus and price per 100 credits (`plan_bands`). Show your plan band and its limits beside every plan size's (API rate, webhook ingress, storage, import file size, columns per auto-run, signals feed, spend defaults incl. Agent and Copilot caps, fastest workflow schedule), the per-channel sending limits every plan shares (emails per mailbox, WhatsApp, LinkedIn, calls) and its workflow Code-step and run-attempt limits, plus Tables capacity usage naming the largest Table. Each plan size's storage says whether it is in force, scheduled to change on a date, or awaiting its rows-per-Table capacity test, with the values it moves to. `spend_safety_defaults.enterprise_agent_run_default` gives Enterprise the $1,999 band’s in-force Agent default with no contract override; `agent_run_approved_max_credits` is the maximum for an explicitly approved higher run. `spend_safety_defaults.applies_to` says what each spend default bounds: an unattended trigger delivery, a table auto-run batch, one Agent run, or the attended Copilot. `web_url` opens the same view in the web app (Settings → Plan limits), including any scheduled change. Read-only; spends no credits. Recovery: https://oxygen-agent.com/docs/safety/billing.")
+        .addCommand(addContractFlags(new Command("show")
+        .description("Compare every plan size: price, monthly credits, volume bonus and price per 100 credits (`plan_bands`). Show your plan band and its limits beside every plan size's (API rate, webhook ingress, storage, import file size, columns per auto-run, signals feed, spend defaults incl. Agent and Copilot caps, fastest workflow schedule), the per-channel sending limits every plan shares (emails per mailbox, WhatsApp, LinkedIn, calls) and its workflow Code-step and run-attempt limits, plus Tables capacity usage naming the largest Table. Each plan size's storage says whether it is in force, scheduled to change on a date, or awaiting its rows-per-Table capacity test, with the values it moves to. `spend_safety_defaults.enterprise_agent_run_default` gives Enterprise the $1,999 band’s in-force Agent default with no contract override; `agent_run_approved_max_credits` is the maximum for an explicitly approved higher run. `spend_safety_defaults.applies_to` says what each spend default bounds: an unattended trigger delivery, a table auto-run batch, one Agent run, or the attended Copilot. `web_url` opens the same view in the web app (Settings → Plan limits), including any scheduled change. Read-only; spends no credits. Recovery: https://oxygen-agent.com/docs/safety/billing."), LIMITS_READ_QUERY_CONTRACT)
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
-        await handleAsyncAction("limits show", options, () => requestOxygen("/api/cli/limits"));
+        await handleAsyncAction("limits show", options, () => {
+            const projection = readContractFlags(options, LIMITS_READ_QUERY_CONTRACT);
+            const issue = limitsReadQueryIssue(projection);
+            if (issue)
+                throw new OxygenError("invalid_request", issue);
+            const params = new URLSearchParams();
+            for (const [key, value] of Object.entries(projection))
+                if (value !== undefined)
+                    params.set(key, String(value));
+            const suffix = params.toString();
+            return requestOxygen(`/api/cli/limits${suffix ? `?${suffix}` : ""}`);
+        });
     }))
         .addCommand(new Command("provider")
         .description("Per-provider call-rate overrides and BYOK daily warning thresholds. With no subcommand, lists policies (same as `limits provider list`).")
@@ -11232,7 +11274,7 @@ Examples:
         .command("billing")
         .description("Plan and managed credit commands. Spend splits into FLEXIBLE (ad-hoc: enrichment, AI, automation — drawn from your free-to-spend balance) and FIXED recurring per-resource monthly commitments blocked out of it; see `billing commitments`. THREE CLOCKS, deliberately different: the CREDIT CYCLE that `billing allowance` reports against (your plan's monthly grant window); each resource's own COMMITMENT RENEWAL, anchored to the day you connected it, so `billing commitments --json` next_due_at rarely matches the cycle end; and your SUBSCRIPTION PERIOD in `billing balance` (annual plans span many credit cycles). A number from one clock will not reconcile against another. On a plan that pays for several workspaces, `billing usage --group-by workspace` totals what each one spent. To price a month of outreach before building it (leads, enrichment, sequence steps, senders), run `billing estimate`. Failed-payment grace, suspension, and recovery: https://oxygen-agent.com/docs/safety/billing.")
         .addCommand(new Command("change")
-        .description("Create a Stripe approval link to start a first plan or change an existing plan, and return that link (`approval_url`), with the target plan's monthly credits (`target_plan`). On a workspace with no plan (`mode: first_subscription`) the link is the same Stripe Checkout the web Subscribe button opens, and credits arrive once Stripe confirms the first payment; subscribing needs an organization admin. Nothing is charged or changed until you confirm in Stripe. `interval` is how the plan bills after the change; `recurring_amount` is what each interval bills and `recurring_monthly` its per-month equivalent (a yearly $99 plan: $990, $82.50). Without --interval the plan keeps its current interval. Moving to yearly applies on confirmation with proration; moving to monthly waits for the period end. To compare every plan's credits, volume bonus and price per 100 credits without creating a link, run `limits show`.")
+        .description("Create an approval link (`approval_url`) to start or change a plan; nothing changes until an organization admin confirms. Compare all six prices, credits and yearly terms with `billing balance` first. Use --interval month --term year for twelve discounted monthly payments, renewing for another year: the $99 plan costs $82.50 per month before tax, not $990 upfront. Credits arrive monthly after successful payment. On a workspace that has never had a plan, the Checkout for any monthly plan from $99 up carries the first-month offer, half its first month, while its 24-hour window is open (`offer`; `billing balance` lists every size under `first_month_offer.plans`): `amount_due_now` is then the discounted first month and `next_invoice_total` the regular price, both before tax. Creating that Checkout starts the window if nothing has started it yet. Upgrades during an annual commitment apply immediately with proration and keep its end date; downgrades and switching to a monthly commitment wait for the term end. Switching from a monthly commitment to yearly starts at the next monthly boundary. Existing prepaid yearly plans keep their cadence unless a new term is selected; transitions wait until their paid period ends. Omit interval and term to preserve the current contract. For an existing subscription, a yearly preview returns charges, start and term-end dates; nothing changes until separate confirmation.")
         .requiredOption("--to <plan>", 
     // Derived from the catalog, never retyped: this help text is the only
     // place a customer's agent learns which plans exist, and it named
@@ -11253,17 +11295,18 @@ Examples:
             : "";
         return `${key} ($${cents / 100}/mo${creditText})`;
     }).join(", ")}.`)
-        .option("--interval <interval>", "Bill monthly (`month`) or yearly (`year`: ten months' price for twelve, credits still granted monthly). Omit to keep the current interval (monthly for a first plan). Monthly to yearly adds no extra month: credits already granted for the rest of the month count toward the first yearly month. Check `annual_billing_available` with `oxygen billing balance --json` before creating a Stripe link. Yearly is refused with `annual_billing_unavailable` until it is offered.")
+        .option("--interval <interval>", "Payment cadence. Use month for new plans; choose --term year for a yearly commitment paid monthly. Omit to preserve an existing subscription's cadence, including prepaid yearly plans.")
+        .option("--term <term>", "Commitment: month or year. Year means twelve discounted monthly payments, renewing annually. Downgrades wait for the term end; omit to preserve the current term.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("billing change", options, () => requestOxygen("/api/cli/billing/change", {
             method: "POST",
             // Sent only when asked: the server keeps the subscriber's interval otherwise.
-            body: { tier: options.to, ...(options.interval ? { interval: options.interval } : {}) },
+            body: { tier: options.to, ...(options.interval ? { interval: options.interval } : {}), ...(options.term ? { term: options.term } : {}) },
         }));
     }))
         .addCommand(new Command("balance")
-        .description("Show the current plan, whether yearly billing is offered (`annual_billing_available`), 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). `billing_interval` says whether the plan bills monthly or yearly; a yearly plan still grants its credits monthly, and `next_credit_grant_at` says when the next monthly grant arrives. `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. `partner_bonus` says whether this workspace earns the agency partner bonus (+15% credits a month for a published directory partner on $99 or above), how many credits, and why not when it does not; the bonus arrives as its own ledger line (`billing usage --category partner_bonus`), never inside plan.monthly_credits. A workspace linked to another organization (`orgs billing-link`) reads its billing at that owner: the balance is the owner's pool, `shared_billing` is true and `billing_owner_organization_id` names the owner. 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("Compare all six subscription sizes in `available_plans`: monthly prices, yearly paid-monthly prices, credit allowances and savings. `annual_monthly_billing_available` says whether yearly paid monthly is offered; `annual_monthly_terms` explains the 12-month commitment, annual renewal, remaining payments after cancellation and plan-change timing. `first_month_offer` is the first-month offer this workspace can still claim: every size it applies to (`plans`, from `minimum_plan` up) with its first-month and regular price before tax, and `ends_at`, null until its 24-hour window starts. The window starts the first time the workspace meets the offer: the app showing it, signup from a browser that saw it on the website, or creating its Checkout with `billing change`. Also show the current plan, commitment, 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 subscription's recurring amount 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). `billing_interval` is payment cadence; `commitment` distinguishes yearly paid monthly from monthly and legacy prepaid yearly plans. Credits are granted monthly; `next_credit_grant_at` is the next grant. For a yearly commitment, cancellation stops annual renewal but remaining monthly payments continue until commitment.ends_at. `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. `partner_bonus` says whether this workspace earns the agency partner bonus (+15% credits a month for a published directory partner on $99 or above), how many credits, and why not when it does not; the bonus arrives as its own ledger line (`billing usage --category partner_bonus`), never inside plan.monthly_credits. A workspace linked to another organization (`orgs billing-link`) reads its billing at that owner: the balance is the owner's pool, `shared_billing` is true and `billing_owner_organization_id` names the owner. 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"));
@@ -11457,7 +11500,7 @@ Examples:
         }));
     }))
         .addCommand(new Command("cancel")
-        .description("Schedule the plan subscription to cancel at period end. Free (no fee, no credits); the plan stays usable until then and the card is not charged again (during a trial, never). Separately funded external resources keep renewing; preview `workspace infrastructure-exit` if you want to end those too. Prints the end date; undo any time before then with billing resume.")
+        .description("Turn off subscription renewal. For a yearly commitment paid monthly, remaining monthly payments continue through commitment_ends_at; the plan stays usable until then. Other plans end at their paid period or trial end with no further subscription renewal charge. This command costs no Oxygen credits. Separately funded external resources keep renewing; preview `workspace infrastructure-exit` to end those too. Prints the end date; undo before then with billing resume.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("billing cancel", options, () => requestOxygen("/api/cli/billing/cancel", {
@@ -11839,7 +11882,7 @@ Examples:
         .option("--key <key>", "Scope key: category/provider/org id, or * for the default.", "*")
         .requiredOption("--window <seconds>", "Window: 60, 3600, or 86400.")
         .option("--limit-usd <usd>", "Ceiling in USD of OXYGEN's own provider cost.")
-        .option("--limit-calls <n>", "Ceiling in call count (used by the signature loop detector).")
+        .option("--limit-calls <n>", "Ceiling in call count: the signature loop detector, or the only ceiling that bounds a $0-priced provider.")
         .option("--action <action>", "warn (meter + alert only) or block (enforce).", "warn")
         .option("--notes <text>", "Why this ceiling is set where it is.")
         .option("--json", "Print a JSON envelope.")
@@ -12439,11 +12482,15 @@ Examples:
             return requestOxygen("/api/cli/copilot/sessions", { method: "POST", body });
         });
     }))
-        .addCommand(new Command("list")
-        .description("List your Workspace Copilot sessions and their current status.")
-        .option("--json", "Print a JSON envelope.")
+        .addCommand(addContractFlags(new Command("list")
+        .description("List Workspace Copilot conversations by session status, newest first; this read starts no inference.")
+        .option("--json", "Print a JSON envelope."), COPILOT_SESSIONS_LIST_CONTRACT)
         .action(async (options) => {
-        await handleAsyncAction("copilot list", options, () => requestOxygen("/api/cli/copilot/sessions"));
+        await handleAsyncAction("copilot list", options, () => {
+            const selectors = readContractFlags(options, COPILOT_SESSIONS_LIST_CONTRACT);
+            const query = new URLSearchParams(Object.entries(selectors).map(([key, value]) => [key, String(value)]));
+            return requestOxygen(`/api/cli/copilot/sessions${query.size ? `?${query}` : ""}`);
+        });
     }))
         .addCommand(new Command("get")
         .description("Show one Workspace Copilot session: its state, turns, and event log. Use --after-seq to page through the event stream.")
@@ -13761,7 +13808,7 @@ Examples:
         .description("View and adjust per-account daily action limits, working hours (the times LinkedIn actions may run) and the timezone they use.")
         .option("--json", "Print a JSON envelope.")
         .addCommand(new Command("get")
-        .description("Show current limits, overrides, working hours (timezone, days, start, end), defaults, and safe maximums for an account. <id> accepts a sender account id, connection id, or Unipile account id.")
+        .description("Show current limits, overrides, working hours (timezone, days, start, end), defaults, hard maximums, and the caution levels above which LinkedIn restriction risk rises, for an account. <id> accepts a sender account id, connection id, or Unipile account id.")
         .argument("<id>", "Sender account id, connection id, or Unipile account id.")
         .option("--json", "Print a JSON envelope.")
         .action(async (id, options) => {
@@ -14193,7 +14240,7 @@ Examples:
         });
     })));
     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 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. To have teammates react to or comment on the workspace's own posts, use `oxygen publishing amplification --help`.")
+        .description("For a LinkedIn audience campaign, find the matching play with `oxygen recipes list \"post engagers\" --view summary --json`: own, competitor, creator or keyword post engagers, company followers, or own followers. The Recipe and shared guide prepare qualified recipients and a disabled ongoing router. For one known post, read its engagers or harvest into a durable Table using its public URL or composite social_id from `oxygen posts get`; harvesting runs as a paced background drip. Existing intent captures are managed with `oxygen feeds list|pause|resume|run`; existing profile watchers use `oxygen tables watcher get`. To have teammates react to or comment on the workspace's own posts, use `oxygen publishing amplification --help`.")
         .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).")
@@ -14561,23 +14608,12 @@ Examples:
     }))));
     program.addCommand(new Command("whatsapp")
         .description("Manage the org's connected WhatsApp accounts for Sequencer: list, connect, sync, inspect, disconnect, tune daily limits, and warm-send into an existing conversation. Cold outbound runs through a WhatsApp sequence (sequences create --channels whatsapp).")
-        .addCommand(new Command("accounts")
-        .description("List connected WhatsApp accounts with health status, warm-up ramp state, limits, and today's usage. Disconnected accounts are hidden unless you pass --status disconnected.")
-        .option("--status <status>", "Filter by account status: active, paused, disconnected, restricted, or credentials_required.")
-        .option("--no-usage", "Skip today's per-account usage counts.")
-        .option("--tag <tags>", "Comma-separated workspace tags — matches WhatsApp accounts carrying ANY of these tags (see `oxygen tags list`).")
+        .addCommand(addContractFlags(new Command("accounts")
+        .description("Read stored WhatsApp account health. Disconnected accounts are hidden by default; --include-disconnected includes retained accounts, --status selects one status. Presence is not send readiness. Use summary and exact account-id/value for long public metadata."), WHATSAPP_ACCOUNTS_READ_CONTRACT, WHATSAPP_ACCOUNT_FLAGS)
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("whatsapp accounts", options, () => {
-            const params = new URLSearchParams();
-            params.set("include_usage", options.usage === false ? "false" : "true");
-            const status = readOption(options.status);
-            if (status)
-                params.set("status", status);
-            const tags = splitCommaList(options.tag);
-            if (tags.length > 0)
-                params.set("tag", tags.join(","));
-            const suffix = params.toString();
+            const suffix = whatsappAccountQuery(options).toString();
             return requestOxygen(`/api/cli/whatsapp/accounts${suffix ? `?${suffix}` : ""}`);
         });
     }))
@@ -15346,28 +15382,28 @@ Examples:
     })))
         .addCommand(new Command("drafts")
         .description("The AI reply-agent draft queue (the approve-before-send review queue).")
-        .addCommand(new Command("list")
+        .addCommand(addContractFlags(new Command("list")
         .description("List drafts awaiting review (queued + edited by default), across email + LinkedIn.")
-        .option("--status <keys>", "Comma-separated draft statuses (queued,edited,sent,rejected).")
-        .option("--channel <channel>", "Filter to one channel: email or linkedin.")
-        .option("--sequence-id <id>", "Filter to one campaign (sequence) id (email drafts only).")
-        .option("--limit <n>", "Maximum drafts to return.")
-        .option("--json", "Print a JSON envelope.")
+        .option("--json", "Print a JSON envelope."), INBOX_DRAFTS_READ_CONTRACT, {
+        status: { valueName: "<keys>", help: "Comma-separated draft statuses (queued,edited,approved,sent,rejected).", parse: readOption },
+        channel: { valueName: "<channel>", help: "Filter to one channel: email or linkedin.", parse: readOption },
+        sequence_id: { valueName: "<id>", help: "Filter to one campaign (sequence) id (email drafts only).", parse: readOption },
+        limit: { valueName: "<n>", help: "Maximum drafts to return.", parse: readOption },
+        conversation_id: { valueName: "<id>", parse: readOption },
+        draft_id: { valueName: "<id>", parse: readOption },
+    })
         .action(async (options) => {
         await handleAsyncAction("inbox drafts list", options, () => {
+            const query = readContractFlags(options, INBOX_DRAFTS_READ_CONTRACT, {
+                status: { parse: readOption }, channel: { parse: readOption },
+                sequence_id: { parse: readOption }, limit: { parse: readOption },
+                conversation_id: { parse: readOption }, draft_id: { parse: readOption },
+            });
             const params = new URLSearchParams();
-            const status = readOption(options.status);
-            if (status)
-                params.set("status", status);
-            const channel = readOption(options.channel);
-            if (channel)
-                params.set("channel", channel);
-            const sequenceId = readOption(options.sequenceId);
-            if (sequenceId)
-                params.set("sequence_id", sequenceId);
-            const limit = readOption(options.limit);
-            if (limit)
-                params.set("limit", limit);
+            for (const [key, value] of Object.entries(query)) {
+                if (value !== undefined && value !== null)
+                    params.set(key, String(value));
+            }
             const suffix = params.toString();
             return requestOxygen(`/api/cli/inbox/drafts${suffix ? `?${suffix}` : ""}`);
         });
@@ -15556,15 +15592,15 @@ Examples:
         });
     })));
     program.addCommand(new Command("sequences")
-        .description("Multichannel outreach sequences: one enrollment per lead can span LinkedIn, email, WhatsApp, human call tasks, and connected-CRM tasks. LinkedIn steps dispatch natively (rate-limited, credit-capped); email steps send natively or place/move/stop the lead in a bound Instantly campaign (BYOK); crm_task can exact-match/upsert/link CRM records and create a mapped external follow-up (HubSpot first), with replay-safe per-operation receipts. A reply always stops that lead, on every channel. To also pause the replier's colleagues, set `--company-reply-pause` on `create`/`update` (pick the reply categories); to pause or resume a company by hand or from a workflow (e.g. a meeting was booked), use `pause-company` / `resume-company` / `paused-companies`. A pause is resumable; a company do-not-contact entry (`suppressions`) is a permanent block.")
-        .addCommand(new Command("list")
+        .description("Multichannel outreach sequences: one enrollment per lead can span LinkedIn, email, WhatsApp, human call tasks, and connected-CRM tasks. LinkedIn steps dispatch natively within sender limits, with zero additional credits per action; connected-account monthly charges remain separate; email steps send natively or place/move/stop the lead in a bound Instantly campaign (BYOK); crm_task can exact-match/upsert/link CRM records and create a mapped external follow-up (HubSpot first), with replay-safe per-operation receipts. A reply always stops that lead, on every channel. To also pause the replier's colleagues, set `--company-reply-pause` on `create`/`update` (pick the reply categories); to pause or resume a company by hand or from a workflow (e.g. a meeting was booked), use `pause-company` / `resume-company` / `paused-companies`. A pause is resumable; a company do-not-contact entry (`suppressions`) is a permanent block.")
+        .addCommand(addContractFlags(new Command("list")
         .description("List sequences with persisted launch status kept separate from current operational state. Fleet counts report marked-active versus operationally-live (active with nonterminal work), and rows explain flowing, paced, paused, blocked, degraded, drained, or empty work without SQL. An active sequence whose every lead has finished shows drained (completed); leads enrolled into it later are contacted on its next dispatch tick. --stats joins each row's LIFETIME funnel.")
         .option("--status <status>", "Filter by status: draft, active, paused, or archived.")
         .addOption(new Option("--operational-state <state>", "Filter by current work state; fleet counts remain unfiltered: empty, drained, never_started (enrolled leads, never launched), blocked, degraded, flowing, paced, or paused (work waiting on a paused sequence).").choices(["empty", "drained", "never_started", "blocked", "degraded", "flowing", "paced", "paused"]))
         .addOption(new Option("--lifecycle <lifecycle>", "Filter by the lifecycle a person reads; fleet counts remain unfiltered: draft, active, completed (active, every lead finished), paused, or archived.").choices([...SEQUENCE_LIFECYCLES]))
         .addOption(new Option("--channel <channel>", "Only sequences carrying this channel.").choices(["email", "linkedin", "whatsapp"]))
         .option("--tag <tag>", "Only sequences carrying this workspace tag (see `oxygen tags list`).")
-        .option("--stats", "Attach lifetime stats per sequence (a stats pass per row — slower on large workspaces).")
+        .option("--stats", "Attach lifetime stats per sequence (a stats pass per row — slower on large workspaces)."), SEQUENCE_LIST_PROJECTION_CONTRACT)
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleReadActionWithLens("sequences list", options, () => {
@@ -15586,6 +15622,10 @@ Examples:
                 params.set("tag", tag);
             if (options.stats)
                 params.set("include", "stats");
+            const projection = readContractFlags(options, SEQUENCE_LIST_PROJECTION_CONTRACT);
+            const omit = typeof projection.omit === "string" ? readOption(projection.omit) : undefined;
+            if (omit)
+                params.set("omit", omit);
             const suffix = params.toString();
             return requestOxygen(`/api/cli/sequences${suffix ? `?${suffix}` : ""}`);
         }, formatSequenceListHealth);
@@ -15844,7 +15884,7 @@ Examples:
         .option("--channels <list>", "Comma-separated channels: linkedin,email,whatsapp,call,crm. Defaults to the channels the journey touches. crm_task currently supports HubSpot.")
         .option("--whatsapp-cold-initiate", "WhatsApp: allow cold-initiating new chats (no prior conversation). Required to start a WhatsApp sequence live — WhatsApp via Unipile is unofficial WhatsApp Web, so cold-initiating is an explicit ban-risk opt-in.")
         .option("--phone-column-key <key>", "WhatsApp: row_values key holding each lead's phone number (else falls back to phone/phone_number/mobile).")
-        .option("--senders <ids>", "Comma-separated LinkedIn or WhatsApp sender account ids (or connection / Unipile ids; `linkedin senders` / `whatsapp accounts` list them). Optional at create; enroll and start require at least one when the journey has LinkedIn or WhatsApp steps (attach later with `sequences update --senders`).")
+        .option("--senders <ids>", "Comma-separated LinkedIn or WhatsApp sender account ids (or connection / Unipile ids; `senders list` / `whatsapp accounts` list them). Optional at create; enroll and start require at least one when the journey has LinkedIn or WhatsApp steps (attach later with `sequences update --senders`).")
         .option("--table <id>", "Source table id or slug whose rows supply {{column}} template values.")
         .option("--from-table <id>", "Alias of --table: the source table id or slug this sequence draws its leads and {{column}} values from.")
         .option("--enroll", "After creating the sequence, immediately enroll every row of the bound table (same as running `sequences enroll --from-table` next). Requires --table/--from-table. Enrolling spends no credits and sends nothing.")
@@ -15852,8 +15892,8 @@ Examples:
         .option("--email-provider <provider>", "Omit for native email through connected Google/Microsoft mailboxes, including Microsoft SMTP transport. Set 'instantly' to bind an Instantly campaign with --email-connection and --email-definition-file. To push rows into a campaign you already run in Smartlead, lemlist, HeyReach or Instantly, use `oxygen sequences push-external`.")
         .option("--email-connection <id>", "Instantly connection id for the email track. Defaults to the org's active Instantly connection.")
         .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-credits <n>", "Stored credit ceiling (0 or more); 0 is valid for a draft. Omit to leave the ceiling unset. Creating a draft sends nothing; live start has its own approval and recipient limits.")
+        .option("--max-live-sends <n>", "Total live-send and CRM-write ceiling across channels, including LinkedIn invites/messages (positive integer). Required for live email/WhatsApp/CRM-task tracks; optional for LinkedIn.")
         .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("--schedule-timezone <tz>", "One sending schedule for every channel, the same as Launch's Sending schedule: IANA zone, e.g. Europe/Berlin. Give it with --schedule-days, --schedule-hours-start and --schedule-hours-end; it sets the email window and the LinkedIn/WhatsApp window together. Without it, email sends weekdays 09:00-17:00 UTC. To give one channel different hours, or to send email in each recipient's own timezone, run `sequences update` after creating (--send-window-file, --linkedin-*).")
         .option("--schedule-days <days>", "Sending schedule days: mon-fri, mon,wed,fri, or ISO numbers 1-7 (1 = Monday).")
@@ -15895,7 +15935,7 @@ Examples:
             const senders = readCsvOption(options.senders);
             const tags = readCsvOption(options.tags);
             const email = readCampaignEmailBinding(options);
-            const maxCredits = readPositiveNumber(options.maxCredits);
+            const maxCredits = readCreditCeilingOrZero(options.maxCredits);
             const maxLiveSends = readPositiveInt(options.maxLiveSends);
             const settings = readSequenceSettings(options);
             // `--from-table` is the phrase customers already use for enroll,
@@ -15966,14 +16006,14 @@ Examples:
         .option("--phone-column-key <key>", "WhatsApp: row_values key holding each lead's phone number (else falls back to phone/phone_number/mobile).")
         .option("--email-column-key <key>", "Native email: row_values key holding each lead's email (else falls back to email/email_address/work_email). Maps a non-English header (e.g. E-Mail).")
         .option("--linkedin-url-column-key <key>", "LinkedIn: row_values key holding each lead's profile URL (else falls back to linkedin_url/linkedinUrl/linkedin/profile_url). \"\" clears it back to auto-detect.")
-        .option("--senders <ids>", "Comma-separated LinkedIn or WhatsApp sender account ids (or connection / Unipile ids; `linkedin senders` / `whatsapp accounts` list them).")
+        .option("--senders <ids>", "Comma-separated LinkedIn or WhatsApp sender account ids (or connection / Unipile ids; `senders list` / `whatsapp accounts` list them).")
         .option("--source-table <idOrSlug>", "Bind the table this sequence enrolls leads from (id or slug). Only lands while the sequence has no source table yet (first-writer-wins); its rows become enrollable leads. Draft/paused only.")
         .option("--email-provider <provider>", "Optional linked-campaign provider: 'instantly'. Omit to preserve the existing binding; --clear-email removes it on a draft. Native email needs no provider binding and sends through connected Google/Microsoft mailboxes, including Microsoft SMTP transport.")
         .option("--email-connection <id>", "Instantly connection id for the email track.")
         .option("--email-definition-file <path>", "Path to a JSON file with the email content spec (subjects/bodies/delays/subsequences).")
         .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-credits <n>", "Stored draft credit ceiling (0 or more); 0 is valid. Changing a started sequence's cap requires its normal live-start approval.")
+        .option("--max-live-sends <n>", "Draft-time total live-send and CRM-write ceiling across channels, including LinkedIn invites/messages (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; 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("--schedule-timezone <tz>", "One sending schedule for every channel, the same as Launch's Sending schedule: IANA zone, e.g. Europe/Berlin. Give it with --schedule-days, --schedule-hours-start and --schedule-hours-end; it sets the email window and the LinkedIn/WhatsApp window together. Use it instead of --send-window-file and the --linkedin-* flags. Email set to send in each recipient's own timezone keeps doing so, with this zone for leads that have none.")
         .option("--schedule-days <days>", "Sending schedule days: mon-fri, mon,wed,fri, or ISO numbers 1-7 (1 = Monday).")
@@ -16042,7 +16082,7 @@ Examples:
             if (options.linkedinUrlColumnKey !== undefined) {
                 body.linkedin_url_column_key = readOption(options.linkedinUrlColumnKey) ?? "";
             }
-            const maxCredits = readPositiveNumber(options.maxCredits);
+            const maxCredits = readCreditCeilingOrZero(options.maxCredits);
             if (maxCredits !== undefined)
                 body.max_credits = maxCredits;
             const maxLiveSends = readPositiveInt(options.maxLiveSends);
@@ -16178,13 +16218,13 @@ Examples:
         .description("Preview or start a sequence. Without --approved this is the launch check and changes nothing: it returns launch_readiness (blockers such as a missing send cap or the WhatsApp cold-initiate opt-in, plus warnings), who sends each step (sender_journey: each step's From, its candidate inboxes and how a lead's inbox is picked; no leads needed), scans pending LinkedIn copy, and returns exact rendered recipient samples, character counts/limits, copy blockers, per-kind scope, sender/mailbox capacity, CRM readiness, and safety caps. Live start requires --approved; --max-credits is optional. Email/WhatsApp/CRM-task journeys additionally require --max-live-sends because their external actions cost 0 Oxygen credits. --dry-run is not this preview: it starts the sequence in simulated mode (it leaves draft), with no send, provider campaign, CRM task, or credits. The first live start also switches on the standing reply → CRM automation for the workspace.")
         .argument("<sequence>", "Sequence id or slug.")
         .option("--approved", "Approve and activate live. Without this flag, returns a preview only, including copy_preview rendered samples and blockers.")
-        .option("--max-credits <n>", "Optional credit ceiling for the LinkedIn track (omit for an unbounded run).")
-        .option("--max-live-sends <n>", "Live external-action ceiling (positive integer). Required for email, WhatsApp, or crm_task steps.")
+        .option("--max-credits <n>", "Optional positive credit ceiling. Omit for the free launch preview. Live start uses the saved ceiling when omitted; an unset ceiling means unbounded credits, not recipient approval.")
+        .option("--max-live-sends <n>", "Total live-send and CRM-write ceiling across channels, including LinkedIn invites/messages (positive integer). Required for email, WhatsApp, or crm_task steps; optional for LinkedIn.")
         .option("--dry-run", "Activate the sequence (status draft → active, startedAt set) in dry-run mode: every step advances with simulated actions — no sends, CRM writes, provider calls, or credits. This is NOT the preview: `sequences start` with no flags is the side-effect-free launch preview. A later live start (--approved) restarts those leads from the first step so they are contacted for real, except deleted source rows, a person another live campaign contacts under exclude_contacted, and older duplicates of a person.")
         .option("--json", "Print a JSON envelope.")
         .action(async (sequence, options) => {
         await handleAsyncAction("sequences start", options, () => {
-            const maxCredits = readPositiveNumber(options.maxCredits);
+            const maxCredits = readPositiveNumber(options.maxCredits, "Omit --max-credits for the free launch preview. To set a live credit ceiling, pass a positive value after reviewing the preview; recipient approval remains separate.");
             const maxLiveSends = readPositiveInt(options.maxLiveSends);
             return requestOxygen(`/api/cli/sequences/${encodeURIComponent(sequence)}/start`, {
                 method: "POST",
@@ -17777,7 +17817,7 @@ Examples:
         await handleAsyncAction("mailboxes get", options, () => requestOxygen(`/api/cli/mailboxes/${encodeURIComponent(mailbox)}`));
     }))
         .addCommand(new Command("delete")
-        .description("Preview or approve removal of exact mailboxes from Oxygen at 0 credits. Deletion immediately removes them from sending but never deletes the underlying Google Workspace or Microsoft 365 accounts. It preserves conversation/message/delivery history and stops any separately listed 100-credit connected-mailbox commitment for future renewals; that line is currently built but not charged, and it is not the 100-credit OXYGEN Warm-up subscription. The current period is not refunded. Listed active/paused sequences keep their status but lose these senders and are not automatically paused. Without --cascade, a mailbox whose own warm-up or deliverability monitoring is still connected fails closed with its exact teardown steps; with --cascade, those add-ons are disconnected as part of the delete (their recurring credits stop too) and nothing is deleted unless every teardown is confirmed. A live managed DOMAIN subscription covers other mailboxes, so it fails closed unless the whole domain goes too: `oxygen domains delete <domain>`, or --include-domains when every inbox on it is selected.")
+        .description("Preview or approve removal of exact mailboxes from Oxygen at 0 credits. Deletion immediately removes them from sending but never deletes the underlying Google Workspace or Microsoft 365 accounts. It preserves conversation/message/delivery history and stops any separately listed 100-credit connected-mailbox commitment for future renewals; the preview reports whether that commitment is active and any separately billed OXYGEN Warm-up subscription. The current period is not refunded. Listed active/paused sequences keep their status but lose these senders and are not automatically paused. Without --cascade, a mailbox whose own warm-up or deliverability monitoring is still connected fails closed with its exact teardown steps; with --cascade, those add-ons are disconnected as part of the delete (their recurring credits stop too) and nothing is deleted unless every teardown is confirmed. A live managed DOMAIN subscription covers other mailboxes, so it fails closed unless the whole domain goes too: `oxygen domains delete <domain>`, or --include-domains when every inbox on it is selected.")
         .requiredOption("--mailboxes <list>", "Comma-separated mailbox ids or addresses (maximum 500).")
         .option("--approved", "Execute the fresh preview. Requires --plan-hash and --confirmation.")
         .option("--plan-hash <hash>", "Fresh preview plan_hash.")
@@ -18070,13 +18110,25 @@ Examples:
                 body: patch,
             });
         });
+    }))
+        .addCommand(new Command("sync")
+        .description("Read or control full Inbox, Sent and archive import for Gmail or Microsoft 365. History sync and CRM analysis are included in the mailbox’s 100-credit monthly connection. Spam, trash and drafts are excluded. Without --action, this is a free progress read; controls preview until --approved. Disconnect keeps imported mail and CRM records and stops sync and sends.")
+        .argument("<mailbox>", "Mailbox ID or exact email address.")
+        .option("--action <action>", "start, pause, resume or disconnect; omit to read progress.")
+        .option("--approved", "Apply the reviewed control; default is preview.")
+        .option("--dry-run", "Preview the control without changing sync.")
+        .option("--json", "Print JSON.")
+        .action(async (mailbox, options) => {
+        await handleAsyncAction("mailboxes sync", options, () => options.action
+            ? requestOxygen("/api/cli/mailboxes/sync", { method: "POST", body: { mailbox, action: options.action, approved: options.approved === true, dry_run: options.dryRun === true } })
+            : requestOxygen(`/api/cli/mailboxes/sync?${new URLSearchParams({ mailbox }).toString()}`));
     }))
         .addCommand(new Command("connect-oauth")
-        .description("Connect Google/Microsoft mailboxes to OXYGEN native send. Authorization costs 0 credits; once connected, each own mailbox reserves 100 credits per month when the repricing credit commitments are active, including warm-up. Preview by default; pass --approved only after reviewing exact candidates. --vendor oxygen requires an exact address list and never discovers a domain directory. Microsoft supports --authorization-mode tenant (one administrator approval, up to 500 exact selected addresses, recommended for dedicated sending tenants) or individual (one account sign-in per mailbox, max 10 per run, recommended for ordinary company/personal mailboxes). For Microsoft's built-in roles, tenant mode requires a Global Administrator or Privileged Role Administrator because it requests the Microsoft Graph application Mail.Send and Mail.Read permissions; Application Administrator and Cloud Application Administrator cannot consent to Microsoft Graph application roles. Microsoft's application grant is tenant-wide at the provider; OXYGEN—not Microsoft—enforces the selected-address boundary at verification and send time unless the tenant separately configures Exchange Application RBAC. For non-managed Microsoft mailboxes, native-send approval does not authorize OXYGEN Warm-up: every mailbox still needs its own `mailboxes warmup microsoft` Outlook consent before standalone enrollment. Connecting authorization does not change whether a mailbox is active or disabled. Google uses individual OAuth. Source tokens, passwords, authenticator seeds, and one-time codes never transfer. Managed authorization paths remain available through their vendor options.")
+        .description("Connect Gmail/Microsoft 365 with --vendor composio to import all mail into Unibox and business activity into CRM. Each connected own mailbox costs 100 credits/month including history, sync and analysis; connection costs 0. Managed OAuth requires provider rollout readiness and exact registered addresses, max 10. Use mailboxes sync for progress and pause/resume/disconnect. Existing native OAuth remains available with --vendor oxygen. Warm-up retains its existing eligibility and pricing. Preview by default; pass --approved only after reviewing exact candidates. --vendor oxygen requires an exact address list and never discovers a domain directory. Microsoft supports --authorization-mode tenant (one administrator approval, up to 500 exact selected addresses, recommended for dedicated sending tenants) or individual (one account sign-in per mailbox, max 10 per run, recommended for ordinary company/personal mailboxes). For Microsoft's built-in roles, tenant mode requires a Global Administrator or Privileged Role Administrator because it requests the Microsoft Graph application Mail.Send and Mail.Read permissions; Application Administrator and Cloud Application Administrator cannot consent to Microsoft Graph application roles. Microsoft's application grant is tenant-wide at the provider; OXYGEN—not Microsoft—enforces the selected-address boundary at verification and send time unless the tenant separately configures Exchange Application RBAC. For non-managed Microsoft mailboxes, native-send approval does not authorize OXYGEN Warm-up: every mailbox still needs its own `mailboxes warmup microsoft` Outlook consent before standalone enrollment. Connecting authorization does not change whether a mailbox is active or disabled. Google uses individual OAuth. Source tokens, passwords, authenticator seeds, and one-time codes never transfer. Managed authorization paths remain available through their vendor options.")
         .addHelpText("after", "\nDocs: https://oxygen-agent.com/docs/providers/mailboxes\n")
         .option("--provider <provider>", "Mailbox provider to provision: google or microsoft.")
-        .option("--vendor <vendor>", "Authorization path: oxygen for imported/manual mailboxes, zapmail (default), or inboxkit.")
-        .option("--mailboxes <list>", "Comma-separated exact mailbox addresses. Required for vendor=oxygen (tenant mode max 500; individual mode max 10).")
+        .option("--vendor <vendor>", "Authorization path: composio for customer-owned Gmail/Microsoft 365 with managed consent, history and CRM; oxygen for native/tenant consent; zapmail (default) or inboxkit for provisioned inboxes.")
+        .option("--mailboxes <list>", "Comma-separated exact mailbox addresses. Required for vendor=composio (max 10) or vendor=oxygen (tenant mode max 500; individual mode max 10).")
         .option("--authorization-mode <mode>", "vendor=oxygen only: auto, tenant, or individual. Tenant is Microsoft-only and never scans the directory.")
         .option("--domains <list>", "Comma-separated sending domains to limit an inboxkit run to. Omit to cover every domain in the pool.")
         .option("--no-canary", "inboxkit only: fan out to every eligible mailbox on a domain that has never connected one, instead of firing a single canary first.")
@@ -19998,6 +20050,7 @@ Full trigger schema: oxygen workflows schema --subject trigger --json
     registerSettingsCommands(program, handleAsyncAction);
     registerCrmSupportFlags(program);
     registerCustomerOperationCommands(program, handleAsyncAction);
+    registerCrmFileReadCommands(program, handleAsyncAction);
     // After the register* helpers: help groups are assigned to the commands that
     // exist when this runs, and a family registered later fell into commander's
     // trailing default "Commands:" list (the 2026-09-30 blind agent read the first
@@ -22114,7 +22167,7 @@ function isNetworkTimeoutError(error) {
     return error instanceof OxygenError && error.code === "network_timeout";
 }
 function feedsListPath(options, tableArgument) {
-    const params = new URLSearchParams();
+    const params = feedReadWindowParams(options);
     const table = readOption(tableArgument) ?? readOption(options.table);
     const transport = readOption(options.transport);
     const status = readOption(options.status);
@@ -22136,7 +22189,8 @@ function feedsListPath(options, tableArgument) {
     return `/api/cli/tables/feeds${query ? `?${query}` : ""}`;
 }
 function feedsGetPath(feed, options) {
-    const params = new URLSearchParams({ feed });
+    const params = feedReadWindowParams(options, true);
+    params.set("feed", feed);
     if (options.includeCursor)
         params.set("include", "cursor");
     return `/api/cli/tables/feeds?${params.toString()}`;
@@ -22559,7 +22613,10 @@ function readCompaniesSearchRunBody(options, promptArg) {
     const maxPages = readPositiveInt(options.maxPages);
     const maxCredits = readPositiveNumber(options.maxCredits);
     const targetCount = readPositiveInt(options.targetCount);
-    const filters = prompt ? readCompanySearchFilters(options) : null;
+    // With --source the server reads only --source-filters-json. Forward the planner's
+    // filters anyway so the server refuses them by name instead of the CLI dropping
+    // them and the run buying an unfiltered search (OXP-1.39.2 S6).
+    const filters = prompt || options.source ? readCompanySearchFilters(options) : null;
     return {
         ...(prompt ? { prompt } : {}),
         ...(plan ? { plan } : {}),
@@ -22716,7 +22773,7 @@ function readSearchPlanJson(value) {
 }
 // Table-driven Employee Finder help, written once and shared by `people search
 // plan` and `people search run` so the price shape reads the same on both.
-const PEOPLE_SEARCH_FROM_TABLE_HELP = "Search every company LinkedIn URL in a table column for the people you describe — --titles, --exclude-titles, --seniorities, --job-functions, --education, location and --min-connections all apply per company. 10 credits per company per page; rows land in a new people table with a company relation back to each source row. Pass the table id or slug plus --linkedin-url-column, and bound it with --company-limit. For up to 50 companies this is the expensive way: people search preview with company.linkedin_url samples them free and people search run --source people_search charges one page across all of them.";
+const PEOPLE_SEARCH_FROM_TABLE_HELP = "Search every company LinkedIn URL in a table column for the people you describe — --titles, --exclude-titles, --seniorities, --job-functions, --education, location and --min-connections all apply per company. 1 credit per company per page; rows land in a new people table with a company relation back to each source row. Pass the table id or slug plus --linkedin-url-column, and bound it with --company-limit. For up to 50 companies this is the expensive way: people search preview with company.linkedin_url samples them free and people search run --source people_search charges one page across all of them.";
 const PEOPLE_SEARCH_LINKEDIN_COLUMN_HELP = "Column key in --from-table holding each company's LinkedIn URL.";
 const PEOPLE_SEARCH_COMPANY_OFFSET_HELP = "Skip this many companies in --from-table. Use it to source the rest after a first-company preview.";
 const PEOPLE_SEARCH_COMPANY_LIMIT_HELP = "Fetch people for at most this many companies from --from-table. Start with --company-limit 1.";
@@ -22811,9 +22868,13 @@ function readPeopleSearchRunBody(options) {
         }
         const maxCreditsNative = readPositiveNumber(options.maxCredits);
         const nativeTarget = readPositiveInt(options.targetCount);
+        // Forwarded so the server refuses them by name; the native lane reads only
+        // --source-filters-json (OXP-1.39.2 S6).
+        const plannerFilters = readPeopleSearchFilters(options);
         return {
             source: "people_search",
             source_filters: parseJsonObject(readFileIfPresent(options.sourceFiltersJson)),
+            ...(plannerFilters ? { filters: plannerFilters } : {}),
             ...(readOption(options.tableName) ? { table_name: readOption(options.tableName) } : {}),
             ...(options.table ? { table: options.table } : {}),
             ...(options.project ? { project: options.project } : {}),
@@ -29437,14 +29498,14 @@ function readPositiveNumberOrZero(value) {
     }
     return parsed;
 }
-function readPositiveNumber(value) {
+function readPositiveNumber(value, nextStep) {
     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 positive number.", {
-            details: { value },
+            details: { value, ...(nextStep ? { next_step: nextStep } : {}) },
             exitCode: 1,
         });
     }