@oxygen-agent/cli 1.1014.86 → 1.1014.118

package/README.md

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

package/dist/command-manifest.js

@@ -111,8 +111,11 @@ const MUTATING_COMMANDS = new Set([
     // The ledger audit reads that same balance first, with the same conditional writes.
     "billing audit",
     // Creates an approval or Checkout link; a first plan's Checkout can start the
-    // first-month offer window. The plan changes only after an admin confirms.
+    // first-month offer window. The plan changes only after confirmation.
     "billing change",
+    // No amount is a read; an amount/pack creates Stripe billing resources.
+    // The manifest describes all invocations, without inventing a credit debit.
+    "billing topup",
     "billing retain",
     // --approved records a domain's renewal exit, or with --revoke resumes renewals.
     "managed-inboxes exit",

package/dist/help.js

@@ -453,6 +453,11 @@ export function argvRequestsJson(argv) {
 }
 function buildUnknownCommandHint(parent, path, token) {
     const names = parent.commands.map((command) => command.name()).filter((name) => name !== "help");
+    const firstWord = token.trim().split(/\s+/)[0] ?? "";
+    if (/\s/.test(token) && parent.commands.some((command) => command.name() === firstWord || command.aliases().includes(firstWord))) {
+        const name = path.split(" ").slice(1).concat(firstWord).join(" ");
+        return `Hint: The subcommand and its options arrived as one argument. Pass them as separate shell arguments; quote individual values only. Inspect the grammar with \`${path.split(" ")[0]} commands get '${name}' --json\`.`;
+    }
     const lower = token.toLowerCase();
     // A read intent on a budget must never point at the mutating `set` command.
     const synonym = path.endsWith(" budget") && lower === "get" && names.includes("list")

package/dist/index.js

@@ -83,6 +83,7 @@ import { SEQUENCE_LIFECYCLES, sequenceDisplayStatus } from "@oxygen/shared/seque
 import { lookupColumnDataType } from "@oxygen/shared/table-field-types";
 import { FILTER_TREE_OPERATORS } from "@oxygen/shared/table-filter-operators";
 import { tableRunSummary } from "@oxygen/shared/table-run-summary";
+import { capabilityDiscoveryRecovery } from "@oxygen/shared/user-capability-routing";
 import { assertRecipeBundleSafe, assertPortableWorkflowDefinition, assertWorkflowGraphManifest, assertWorkflowManifest, buildRecipeManifest, compileWorkflowDefinition, isAnyWorkflowManifest, isRecipeManifest, isWorkflowDefinition, isWorkflowGraphManifest, isWorkflowManifest, hashPortableWorkflowGraphManifest, WORKFLOW_GRAPH_COMPILER_VERSION, WORKFLOW_GRAPH_MANIFEST_VERSION, } from "@oxygen/workflows";
 import { Command, CommanderError, Option } from "commander";
 import { execFileSync } from "node:child_process";
@@ -3676,6 +3677,7 @@ export function createProgram() {
     const program = new Command();
     const binaryName = resolveCliBinaryName();
     const directoryDocsUrl = `${defaultApiUrl()}/docs/agencies`;
+    const billingDocsUrl = `${defaultApiUrl()}/docs/safety/billing`;
     program
         .name(binaryName)
         .description("Revenue infrastructure for B2B startups — agent-operated GTM: tables, enrichment, sequences, workflows, CRM, knowledge. Everything here also runs in the web app and over MCP; every state-changing action returns a web_url deep-link.")
@@ -3955,10 +3957,13 @@ export function createProgram() {
         .action(async (queryParts, options) => {
         await handleAsyncAction("capabilities search", options, async () => {
             const query = queryParts.join(" ");
+            const route = inferUserCapabilityRoute(query);
             return {
                 query,
-                route: serializeCapabilityRoute(inferUserCapabilityRoute(query)),
-                hint: "Hydrate one exact CLI command with `oxygen commands get <exact-command> --json`, or one MCP tool with `oxygen_capabilities_schema`.",
+                route: serializeCapabilityRoute(route),
+                hint: route
+                    ? "Hydrate one exact CLI command with `oxygen commands get <exact-command> --json`, or one MCP tool with `oxygen_capabilities_schema`."
+                    : capabilityDiscoveryRecovery(query, "cli"),
                 alternate_search_hint: `If this route does not fit the outcome, run \`oxygen skills search ${JSON.stringify(query)} --json\` for a narrower operational play.`,
             };
         });
@@ -8532,9 +8537,8 @@ Examples:
         .option("--force", "Re-arm past an existing once-ever marker, the one deliberate way to research the same workspace twice. Without --live it only previews the re-arm for free: nothing is cleared or written. With --live it replaces the marker with a new pass and spends again.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
-        await handleAsyncAction("knowledge bootstrap", options, () => requestOxygen("/api/cli/knowledge/bootstrap", {
-            method: "POST",
-            body: {
+        await handleAsyncAction("knowledge bootstrap", options, () => {
+            const parameters = {
                 mode: options.live || options.approved ? "live" : "dry_run",
                 ...(readOption(options.domain) ? { domain: readOption(options.domain) } : {}),
                 ...(readOption(options.linkedin) ? { linkedin_url: readOption(options.linkedin) } : {}),
@@ -8542,8 +8546,11 @@ Examples:
                     ? { max_credits: readPositiveNumber(options.maxCredits) }
                     : {}),
                 ...(options.force ? { force: true } : {}),
-            },
-        }));
+            };
+            return parameters.mode === "live"
+                ? requestOxygen("/api/cli/knowledge/bootstrap", { method: "POST", body: parameters })
+                : requestOxygen(knowledgeReadPath("/api/cli/knowledge/bootstrap", parameters));
+        });
     })
         .addCommand(new Command("status")
         .description("Report the once-ever bootstrap marker for this workspace: status (queued, running, completed, partial, skipped, failed, or never attempted), when it ran, its system run id, the credits it actually spent, the domain researched, the reason it stopped, and the pages it wrote. Free, reads only, and the honest way to find out whether the automatic pass already happened before you spend on a manual one.")
@@ -8556,10 +8563,7 @@ Examples:
             ...options,
             json: options.json || Boolean(knowledgeBootstrapCommand.opts().json),
         };
-        await handleAsyncAction("knowledge bootstrap status", outputOptions, () => requestOxygen("/api/cli/knowledge/bootstrap", {
-            method: "POST",
-            body: { status: true },
-        }));
+        await handleAsyncAction("knowledge bootstrap status", outputOptions, () => requestOxygen("/api/cli/knowledge/bootstrap?status=true"));
     }));
     program
         .command("knowledge")
@@ -8696,13 +8700,10 @@ Examples:
         .action(async (slugOrId, options) => {
         await handleAsyncAction("knowledge page revisions", options, () => {
             const limit = readPositiveInt(options.limit);
-            return requestOxygen("/api/cli/knowledge/pages/revisions", {
-                method: "POST",
-                body: {
-                    ...knowledgePageRefBody(slugOrId),
-                    ...(limit !== undefined ? { limit } : {}),
-                },
-            });
+            return requestOxygen(knowledgeReadPath("/api/cli/knowledge/pages/revisions", {
+                ...knowledgePageRefBody(slugOrId),
+                ...(limit !== undefined ? { limit } : {}),
+            }));
         });
     }))
         .addCommand(new Command("revision")
@@ -8718,13 +8719,10 @@ Examples:
                     details: { revision },
                 });
             }
-            return requestOxygen("/api/cli/knowledge/pages/revisions/get", {
-                method: "POST",
-                body: {
-                    ...knowledgePageRefBody(slugOrId),
-                    revision: revisionNumber,
-                },
-            });
+            return requestOxygen(knowledgeReadPath("/api/cli/knowledge/pages/revisions/get", {
+                ...knowledgePageRefBody(slugOrId),
+                revision: revisionNumber,
+            }));
         });
     })))
         .addCommand(new Command("search")
@@ -8770,10 +8768,7 @@ Examples:
         .option("--depth <n>", "Local-graph hop depth (1-3, default 1). Only applies with --center.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
-        await handleAsyncAction("knowledge graph", options, () => requestOxygen("/api/cli/knowledge/graph", {
-            method: "POST",
-            body: buildKnowledgeGraphBody(options),
-        }));
+        await handleAsyncAction("knowledge graph", options, () => requestOxygen(knowledgeReadPath("/api/cli/knowledge/graph", buildKnowledgeGraphBody(options))));
     }))
         .addCommand(new Command("lint")
         .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.")
@@ -8802,10 +8797,7 @@ Examples:
         .option("--limit <n>", "Maximum log entries to return.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
-        await handleAsyncAction("knowledge log", options, () => requestOxygen("/api/cli/knowledge/log", {
-            method: "POST",
-            body: buildKnowledgeLogListBody(options),
-        }));
+        await handleAsyncAction("knowledge log", options, () => requestOxygen(knowledgeReadPath("/api/cli/knowledge/log", buildKnowledgeLogListBody(options))));
     }))
         .addCommand(new Command("append")
         .description("Append an entry to the knowledge log.")
@@ -8823,14 +8815,16 @@ Examples:
         .addCommand(new Command("proposals")
         .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("--limit <n>", "Maximum proposals to return. Defaults to 50; server caps at 200.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
-        await handleAsyncAction("knowledge proposals", options, () => requestOxygen("/api/cli/knowledge/proposals", {
-            method: "POST",
-            body: {
+        await handleAsyncAction("knowledge proposals", options, () => {
+            const limit = readPositiveInt(options.limit);
+            return requestOxygen(knowledgeReadPath("/api/cli/knowledge/proposals", {
                 ...(readOption(options.status) ? { status: readOption(options.status) } : {}),
-            },
-        }));
+                ...(limit !== undefined ? { limit } : {}),
+            }));
+        });
     })
         .addCommand(new Command("approve")
         .description("Approve a knowledge proposal and apply it to the target page.")
@@ -10869,13 +10863,30 @@ Examples:
         .addCommand(new Command("retry-failed")
         .description("Requeue failed items for a durable table action run. Items with an unconfirmed external effect stay blocked until their destination is verified and explicitly approved.")
         .argument("<run_id>", "Table action run UUID.")
+        .option("--dry-run", "Read the exact retry scope and approval hash without requeueing.")
+        .option("--approved", "Approve the inspected retry scope and additional-credit ceiling.")
+        .option("--retry-plan-hash <hash>", "Hash returned by the retry dry run.")
+        .option("--max-additional-credits <n>", "Fresh credit allowance for this recovery; never raises the original lifetime ceiling.")
         .option("--approved-effect-unknown", "After a human verifies every affected destination, explicitly allow re-executing items whose prior external effect could not be confirmed.")
         .option("--json", "Print a JSON envelope.")
         .action(async (runId, options) => {
-        await handleAsyncAction("table-runs retry-failed", options, () => requestOxygen(`/api/cli/table-action-runs/${encodeURIComponent(runId)}/retry-failed`, {
-            method: "POST",
-            body: options.approvedEffectUnknown ? { approved_effect_unknown: true } : {},
-        }));
+        if (options.dryRun && (options.approved || options.retryPlanHash || options.maxAdditionalCredits !== undefined || options.approvedEffectUnknown)) {
+            throw new OxygenError("invalid_request", "Use --dry-run separately from retry approval flags.", { exitCode: 2 });
+        }
+        const maxAdditionalCredits = options.maxAdditionalCredits === undefined ? undefined : Number(options.maxAdditionalCredits);
+        if (maxAdditionalCredits !== undefined && (!options.maxAdditionalCredits?.trim() || !Number.isFinite(maxAdditionalCredits) || maxAdditionalCredits < 0)) {
+            throw new OxygenError("invalid_request", "--max-additional-credits must be a nonnegative number.", { exitCode: 2 });
+        }
+        await handleAsyncAction("table-runs retry-failed", options, () => options.dryRun
+            ? requestOxygen(`/api/cli/table-action-runs/${encodeURIComponent(runId)}/retry-failed`, { method: "GET" })
+            : requestOxygen(`/api/cli/table-action-runs/${encodeURIComponent(runId)}/retry-failed`, {
+                method: "POST", body: {
+                    ...(options.approvedEffectUnknown ? { approved_effect_unknown: true } : {}),
+                    ...(options.approved !== undefined ? { approved: options.approved } : {}),
+                    ...(options.retryPlanHash !== undefined ? { retry_plan_hash: options.retryPlanHash } : {}),
+                    ...(maxAdditionalCredits !== undefined ? { max_additional_credits: maxAdditionalCredits } : {}),
+                },
+            }));
     }));
     program
         .command("table-ingestions")
@@ -11486,7 +11497,7 @@ Examples:
         .description("Plan-tier limits, spend-safety defaults, per-channel sending limits, and storage capacity posture. `limits show --section capacity` returns storage alone, including which Table is full.")
         .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(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)
+        .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: " + billingDocsUrl + "."), LIMITS_READ_QUERY_CONTRACT)
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("limits show", options, () => {
@@ -11529,9 +11540,9 @@ Examples:
     })));
     program
         .command("billing")
-        .description("Plan and managed credit commands. Credits reserved but not yet charged are listed hold by hold with `billing usage --meter holds`. 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.")
+        .description("Plan and managed credit commands. Credits reserved but not yet charged are listed hold by hold with `billing usage --meter holds`. 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: " + billingDocsUrl + ".")
         .addCommand(new Command("change")
-        .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.")
+        .description("Create an approval link (`approval_url`) to start or change a plan; no charge or plan change until confirmation. First purchase needs an admin/owner; existing-plan changes allow any unrestricted member. 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. Legacy prepaid yearly upgrades that keep their cadence apply immediately with proration; downgrades and term or cadence changes wait until the paid year 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
@@ -11563,7 +11574,7 @@ Examples:
         }));
     }))
         .addCommand(new Command("balance")
-        .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. 0 credits; reserves nothing. Due plan grants or credit expiry may apply.")
+        .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: " + defaultApiUrl() + "/billing. Policy: " + billingDocsUrl + ". 0 credits; reserves nothing. Due plan grants or credit expiry may apply.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("billing balance", options, () => requestOxygen("/api/cli/billing/balance"));
@@ -11634,7 +11645,7 @@ Examples:
         await handleAsyncAction("billing allowance", options, () => requestOxygen("/api/cli/billing/allowance"));
     }))
         .addCommand(new Command("usage")
-        .description("Show credit ledger events (each tagged with its FIXED/FLEXIBLE spend_class), workflow step usage (automation_actions: credits per step, credits billed; writing rows is free), calls with your own API keys (byok_calls: the platform fee per call and the fee credits this month; your provider bills the call itself), or connected LinkedIn and WhatsApp accounts (provider_seats: the rolling-30d peak and its implied connectivity cost; what each account is charged is its credit reservation in `billing commitments`). On a plan that pays for several workspaces (an agency covering client workspaces), `--group-by workspace` totals the credits each workspace spent (`by_workspace`) and `--workspace <id|slug>` narrows the ledger to one of them; a linked client workspace sees only its own spend. managed_credits_used counts captured credits; for where credits went by category, provider or tool, with shares, run `billing audit`.")
+        .description("Show credit ledger events (each tagged with its FIXED/FLEXIBLE spend_class), workflow step usage (automation_actions: credits per step, credits billed; writing rows is free), calls with your own API keys (byok_calls: the platform fee per successful call and the fee credits this month; vendor charges follow your provider's terms), or connected LinkedIn and WhatsApp accounts (provider_seats: the rolling-30d peak and its implied connectivity cost; what each account is charged is its credit reservation in `billing commitments`). On a plan that pays for several workspaces (an agency covering client workspaces), `--group-by workspace` totals the credits each workspace spent (`by_workspace`) and `--workspace <id|slug>` narrows the ledger to one of them; a linked client workspace sees only its own spend. managed_credits_used counts captured credits; for where credits went by category, provider or tool, with shares, run `billing audit`.")
         .option("--meter <meter>", "credits, automation_actions, byok_calls, provider_seats (rolling-30d peak connected accounts and the flat per-account charge; each account's reservation is listed by `billing commitments`), or holds (each held reservation behind reserved_credits in this workspace: credits, run, why it is held (an unmarked LinkedIn lookup hold cannot say whether its result was unknown or delivered), and automatic_return: LinkedIn lookup holds from 24 hours to 30 days old and explicitly unknown LeadMagic email-validation holds older than 24 hours are eligible while automatic return is switched on, and an hourly release returns it on a later pass with no fixed deadline; read-only, newest first, --days up to 365 and --limit apply). Defaults to credits.")
         .option("--days <n>", "Lookback window in days. Defaults to 30.")
         .option("--from <iso>", "Only include ledger events at or after this ISO timestamp.")
@@ -11790,7 +11801,7 @@ Examples:
         await handleAsyncAction("billing retain", options, () => requestOxygen("/api/cli/billing/cancel", { method: "POST", body: { action: "retain", offer_id: options.offer } }));
     }))
         .addCommand(new Command("topup")
-        .description("Buy a custom amount of on-demand credits. Run without an amount to see the current price per 100 credits (`usd_per_100_credits`), the allowed range and the packs; checkout happens in Stripe, the price is shown before you pay, and purchased credits never expire. Plan credits cost less. `usd_per_1k_credits` is a deprecated name for the same per-100 price, not a price per 1,000 credits.")
+        .description("No amount: read-only price quote, no checkout. With --credits or a pack: create Stripe Checkout and possibly billing resources; no charge until payment. Read tax_basis and review tax and the final total in Checkout. Prices are per 100 credits (`usd_per_100_credits`); credits arrive after confirmed payment and never expire. Plan credits cost less. `usd_per_1k_credits` is a deprecated name for the same per-100 price, not a price per 1,000 credits. `default_credits` is the web form's initial custom selection, not a purchase or minimum.")
         .argument("[pack]", "A pack id from the list shown when you run without an amount.")
         .option("--credits <n>", "Credits to buy (800-100,000 in 100-credit increments).")
         .option("--json", "Print a JSON envelope.")
@@ -13411,7 +13422,7 @@ Examples:
         .command("enrich-column")
         .description("High-level table enrichment helpers. To see every enrichment a table's columns support, with per-row prices, before choosing one, run `tools search --for-table <table>` (0 credits).")
         .addCommand(new Command("preview")
-        .description("Preflight an enrichment column without provider calls or credit usage. A lane on your own key (BYOK) is quoted at OXYGEN's platform fee per call, hit or miss (provider_cost_breakdown[].byok_platform_fee_credits_per_call).")
+        .description("Preflight an enrichment column without provider calls or credit usage. A lane on your own key (BYOK) is quoted at OXYGEN's platform fee per successful call, including a successful miss; vendor charges follow your provider's terms (provider_cost_breakdown[].byok_platform_fee_credits_per_call).")
         .argument("<table>", "Table id or slug.")
         .option("--source-column <column>", "Source column key or id. For mobile_phone this is the LinkedIn URL column.")
         .option("--full-name-column <column>", "Column key or id containing the person's full name for work_email. Pair with company-domain/name for Prospeo, LeadMagic, Hunter, Dropleads, ContactOut, BetterContact, or People Data Labs.")
@@ -13503,7 +13514,7 @@ Examples:
         .option("--company-domain <domain>", "Company apex domain, e.g. acme.com.")
         .option("--company-name <name>", "Company name.")
         .option("--mode <mode>", "dry_run (default) previews the plan and spends nothing; live spends credits and returns the answer.")
-        .option("--max-credits <credits>", "Spend ceiling in Oxygen credits; a lane that runs on your own provider key bills your provider account and is outside it (cap that with `oxygen limits provider set`). Required for --mode live. Run the free dry_run first: it returns estimate.recommended_max_credits, the ceiling that lets the WHOLE resolved waterfall run, plus estimate.min_credits and a per-leg breakdown. When the resolved chain runs the guessed-address pass (the name+domain and first/last+domain profiles, not the LinkedIn-URL one) the block also carries estimate.pattern_guess_verification_credits — the verification checks that pass bills before any named provider is dialled. A lower ceiling does NOT stop the run: each lane priced above what is left of it is refused on its own (spend_cap_too_low) and the waterfall advances, so a cheaper lane further down the chain can still run and bill.")
+        .option("--max-credits <credits>", "Spend ceiling in Oxygen credits, including the platform fee on each successful own-key call, even on a miss. Your provider may separately bill your account under its own rules, outside this ceiling (cap own-key calls with `oxygen limits provider set`). Required for --mode live. Run the free dry_run first: it returns estimate.recommended_max_credits, the ceiling that lets the WHOLE resolved waterfall run, plus estimate.min_credits and a per-leg breakdown. When the resolved chain runs the guessed-address pass (the name+domain and first/last+domain profiles, not the LinkedIn-URL one) the block also carries estimate.pattern_guess_verification_credits — the verification checks that pass bills before any named provider is dialled. A lower ceiling does NOT stop the run: each lane priced above what is left of it is refused on its own (spend_cap_too_low) and the waterfall advances, so a cheaper lane further down the chain can still run and bill.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("find email", options, () => requestOxygen("/api/cli/find/run", { method: "POST", body: buildFindBody("email", options) }));
@@ -13516,7 +13527,7 @@ Examples:
         .option("--company-domain <domain>", "Company apex domain, e.g. acme.com.")
         .option("--company-name <name>", "Company name.")
         .option("--mode <mode>", "dry_run (default) previews the plan and spends nothing; live spends credits and returns the answer.")
-        .option("--max-credits <credits>", "Spend ceiling in Oxygen credits; a lane that runs on your own provider key bills your provider account and is outside it (cap that with `oxygen limits provider set`). Required for --mode live. Run the free dry_run first: it returns estimate.recommended_max_credits, the ceiling that lets the WHOLE resolved waterfall run, plus estimate.min_credits and a per-leg breakdown. A lower ceiling does NOT stop the run: each lane priced above what is left of it is refused on its own (spend_cap_too_low) and the waterfall advances, so a cheaper lane further down the chain can still run and bill.")
+        .option("--max-credits <credits>", "Spend ceiling in Oxygen credits, including the platform fee on each successful own-key call, even on a miss. Your provider may separately bill your account under its own rules, outside this ceiling (cap own-key calls with `oxygen limits provider set`). Required for --mode live. Run the free dry_run first: it returns estimate.recommended_max_credits, the ceiling that lets the WHOLE resolved waterfall run, plus estimate.min_credits and a per-leg breakdown. A lower ceiling does NOT stop the run: each lane priced above what is left of it is refused on its own (spend_cap_too_low) and the waterfall advances, so a cheaper lane further down the chain can still run and bill.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("find personal-email", options, () => requestOxygen("/api/cli/find/run", { method: "POST", body: buildFindBody("personal_email", options) }));
@@ -13530,7 +13541,7 @@ Examples:
         .option("--company-name <name>", "Company name.")
         .option("--verify", "Verify the found number with ClearoutPhone — adds line_type/carrier and keeps the number on a non-verdict (only a genuine 'not valid' is discarded).")
         .option("--mode <mode>", "dry_run (default) previews the plan and spends nothing; live spends credits and returns the answer.")
-        .option("--max-credits <credits>", "Spend ceiling in Oxygen credits; a lane that runs on your own provider key bills your provider account and is outside it (cap that with `oxygen limits provider set`). Required for --mode live. Run the free dry_run first: it returns estimate.recommended_max_credits, the ceiling that lets the WHOLE resolved waterfall run, plus estimate.min_credits and a per-leg breakdown. A lower ceiling does NOT stop the run: each lane priced above what is left of it is refused on its own (spend_cap_too_low) and the waterfall advances, so a cheaper lane further down the chain can still run and bill.")
+        .option("--max-credits <credits>", "Spend ceiling in Oxygen credits, including the platform fee on each successful own-key call, even on a miss. Your provider may separately bill your account under its own rules, outside this ceiling (cap own-key calls with `oxygen limits provider set`). Required for --mode live. Run the free dry_run first: it returns estimate.recommended_max_credits, the ceiling that lets the WHOLE resolved waterfall run, plus estimate.min_credits and a per-leg breakdown. A lower ceiling does NOT stop the run: each lane priced above what is left of it is refused on its own (spend_cap_too_low) and the waterfall advances, so a cheaper lane further down the chain can still run and bill.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("find phone", options, () => requestOxygen("/api/cli/find/run", { method: "POST", body: buildFindBody("phone", options) }));
@@ -13543,7 +13554,7 @@ Examples:
         .option("--company-name <name>", "Company name.")
         .option("--company-linkedin-url <url>", "Company LinkedIn URL.")
         .option("--mode <mode>", "dry_run (default) previews the plan and spends nothing; live spends credits and returns the answer.")
-        .option("--max-credits <credits>", "Spend ceiling in Oxygen credits; a lane that runs on your own provider key bills your provider account and is outside it (cap that with `oxygen limits provider set`). Required for --mode live. Run the free dry_run first: it returns estimate.recommended_max_credits, the ceiling that lets the WHOLE resolved waterfall run, plus estimate.min_credits and a per-leg breakdown. A lower ceiling does NOT stop the run: each lane priced above what is left of it is refused on its own (spend_cap_too_low) and the waterfall advances, so a cheaper lane further down the chain can still run and bill.")
+        .option("--max-credits <credits>", "Spend ceiling in Oxygen credits, including the platform fee on each successful own-key call, even on a miss. Your provider may separately bill your account under its own rules, outside this ceiling (cap own-key calls with `oxygen limits provider set`). Required for --mode live. Run the free dry_run first: it returns estimate.recommended_max_credits, the ceiling that lets the WHOLE resolved waterfall run, plus estimate.min_credits and a per-leg breakdown. A lower ceiling does NOT stop the run: each lane priced above what is left of it is refused on its own (spend_cap_too_low) and the waterfall advances, so a cheaper lane further down the chain can still run and bill.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("find linkedin", options, () => requestOxygen("/api/cli/find/run", { method: "POST", body: buildFindBody("linkedin", options) }));
@@ -13561,7 +13572,7 @@ Examples:
         .option("--company-name <name>", "Company name.")
         .option("--include-raw", "Also return the provider's raw profile payload (profile_raw) for fields the profile block does not carry.")
         .option("--mode <mode>", "dry_run (default) previews the plan and spends nothing; live spends credits and returns the profile.")
-        .option("--max-credits <credits>", "Spend ceiling in Oxygen credits; a lane that runs on your own provider key bills your provider account and is outside it (cap that with `oxygen limits provider set`). Required for --mode live. Run the free dry_run first: estimate.recommended_max_credits funds the profile lookup plus, for an email or name input, every lane of the LinkedIn URL waterfall that resolves it.")
+        .option("--max-credits <credits>", "Spend ceiling in Oxygen credits, including the platform fee on each successful own-key call, even on a miss. Your provider may separately bill your account under its own rules, outside this ceiling (cap own-key calls with `oxygen limits provider set`). Required for --mode live. Run the free dry_run first: estimate.recommended_max_credits funds the profile lookup plus, for an email or name input, every lane of the LinkedIn URL waterfall that resolves it.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("find person", options, () => requestOxygen("/api/cli/find/run", { method: "POST", body: buildFindBody("person", options) }));
@@ -13575,7 +13586,7 @@ Examples:
         .option("--list-fields", "Print the field catalog (category, description, provider count, per-row credits: free / fixed / ~estimated) and exit. Needs no identity; spends nothing.")
         .option("--check-technologies <names>", "Comma-separated technology names for the technology_check field, answered yes/no against the detected stack (e.g. hubspot,salesforce).")
         .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 in Oxygen credits; a lane that runs on your own provider key bills your provider account and is outside it (cap that with `oxygen limits provider set`). Required for --mode live; 0 can still call providers on zero-credit lanes and reuse any priced lane this workspace already has a cached answer for (the other priced lanes are skipped as credit_ceiling_reached). Run the free dry_run first: it returns estimate.recommended_max_credits, the ceiling that funds every lane in the plan, and estimate.min_credits, what the plan costs if each field is answered by its first lane.")
+        .option("--max-credits <credits>", "Spend ceiling in Oxygen credits, including the platform fee on each successful own-key call, even on a miss. Your provider may separately bill your account under its own rules, outside this ceiling (cap own-key calls with `oxygen limits provider set`). Required for --mode live; 0 can still call providers on zero-credit lanes and reuse any priced lane this workspace already has a cached answer for (the other priced lanes are skipped as credit_ceiling_reached). Run the free dry_run first: it returns estimate.recommended_max_credits, the ceiling that funds every lane in the plan, and estimate.min_credits, what the plan costs if each field is answered by its first lane.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("find company", options, () => requestOxygen("/api/cli/find/run", { method: "POST", body: buildFindBody("company", options) }));
@@ -16468,6 +16479,8 @@ Examples:
         .option("--schedule-hours-start <HH:MM>", "Sending schedule start, local to --schedule-timezone, e.g. 09:00.")
         .option("--schedule-hours-end <HH:MM>", "Sending schedule end (exclusive), e.g. 17:00. An email step's own send_window (on the step in --steps-file) still overrides it for that step. LinkedIn sends also stay inside each LinkedIn account's working hours (default 07:00-22:00 in the account's timezone; set with `oxygen senders limits set`); WhatsApp accounts and email mailboxes have no hours of their own.")
         .option("--send-window-file <path>", "Email-only window JSON: { timezone, days?, start, end, timezone_mode?, recipient_timezone_column? }; days are ISO 1-7. New sequences default to weekdays 09:00-17:00 UTC. Use it to keep email on different hours from LinkedIn/WhatsApp, or to send in each recipient's own timezone (timezone_mode recipient, which --schedule-* then keeps); for one schedule across channels, use --schedule-* instead.")
+        .option("--linkedin-invite-schedule <json>", 'LinkedIn invites only: { "timezone": "Europe/Berlin", "days": [1,2,3,4,5,6,7], "start": "09:00", "end": "17:00" }. Replaces the general Sequence schedule for invites; account working hours still apply. null restores the general schedule.')
+        .option("--linkedin-message-schedule <json>", 'LinkedIn messages and InMail only: { "timezone": "Europe/Berlin", "days": [1,2,3,4,5], "start": "10:00", "end": "16:00" }. Replaces the general Sequence schedule for messages; account working hours still apply. null restores the general schedule.')
         .option("--linkedin-timezone <tz>", "LinkedIn/WhatsApp-only sending schedule: IANA zone, e.g. Europe/Zurich. Set with --linkedin-days, --linkedin-hours-start and --linkedin-hours-end; for LinkedIn the window narrows each account's working hours, for WhatsApp it is the only hours limit. For one schedule across channels, use --schedule-* instead.")
         .option("--linkedin-days <days>", "LinkedIn sending schedule days: mon-fri, mon,wed,fri, or ISO numbers 1-7 (1 = Monday).")
         .option("--linkedin-hours-start <HH:MM>", "LinkedIn sending schedule start, local to --linkedin-timezone, e.g. 06:45.")
@@ -29604,6 +29617,12 @@ function buildKnowledgePageListBody(options) {
         ...(limit !== undefined ? { limit } : {}),
     };
 }
+function knowledgeReadPath(path, parameters) {
+    const query = new URLSearchParams(Object.entries(parameters)
+        .filter(([, value]) => value !== undefined)
+        .map(([key, value]) => [key, String(value)]));
+    return query.size ? `${path}?${query}` : path;
+}
 function buildKnowledgeGraphBody(options) {
     const maxNodes = readPositiveInt(options.maxNodes);
     const center = readOption(options.center);
@@ -29649,6 +29668,7 @@ const KNOWLEDGE_SYNC_DEFAULT_TTL_MINUTES = 15;
 // 500 batches × the server's 100-page default is far above any v1 wiki; the cap
 // only exists so a misbehaving server can never wedge the CLI in a loop.
 const KNOWLEDGE_SYNC_MAX_BATCHES = 500;
+const KNOWLEDGE_SYNC_CATALOG_MAX_BATCHES = 500;
 // Envelope error codes meaning this org can no longer be read with the stored
 // token (revoked membership, expired key, org mismatch). The mirror is a local
 // cache of tenant data and must not outlive access to it.
@@ -29779,6 +29799,43 @@ function applyKnowledgeSyncPage(dir, state, page, counters) {
     };
     counters.synced += 1;
 }
+async function readKnowledgeMirrorCatalog(requestOrg, mirrorPath) {
+    let cursor = null;
+    const seenCursors = new Set();
+    const pages = new Map();
+    for (let batch = 0; batch < KNOWLEDGE_SYNC_CATALOG_MAX_BATCHES; batch += 1) {
+        const query = new URLSearchParams({ max_chars: "48000", limit: "1000", ...(cursor ? { cursor } : {}) });
+        const window = await requestOxygen(`/api/cli/knowledge/index?${query}`, requestOrg);
+        if (typeof window.has_more !== "boolean" || !Number.isInteger(window.max_chars) || window.max_chars < 2000 || window.max_chars > 48000 ||
+            !Array.isArray(window.index?.pages) || window.index.capped !== window.has_more ||
+            (window.next_cursor !== null && typeof window.next_cursor !== "string") || (!window.has_more && window.next_cursor !== null)) {
+            throw new OxygenError("knowledge_sync_catalog_invalid", "The knowledge catalog did not return a complete bounded continuation receipt. The generated index was left unchanged.", {
+                details: { catalog_cursor: cursor, mirror_path: mirrorPath }, exitCode: 1,
+            });
+        }
+        for (const page of window.index.pages) {
+            if (!page || typeof page.slug !== "string" || !page.slug || pages.has(page.slug)) {
+                throw new OxygenError("knowledge_sync_catalog_changed", "The catalog repeated or omitted a page slug during live traversal. Retry sync to restart the catalog; the generated index was left unchanged.", {
+                    details: { catalog_cursor: cursor, mirror_path: mirrorPath }, exitCode: 1,
+                });
+            }
+            pages.set(page.slug, page);
+        }
+        if (!window.has_more) {
+            return { ...window, index: { ...window.index, pages: [...pages.values()] } };
+        }
+        if (!window.next_cursor || seenCursors.has(window.next_cursor)) {
+            throw new OxygenError("knowledge_sync_catalog_stalled", "The catalog cursor did not advance; the generated index was left unchanged. Retry sync to restart the catalog from the preserved page watermark.", {
+                details: { catalog_cursor: cursor, next_cursor: window.next_cursor, mirror_path: mirrorPath }, exitCode: 1,
+            });
+        }
+        cursor = window.next_cursor;
+        seenCursors.add(cursor);
+    }
+    throw new OxygenError("knowledge_sync_catalog_incomplete", "The catalog batch cap was reached before its terminal receipt. The generated index was left unchanged; retry sync to restart the catalog from the preserved page watermark.", {
+        details: { catalog_cursor: cursor, mirror_path: mirrorPath, batch_cap: KNOWLEDGE_SYNC_CATALOG_MAX_BATCHES }, exitCode: 1,
+    });
+}
 // `orgOverride` targets a specific org (used by `sync --all`): it names the mirror
 // directory explicitly and pins X-Oxygen-Organization on every request in the
 // loop, so each workspace clones into its own mirror regardless of the cached
@@ -29842,11 +29899,12 @@ options, orgOverride) {
                 lastSeen = { updated_at: page.updated_at, id: page.id };
             }
             if (!delta.has_more) {
-                // Completed. Persist the watermark AFTER the last seen page — the delta
-                // keyset is (updated_at, id) ascending and updated_at is the server's own
-                // ISO rendering, so `<updated_at>|<id>` is exactly the server cursor and
-                // the next sync fetches only pages updated since.
-                if (lastSeen)
+                // The native SQL watermark retains timestamp precision that the public
+                // updated_at Date can lose. Older servers lack last_cursor; retain their
+                // compatibility fallback without claiming it preserves SQL precision.
+                if (delta.last_cursor)
+                    state.cursor = delta.last_cursor;
+                else if (lastSeen)
                     state.cursor = `${lastSeen.updated_at}|${lastSeen.id}`;
                 completed = true;
                 break;
@@ -29868,19 +29926,18 @@ options, orgOverride) {
                 exitCode: 1,
             });
         }
-        // Generated summaries come from the server's own projections, not a client-side
-        // recomputation. A real wiki page may own the `index`/`log` slug — page bytes win.
-        // `all=true` on purpose: the generated index.md must list every page this
-        // mirror just cloned, and the route's default is a 200-page window.
-        const index = await requestOxygen("/api/cli/knowledge/index?all=true", requestOrg);
-        const logPage = await requestOxygen("/api/cli/knowledge/log", {
-            method: "POST",
-            body: {},
-            ...requestOrg,
-        });
-        if (!state.pages.index)
+        // Save page progress before summary reads so a failed catalog can resume its
+        // delta without declaring a fresh, fully completed mirror.
+        state.last_sync_at = null;
+        writeMirrorState(target.dir, state);
+        // Traverse every native catalog window, including shared-only continuations.
+        // Its scope excludes archived/proposal pages; it is a live keyset, not a
+        // snapshot of every cloned page. Real `index`/`log` page bytes take priority.
+        const index = state.pages.index ? null : await readKnowledgeMirrorCatalog(requestOrg, target.dir);
+        const logPage = state.pages.log ? null : await requestOxygen("/api/cli/knowledge/log", requestOrg);
+        if (index)
             writeGeneratedIndexFile(target.dir, index.index);
-        if (!state.pages.log)
+        if (logPage)
             writeGeneratedLogFile(target.dir, logPage.entries);
         state.last_sync_at = new Date().toISOString();
         writeMirrorState(target.dir, state);
@@ -30569,6 +30626,10 @@ function readSequenceSettings(options) {
     if (linkedinSchedule) {
         settings.schedule = linkedinSchedule;
     }
+    if (options.linkedinInviteSchedule !== undefined)
+        settings.linkedin_invite_schedule = parseJsonValue(options.linkedinInviteSchedule, "--linkedin-invite-schedule");
+    if (options.linkedinMessageSchedule !== undefined)
+        settings.linkedin_message_schedule = parseJsonValue(options.linkedinMessageSchedule, "--linkedin-message-schedule");
     // Tri-state: `--no-whatsapp-cold-initiate` (update) turns the opt-in off.
     if (options.whatsappColdInitiate !== undefined) {
         settings.whatsapp_cold_initiate = options.whatsappColdInitiate;

package/dist/skills.js

@@ -7,6 +7,7 @@ import { defaultApiUrl, loadCredentials, normalizeApiUrl } from "./credentials.j
 import { requestOxygen } from "./http-client.js";
 import { isRecord, readOption } from "./util.js";
 import { resolveCmdShimInvocation } from "./windows-shim.js";
+import { capabilityDiscoveryRecovery } from "@oxygen/shared/user-capability-routing";
 const DEFAULT_SKILL_AGENTS = ["codex", "claude-code", "cursor"];
 const SKILL_INDEX_PATH = "/.well-known/skills/index.json";
 const SKILLS_ACCESS_API_PATH = "/api/cli/skills/access";
@@ -144,6 +145,7 @@ export async function searchAgentSkills(query, options, runtime = {}) {
     return {
         query: normalized,
         route: serializeCapabilityRoute(route, { visibleSkills: index.skill_names }),
+        ...(!route ? { hint: capabilityDiscoveryRecovery(normalized, "cli") } : {}),
         total_matches: matches.length,
         returned: Math.min(limit, matches.length),
         skills: matches.slice(0, limit).map(({ skill, score, matching_documents }) => ({

package/node_modules/@oxygen/shared/dist/capability-discovery.js

@@ -1018,6 +1018,18 @@ const CRM_ENRICHMENT_READ_VIEW = {
 };
 /** The card a route reports: Publishing's own, or its UGC view for a creator-program ask. */
 function routeCardFor(card, query) {
+    const placementGuide = card.id === "sending-infrastructure" ? placementGuideRecommendation(query) : null;
+    if (placementGuide)
+        card = { ...card, posture: "read_only", execution: placementGuide.execution };
+    const lookup = card.id === "tables" ? linkedinUrlFindingRecommendation(query) : null;
+    if (lookup)
+        card = { ...card, execution: lookup.execution };
+    const pageResearch = card.id === "sourcing-and-provider-tools" ? pageScrapingRecommendation(query) : null;
+    if (pageResearch)
+        card = { ...card, execution: pageResearch.execution };
+    const collaboration = card.id === "collaboration" ? collaborationRecommendation(query) : null;
+    if (collaboration)
+        card = { ...card, execution: collaboration.execution, posture: collaboration.posture };
     if (card.id === "records" && isCrmEnrichmentConfigurationRead(query))
         return { ...card, ...CRM_ENRICHMENT_READ_VIEW };
     const crmMaintenance = card.id === "records" ? crmMaintenanceRecommendation(query) : null;
@@ -1115,6 +1127,8 @@ function routeCardFor(card, query) {
 /** Search surfaces share the selected skill owner; a general router is fallback. */
 function preferredSkillForIntent(card, query) {
     if (card.id === "tables") {
+        if (linkedinUrlFindingRecommendation(query))
+            return "oxygen-enrichment";
         if (/\bclay\b/.test(query) && /\b(import|export|migrat\w*|mov\w*)\b/.test(query))
             return "oxygen-clay-migration";
         if (isTableMaintenanceIntent(query))
@@ -1926,6 +1940,8 @@ function explicitCapabilityIntent(query) {
     if (isWorkspacePagesIntent(query) || isWorkspaceSettingsIntent(query)) {
         return ROUTE_BY_ID.get("workspace-access") ?? null;
     }
+    if (collaborationRecommendation(query))
+        return ROUTE_BY_ID.get("collaboration") ?? null;
     if (/\btables?\b/.test(query) && isSecondPartyDecisionIntent(query))
         return ROUTE_BY_ID.get("collaboration") ?? null;
     if (tableReadRecommendation(query) || tableMaintenanceRecommendation(query))
@@ -2009,6 +2025,8 @@ function explicitCapabilityIntent(query) {
     }
     if (isHostedWorkflowIntent(query))
         return ROUTE_BY_PRIMITIVE.get("workflows") ?? null;
+    if (placementGuideRecommendation(query))
+        return ROUTE_BY_ID.get("sending-infrastructure") ?? null;
     if (isCompanySourcingIntent(query))
         return ROUTE_BY_ID.get("sourcing-and-provider-tools") ?? null;
     if (isOwnedPostCommentIntent(query))
@@ -2053,6 +2071,8 @@ function explicitCapabilityIntent(query) {
     // research input.
     if (isNetNewLinkedInInitiation(query))
         return ROUTE_BY_PRIMITIVE.get("sequences") ?? null;
+    if (linkedinUrlFindingRecommendation(query))
+        return ROUTE_BY_PRIMITIVE.get("tables") ?? null;
     if (isPublicLinkedInRead(query))
         return ROUTE_BY_ID.get("linkedin-public-research") ?? null;
     if (/\b(my|our|own)\b.{0,40}\blinkedin\b.{0,40}\b(post )?engagers?\b/.test(query)) {
@@ -2134,6 +2154,10 @@ function explicitCapabilityIntent(query) {
     // company_enrich preset instead.
     if (isCompanyUrlRecoveryIntent(query))
         return ROUTE_BY_ID.get("sourcing-and-provider-tools") ?? null;
+    if (pageScrapingRecommendation(query))
+        return ROUTE_BY_ID.get("sourcing-and-provider-tools") ?? null;
+    if (/\bagency partners?\b/.test(query))
+        return ROUTE_BY_ID.get("agency-directory") ?? null;
     // A category-plus-place ask ("dental practices in Austin", "local businesses",
     // "scrape Google Maps") is the companies-search `local` intent. A 2026-09-21
     // blind user typing "find local businesses like dental practices in a city"
@@ -2212,6 +2236,18 @@ function isPublishingPostIntent(query) {
         && !(/\b(find|search|scrape|research)\b/.test(query) && /\b(about|mention|containing)\b/.test(query));
 }
 function recommendationsFor(card, query) {
+    const placementGuide = card.id === "sending-infrastructure" ? placementGuideRecommendation(query) : null;
+    if (placementGuide)
+        return placementGuide;
+    const lookup = card.id === "tables" ? linkedinUrlFindingRecommendation(query) : null;
+    if (lookup)
+        return lookup;
+    const pageResearch = card.id === "sourcing-and-provider-tools" ? pageScrapingRecommendation(query) : null;
+    if (pageResearch)
+        return pageResearch;
+    const collaboration = card.id === "collaboration" ? collaborationRecommendation(query) : null;
+    if (collaboration)
+        return collaboration;
     if (card.id === "knowledge-graph" && isWorkspaceSkillIntent(query)) {
         return { tools: ["oxygen_workspace_skills_list", "oxygen_workspace_skills_create", "oxygen_workspace_skills_import", "oxygen_workspace_skills_get", "oxygen_workspace_skills_update", "oxygen_workspace_skills_archive"],
             commands: ["skills workspace list", "skills workspace create", "skills workspace import", "skills workspace get", "skills workspace update", "skills workspace archive"] };
@@ -2930,6 +2966,48 @@ function isRowClassificationIntent(query) {
 function isCompanyResearchQuestionIntent(query) {
     return /\b(founders?|founded by|parent compan(?:y|ies)|subsidiar(?:y|ies)|cloud provider|naics|column templates?|template catalog|ready[- ]made|research question|company research|offers? demos?|gives? demos?)\b/.test(query);
 }
+/** Supporting placement instructions belong to deliverability, even when the ask names an inbox. */
+function placementGuideRecommendation(query) {
+    if (!/\bplacement(?:[- ]tests?)?\b/.test(query)
+        || !/\b(guidance|guide|instructions|supporting|read|docs?|documentation)\b/.test(query)
+        || /\b(run|send|create|connect|enable)\b/.test(query))
+        return null;
+    return {
+        tools: ["oxygen_skills_get"],
+        commands: ["skills get"],
+        exactCommand: "oxygen skills get oxygen-deliverability --file references/placement.md --json",
+        exactMcpCall: { tool: "oxygen_skills_get", arguments: { name: "oxygen-deliverability", file: "references/placement.md" } },
+        execution: "Read oxygen-deliverability, references/placement.md for placement-test guidance and references/emailguard.md for inbox monitoring. Instruction reads do not run a test or enroll a mailbox. Keep the live preview, sender scope, credit ceiling and separate approvals for provider provisioning and test sends.",
+    };
+}
+/** OXP-43.72: pricing qualifies the lookup or scrape, rather than changing its owner. */
+function linkedinUrlFindingRecommendation(query) {
+    if (!/\blinkedin\b/.test(query) || !/\b(urls?|links?)\b/.test(query)
+        || !/\b(find|finding|lookup|look up|resolve|missing)\b/.test(query)
+        || /\b(scrape\w*|posts?|comments?|engagers?|followers?|connect|inbox|send\w*|publish\w*)\b/.test(query)
+        || /\bcompany pages?\b/.test(query))
+        return null;
+    return {
+        tools: ["oxygen_tools_search", "oxygen_columns_add", "oxygen_enrich_column_preview"],
+        commands: ["tools search", "columns add", "enrich-column preview"],
+        exactCommand: "oxygen tools search find_linkedin_url --json",
+        exactMcpCall: { tool: "oxygen_tools_search", arguments: { query: "find_linkedin_url" } },
+        execution: "Inspect the native LinkedIn URL waterfall and current pricing with tools search find_linkedin_url. Read oxygen-enrichment and its references/linkedin-url.md. Add the linkedin_url capability to existing rows, then preview the exact row scope for free before an approved run with a credit ceiling. Known-profile scraping is a separate operation.",
+    };
+}
+function pageScrapingRecommendation(query) {
+    if (!/\b(scrap(?:e|ing)|crawl\w*|fetch|extract)\b/.test(query)
+        || !/\b(pages?|websites?|web ?sites?|web content|urls?)\b/.test(query)
+        || /\b(linkedin|emails?|phones?|crm|records?)\b/.test(query))
+        return null;
+    return {
+        tools: ["oxygen_tools_search", "oxygen_tools_get"],
+        commands: ["tools search", "tools get"],
+        exactCommand: "oxygen tools search firecrawl --json",
+        exactMcpCall: { tool: "oxygen_tools_search", arguments: { query: "firecrawl" } },
+        execution: "Discover public-page operations with tools search firecrawl, then hydrate one exact tool and its pricing. Read oxygen-sourcing and provider-runbooks/firecrawl.md. Preview the selected URLs and price before execution; live scraping requires approval for the exact URL scope and credit ceiling. For durable per-row research, use native Tables research columns. Discovery does not run a scrape.",
+    };
+}
 function isCompanyUrlRecoveryIntent(query) {
     const urlNoun = /\b(websites?|web ?sites?|website urls?|domains?|urls?|homepages?)\b/;
     const companyNoun = /\b(compan(?:y|ies)|accounts?|organi[sz]ations?|brands?|vendors?)\b/;
@@ -3109,6 +3187,50 @@ function isNetNewLinkedInInitiation(query) {
         return false;
     return !/\b(sequence|campaign|cadence|enroll|nurture|multi[ -]step|multi[ -]recipient|leads|contacts|recipients|audience|rotate senders?|stop on reply|day\s*\d+)\b/.test(query);
 }
+/** Recommendations point to the mounted native owners, without conferring their write authority. */
+function collaborationRecommendation(query) {
+    const memberRead = { tools: ["oxygen_workspace_members_list"], commands: ["approvals client list"],
+        execution: "Read workspace member roles, Clerk profiles and pending invitations. This does not invite anyone or change access. Free.", posture: "read_only" };
+    const member = /\b(members?|memberships?)\b/.test(query);
+    const workspace = /\b(workspace|organization|org)\b/.test(query);
+    const clientRole = /\bclient (?:role|access|login)\b/.test(query);
+    const roleWrite = /\b(set|change|grant|clear|remove|revoke|restrict|promote|demote)\b/.test(query);
+    if (clientRole && roleWrite && !/\b(crm|records?|contacts?|companies|api|oauth)\b/.test(query)) {
+        const clear = /\b(clear|remove|revoke)\b/.test(query);
+        return { tools: ["oxygen_members_client_role_set", ...memberRead.tools], commands: [clear ? "approvals client revoke" : "approvals client grant", ...memberRead.commands],
+            execution: "An admin can set or clear the restricted client overlay; a pending invite is checked in Clerk. This sends no invitation and does not change the Clerk workspace role. Free.", posture: "workspace_write" };
+    }
+    if (workspace && member && roleWrite && /\b(roles?|admin|administrator)\b/.test(query))
+        return {
+            tools: ["oxygen_members_workspace_role_set", ...memberRead.tools], commands: ["orgs member-role", ...memberRead.commands],
+            execution: "An admin changes a member's workspace role in Clerk before Oxygen mirrors it. Self-role changes and the last administrator are protected; the client overlay is separate. Free.", posture: "workspace_write",
+        };
+    if (((workspace && member) || clientRole || /\bwho is in (?:my|our|this|the) workspace\b/.test(query))
+        && !/\b(invite|add|delete|cancel|enable|disable|set|change|grant|clear|remove|revoke|restrict|promote|demote)\b/.test(query))
+        return memberRead;
+    if (/\b(?:approval|launch|sign ?off) gates?\b/.test(query)) {
+        const write = /\b(arm|set|enable|disable|require|change|turn)\b/.test(query);
+        return { tools: write ? ["oxygen_approvals_gate_set", "oxygen_approval_gates_list"] : ["oxygen_approval_gates_list", "oxygen_approvals_gate_set"],
+            commands: write ? ["approvals gate set", "approvals gate list"] : ["approvals gate list", "approvals gate set"],
+            execution: write ? "An admin configures the approval gate; this grants no approval. Launch gates a sequence; signoff gates a table. The owning primitive enforces it. Free."
+                : "Read configured approval gates and effective state for an exact subject. Reading a gate grants no approval. Free.", posture: write ? "workspace_write" : "read_only" };
+    }
+    if (/\bcomments?\b/.test(query) && /\b(internal|workspace|teammate|client)\b/.test(query)
+        && !/\b(linkedin|public|published|posts?|publishing)\b/.test(query)) {
+        if (/\b(edit|update|correct)\b/.test(query))
+            return { tools: ["oxygen_comments_edit", "oxygen_comments_list"], commands: ["comments edit", "comments list"],
+                execution: "Edit your own internal workspace comment by comment id; the author check and edit time are enforced by its native owner. Free.", posture: "workspace_write" };
+        if (/\b(delete|retract|remove)\b/.test(query))
+            return { tools: ["oxygen_comments_delete", "oxygen_comments_list"], commands: ["comments delete", "comments list"],
+                execution: "Retract your own internal comment by comment id. Its audit placeholder remains; this does not delete a public post comment. Free.", posture: "workspace_write" };
+    }
+    if (/\b(cancel|withdraw|retract)\b/.test(query) && /\b(?:approval|sign ?off) requests?\b/.test(query))
+        return {
+            tools: ["oxygen_approvals_cancel", "oxygen_approvals_list"], commands: ["approvals cancel", "approvals list"],
+            execution: "Withdraw an approval request you created, by request id; this grants no approval. The requester check remains enforced by the native owner. Free.", posture: "workspace_write",
+        };
+    return null;
+}
 function isSecondPartyDecisionIntent(query) {
     const decisionLanguage = /\b(sign ?off|signoff|approval request|request approval|approval gate|go no go)\b/.test(query);
     const clientDecision = /\bclient\b.{0,20}\b(approv\w*|sign ?off|review|decide|decision|login|role)\b/.test(query)

package/node_modules/@oxygen/shared/dist/contracts/browser-operations.js

@@ -97,15 +97,25 @@ export const BROWSER_OPERATIONS = [
     operation("tables.resource.runs.cancel", `${run}/cancel`, "POST", "tables runs stop", "oxygen_table_resource_run_stop", "runs", "Cancel one durable Table run; never repeats external provider effects."),
     operation("tables.resource.runs.pause", `${run}/pause`, "POST", "tables runs pause", "oxygen_table_resource_run_pause", "runs", "Pause one durable Table run without discarding its approved scope."),
     operation("tables.resource.runs.resume", `${run}/resume`, "POST", "tables runs resume", "oxygen_table_resource_run_resume", "runs", "Resume a paused Table run within its existing approved scope and credit ceiling."),
-    operation("tables.resource.runs.retry", `${run}/retry-failed`, "POST", "tables runs retry", "oxygen_table_resource_run_retry", "runs", "Retry failed cells within a Table run's approved scope. Uncertain external effects require approved_effect_unknown=true.", { approved_effect_unknown: bool() }, [], { spends: true }),
+    operation("tables.resource.runs.retry", `${run}/retry-failed`, "POST", "tables runs retry", "oxygen_table_resource_run_retry", "runs", "Retry failed cells; a fresh allowance requires approved, retry_plan_hash and max_additional_credits. Uncertain effects require separate approval.", { approved_effect_unknown: bool(), approved: bool(), retry_plan_hash: text(), max_additional_credits: num({ minimum: 0 }) }, [], { spends: true }),
     operation("tables.resource.runs.provider_summary", `${run}/provider-summary`, "GET", "tables runs provider-summary", "oxygen_table_resource_run_provider_summary", "runs", "Read a Table run's provider outcomes, fulfilled rows, costs and timing."),
     operation("tables.resource.ingestions.cancel", `${table}/ingestions/{ingestion_run}/cancel`, "POST", "tables ingestion stop", "oxygen_table_resource_ingestion_stop", "runs", "Cancel this Table's active hosted ingestion run."),
     operation("tables.resource.ingestions.retry", `${table}/ingestions/{ingestion_run}/retry-failed`, "POST", "tables ingestion retry", "oxygen_table_resource_ingestion_retry", "runs", "Retry failed items in this Table's hosted ingestion run."),
     operation("tables.resource.import", "/api/cli/tables/import", "POST", "tables upload", "oxygen_table_resource_upload", "tables", "Preview or import small uploaded CSV, JSON or XLSX bytes through the exact browser import contract. Preview writes no rows.", upload, ["content_base64", "file_name"], { multipart }),
     operation("billing.activate", "/api/cli/billing/activate", "POST", "billing activate", "oxygen_billing_activate", "billing", "Activate a trial subscription now and charge its saved payment method; administrator approval is required. An optional tier reprices the active trial in the same call.", { approved: bool(), tier: text() }, ["approved"], { spends: true }),
-    operation("billing.checkout", "/api/cli/billing/checkout", "POST", "billing checkout", "oxygen_billing_checkout", "billing", "Open the same hosted plan checkout as the browser; the returned URL carries the payment approval step.", { plan: text(), interval: enumOf(["month", "year"]), term: enumOf(["month", "year"]), terms_version: text(), currency: text(), trial: bool(), return_to: text(), source: text(), blocked: text() }, ["plan"]),
-    operation("billing.confirm", "/api/cli/billing/confirm", "POST", "billing confirm", "oxygen_billing_confirm", "billing", "Confirm an exact unexpired plan-change preview. approved accepts its payment, term and effective date; workspace administrator required.", { token: text(), approved: bool() }, ["token", "approved"], { spends: true }),
-    operation("billing.portal", "/api/cli/billing/portal", "POST", "billing portal", "oxygen_billing_portal", "billing", "Create the workspace's authenticated Stripe billing-portal URL; requires workspace administrator authorization.", { returnUrl: text() }),
+    operation("billing.checkout", "/api/cli/billing/checkout", "POST", "billing checkout", "oxygen_billing_checkout", "billing", "Open browser Checkout; payment approves purchase. First purchase: admin/owner. New yearly plans use interval month, term year and the current terms_version.", {
+        plan: text("Plan key from billing balance available_plans, for example oxygen_49."),
+        interval: enumOf(["month", "year"], { description: "New purchases use month. year is legacy prepaid cadence, refused for new purchases." }),
+        term: enumOf(["month", "year"], { description: "year commits to twelve discounted monthly payments; month is the default." }),
+        terms_version: text("Required for term year: annual_monthly_terms.terms_version from billing balance."),
+        currency: text("Billing currency: usd (default)."),
+        trial: bool({ description: "Retired compatibility option; omit for a new paid subscription." }),
+        return_to: text("Same-origin path to return to after Checkout, for example /home."),
+        source: text("Optional upgrade-entry attribution; omit if unknown."),
+        blocked: text("Optional capability that led to the upgrade; omit if unknown."),
+    }, ["plan"]),
+    operation("billing.confirm", "/api/cli/billing/confirm", "POST", "billing confirm", "oxygen_billing_confirm", "billing", "Confirm a plan-change preview within 15 minutes; approved accepts payment, term and effective date. Unrestricted members allowed; restricted clients denied.", { token: text(), approved: bool() }, ["token", "approved"], { spends: true }),
+    operation("billing.portal", "/api/cli/billing/portal", "POST", "billing portal", "oxygen_billing_portal", "billing", "Create a Stripe billing-portal URL. Unrestricted members allowed; restricted clients denied.", { returnUrl: text() }),
     operation("billing.ownership.get", "/api/cli/billing/ownership", "GET", "billing ownership get", "oxygen_billing_ownership_get", "billing", "Read the active workspace's shared billing owner, candidate owners and credit cap."),
     operation("billing.ownership.set", "/api/cli/billing/ownership", "POST", "billing ownership set", "oxygen_billing_ownership_set", "billing", "Set the billing owner and optional monthly credit cap using the browser's administrator and workspace eligibility checks.", { billing_owner_organization_id: text(), monthly_credit_cap: nullable(num({ minimum: 0 })) }, ["billing_owner_organization_id"]),
     operation("billing.ownership.clear", "/api/cli/billing/ownership", "DELETE", "billing ownership clear", "oxygen_billing_ownership_clear", "billing", "Restore this workspace's own billing ownership after the same administrator checks as the browser."),

package/node_modules/@oxygen/shared/dist/contracts/customer-operations.js

@@ -8,6 +8,7 @@ import { COPILOT_SESSIONS_LIST_CONTRACT } from "./copilot-sessions.js";
 import { CRM_FILE_ATTACH_CONTRACT, CRM_FILE_ATTACH_DESCRIPTION } from "./crm-support.js";
 import { spintaxContract } from "./spintax.js";
 import { betaFeaturesUpdateContract, emailDomainSuppressionListContract, emailDomainSuppressionRemoveContract, emailSuppressionRemoveContract, providerLimitListContract, providerLimitSelectorContract, providerLimitUpdateContract } from "./workspace-utilities.js";
+import { knowledgeSyncReadContract } from "./knowledge-sync.js";
 const text = (description) => str(description === undefined ? {} : { description });
 const list = () => arr(str());
 const json = { type: "object", additionalProperties: true };
@@ -34,8 +35,8 @@ export const CUSTOMER_OPERATIONS = [
     operation("comments.edit", "/api/cli/collab/comments/{comment_id}", "PATCH", "comments edit", "oxygen_comments_edit", "collaboration", "Edit your own internal workspace comment; records the edit time.", { body: text() }, ["body"], mcpOnly),
     operation("comments.delete", "/api/cli/collab/comments/{comment_id}", "DELETE", "comments delete", "oxygen_comments_delete", "collaboration", "Retract your own internal workspace comment while retaining its audit trail.", {}, [], mcpOnly),
     operation("approvals.cancel", "/api/cli/collab/requests/{request_id}/cancel", "POST", "approvals cancel", "oxygen_approvals_cancel", "collaboration", "Withdraw an approval request you created; grants no approval.", { note: text() }, [], mcpOnly),
-    operation("members.client_role", "/api/cli/collab/members/role", "POST", "approvals client grant", "oxygen_members_client_role_set", "collaboration", "Set or clear a member's restricted client role; workspace admin only.", { email: text(), role: nullable(enumOf(["client"])) }, ["email", "role"], mcpOnly),
-    operation("members.workspace_role", "/api/cli/collab/members/workspace-role", "POST", "orgs member-role", "oxygen_members_workspace_role_set", "collaboration", "Change a member's workspace role; admin only and the last administrator is protected.", { email: text(), role: enumOf(["admin", "member"]) }, ["email", "role"], mcpOnly),
+    operation("members.client_role", "/api/cli/collab/members/role", "POST", "approvals client grant", "oxygen_members_client_role_set", "collaboration", "Set or clear the restricted client overlay; admin only. May read pending Clerk invitations; sends no invitation. Free.", { email: text(), role: nullable(enumOf(["client"])) }, ["email", "role"], { ...mcpOnly, annotations: { openWorldHint: true } }),
+    operation("members.workspace_role", "/api/cli/collab/members/workspace-role", "POST", "orgs member-role", "oxygen_members_workspace_role_set", "collaboration", "Change a member's workspace role in Clerk; admin only, with self-role and last-administrator protection. Free.", { email: text(), role: enumOf(["admin", "member"]) }, ["email", "role"], { ...mcpOnly, annotations: { openWorldHint: true } }),
     operation("copilot.sessions.list", "/api/cli/copilot/sessions", "GET", "copilot list", "oxygen_copilot_sessions_list", "agents", "List attended Copilot sessions in this workspace.", COPILOT_SESSIONS_LIST_CONTRACT.properties, [], mcpOnly),
     operation("copilot.sessions.update", "/api/cli/copilot/sessions/{session_id}", "PATCH", "copilot policy set", "oxygen_copilot_session_update", "agents", "Set an attended Copilot session's approval and screen-follow policies. Paid auto-approval is explicit standing authorization.", { auto_approve_policy: enumOf(["off", "paid"]), surface_policy: enumOf(["off", "follow"]) }, [], { spends: true }),
     operation("copilot.attachments.list", "/api/cli/copilot/sessions/{session_id}/attachments", "GET", "copilot attachments list", "oxygen_copilot_attachments_list", "agents", "List sent and unsent attachments in one Copilot session.", {}, []),
@@ -64,8 +65,8 @@ export const CUSTOMER_OPERATIONS = [
     operation("directory.logo", "/api/cli/directory/listing/logo", "POST", "directory logo upload", "oxygen_directory_logo_upload", "crm", "Upload a public agency-directory logo and read back the updated listing; PNG, JPEG, WebP or SVG, at most 2 MB.", { content_base64: text(), file_name: text(), content_type: enumOf(["image/png", "image/jpeg", "image/webp", "image/svg+xml"]) }, ["content_base64", "file_name", "content_type"], { multipart: { contentField: "content_base64", nameField: "file_name", typeField: "content_type", fileField: "file" } }),
     operation("domains.delete", "/api/cli/domains/delete", "POST", "domains delete", "oxygen_domains_delete", "deliverability", "Preview domain removal and renewal cancellation; execute only with the exact plan hash and confirmation.", { domains: list(), approved: bool(), plan_hash: text(), confirmation: text() }, ["domains"], mcpOnly),
     operation("knowledge.pages.archive", "/api/cli/knowledge/pages/archive", "POST", "knowledge page archive", "oxygen_knowledge_page_archive", "knowledge", "Archive a knowledge page; content/history remain, links become unresolved. Pass expected_revision for the version you reviewed.", { slug: text(), id: text(), expected_revision: int({ minimum: 1 }) }, [], mcpOnly),
-    operation("knowledge.sync.manifest", "/api/cli/knowledge/sync/manifest", "POST", "knowledge sync-manifest", "oxygen_knowledge_sync_manifest", "knowledge", "Read the wiki revision and content-hash inventory without downloading instruction bodies.", {}, [], { mutates: false }),
-    operation("knowledge.sync.delta", "/api/cli/knowledge/sync/delta", "POST", "knowledge sync", "oxygen_knowledge_sync_delta", "knowledge", "Read one resumable batch of wiki pages and tombstones, bounded by the server's byte budget.", { cursor: text(), limit: int({ minimum: 1, maximum: 200 }) }, [], { ...mcpOnly, mutates: false }),
+    operation("knowledge.sync.manifest", "/api/cli/knowledge/sync/manifest", "POST", "knowledge sync-manifest", "oxygen_knowledge_sync_manifest", "knowledge", "Read wiki revision/hash metadata. Follow next_cursor for remaining pages; scope is a live keyset, not a snapshot.", {}, [], { contract: knowledgeSyncReadContract, mutates: false }),
+    operation("knowledge.sync.delta", "/api/cli/knowledge/sync/delta", "POST", "knowledge sync-delta", "oxygen_knowledge_sync_delta", "knowledge", "Read complete wiki pages/tombstones. First call seeds missing starter pages. Follow next_cursor; an oversized page is refused without skipping. 0 credits.", {}, [], { contract: knowledgeSyncReadContract }),
     operation("limits.provider.get", "/api/cli/limits/provider", "GET", "limits provider list", "oxygen_provider_limits_list", "billing", "Read provider request limits and BYOK warning defaults. MCP defaults to bounded summary pages; follow paging.next_offset with the same filter. HTTP/CLI omit pagination for the full legacy list. 0 credits.", {}, [], { contract: providerLimitListContract, generated: { cli: false, mcp: false } }),
     operation("limits.provider.set", "/api/cli/limits/provider", "POST", "limits provider set", "oxygen_provider_limits_set", "billing", "Set an enforced provider request limit; admin or owner only. Approve the exact provider, operation and window: raising a cap may permit more provider use. 0 credits.", {}, [], { ...mcpOnly, contract: providerLimitUpdateContract }),
     operation("limits.provider.delete", "/api/cli/limits/provider", "DELETE", "limits provider delete", "oxygen_provider_limits_delete", "billing", "Clear one provider request-limit override; admin or owner only. Approve the exact selector. Other operation overrides remain; the provider returns to its defaults, whose BYOK threshold may be observe-only. 0 credits.", {}, [], { ...mcpOnly, contract: providerLimitSelectorContract, queryFields: ["provider", "operation"] }),
@@ -107,7 +108,7 @@ export const CUSTOMER_OPERATIONS = [
     operation("billing.invoices", "/api/cli/billing/invoices", "GET", "billing invoices", "oxygen_billing_invoices", "billing", "Read this workspace's billing invoices and their hosted payment links.", {}, [], mcpOnly),
     operation("billing.seats.set", "/api/cli/billing/seats", "POST", "billing seats set", "oxygen_billing_seats_set", "billing", "Set purchased legacy sending-seat quantity. Retired seats cannot increase; reducing existing seats lowers the next renewal charge.", { seat_key: enumOf(["linkedin", "whatsapp", "phone_number", "email_sender"]), quantity: int({ minimum: 0 }) }, ["seat_key", "quantity"], mcpOnly),
     operation("collaboration.gates.list", "/api/cli/collab/gates", "GET", "approvals gate list", "oxygen_approval_gates_list", "collaboration", "Read this workspace's approval gates, optionally for one exact subject.", { subject: text() }, [], mcpOnly),
-    operation("collaboration.members.list", "/api/cli/collab/members", "GET", "approvals client list", "oxygen_workspace_members_list", "collaboration", "Read workspace members and their collaboration roles.", {}, [], mcpOnly),
+    operation("collaboration.members.list", "/api/cli/collab/members", "GET", "approvals client list", "oxygen_workspace_members_list", "collaboration", "Read workspace member roles, with Clerk profiles and pending invitations. Free.", {}, [], { ...mcpOnly, annotations: { openWorldHint: true } }),
     operation("crm.connections", "/api/cli/crm/objects/{object}/records/{row_id}/connections", "GET", "crm connections", "oxygen_crm_connections", "crm", "Read a CRM record's connected conversations, sequence enrollments and related activity.", { conversation_limit: int({ minimum: 1 }), sequence_limit: int({ minimum: 1 }) }, [], mcpOnly),
     operation("crm.tasks.list", "/api/cli/crm/tasks", "GET", "crm tasks list", "oxygen_crm_tasks_queue", "crm", "Read the workspace task queue by status, assignee and cursor.", { status: text(), assignee: text(), cursor: text(), limit: int({ minimum: 1 }) }, [], mcpOnly),
     operation("crm.files.download", "/api/cli/crm/files/{attachment_id}/download", "GET", "crm files download", "oxygen_crm_file_download", "crm", "Download a tenant-owned record attachment by attachment_id. The native authenticated response contains its exact bytes.", {}, [], { binary: { maxBytes: 50 * 1024 * 1024 } }),

package/node_modules/@oxygen/shared/dist/contracts/knowledge-sync.d.ts

@@ -0,0 +1,19 @@
+/** Both sync readers expose complete native pages; no formatter may trim a
+ * page after its continuation position has been issued. */
+export declare const knowledgeSyncReadContract: import("./schema.js").ContractObject<{
+    readonly cursor: import("./schema.js").StringProperty;
+    readonly limit: {
+        type: "integer";
+        description?: string;
+        minimum?: number;
+        maximum?: number;
+        "x-clamp"?: true;
+    };
+    readonly max_chars: {
+        type: "integer";
+        description?: string;
+        minimum?: number;
+        maximum?: number;
+        "x-clamp"?: true;
+    };
+}, never>;

package/node_modules/@oxygen/shared/dist/contracts/knowledge-sync.js

@@ -0,0 +1,8 @@
+import { int, obj, str } from "./schema.js";
+/** Both sync readers expose complete native pages; no formatter may trim a
+ * page after its continuation position has been issued. */
+export const knowledgeSyncReadContract = obj({
+    cursor: str({ minLength: 1, maxLength: 256 }),
+    limit: int({ minimum: 1, maximum: 200 }),
+    max_chars: int({ minimum: 1000, maximum: 48000, description: "Complete receipt window; surface cap applies." }),
+});

package/node_modules/@oxygen/shared/dist/contracts/publishing-reads.d.ts

@@ -20,6 +20,7 @@ export declare const publishingReadProjectionContract: ContractObject<{
         readonly description?: string;
         readonly minLength?: number;
         readonly maxLength?: number;
+        readonly pattern?: string;
         readonly enum: readonly ["full", "summary", "value"];
     };
     readonly value_path: import("./schema.js").StringProperty;
@@ -40,6 +41,7 @@ export declare const publishingAmplificationListQueryContract: ContractObject<{
         readonly description?: string;
         readonly minLength?: number;
         readonly maxLength?: number;
+        readonly pattern?: string;
         readonly enum: readonly ["full", "summary", "value"];
     };
     readonly value_path: import("./schema.js").StringProperty;
@@ -57,6 +59,7 @@ export declare const publishingAmplificationListQueryContract: ContractObject<{
         readonly description?: string;
         readonly minLength?: number;
         readonly maxLength?: number;
+        readonly pattern?: string;
         readonly enum: readonly ["all", "tag", "post", "ugc_program", "ugc_peer_program"];
     };
     readonly limit: {
@@ -73,6 +76,7 @@ export declare const publishingAmplificationActionsQueryContract: ContractObject
         readonly description?: string;
         readonly minLength?: number;
         readonly maxLength?: number;
+        readonly pattern?: string;
         readonly enum: readonly ["full", "summary", "value"];
     };
     readonly value_path: import("./schema.js").StringProperty;
@@ -99,6 +103,7 @@ export declare const publishingNotesQueryContract: ContractObject<{
         readonly description?: string;
         readonly minLength?: number;
         readonly maxLength?: number;
+        readonly pattern?: string;
         readonly enum: readonly ["full", "summary", "value"];
     };
     readonly value_path: import("./schema.js").StringProperty;
@@ -127,6 +132,7 @@ export declare const publishingRevisionsQueryContract: ContractObject<{
         readonly description?: string;
         readonly minLength?: number;
         readonly maxLength?: number;
+        readonly pattern?: string;
         readonly enum: readonly ["full", "summary", "value"];
     };
     readonly value_path: import("./schema.js").StringProperty;
@@ -166,6 +172,7 @@ export declare const publishingAnalyticsQueryContract: ContractObject<{
         readonly description?: string;
         readonly minLength?: number;
         readonly maxLength?: number;
+        readonly pattern?: string;
         readonly enum: readonly ["full", "summary", "value"];
     };
     readonly value_path: import("./schema.js").StringProperty;

package/node_modules/@oxygen/shared/dist/contracts/schema.d.ts

@@ -15,6 +15,8 @@ export type StringProperty = {
     enum?: readonly string[];
     minLength?: number;
     maxLength?: number;
+    /** JSON Schema regular expression, evaluated with Unicode semantics. */
+    pattern?: string;
 };
 export type NumberProperty = {
     type: "number" | "integer";
@@ -99,6 +101,7 @@ export declare function jsonValue(options?: Described): {
 export declare function str(options?: Described & {
     minLength?: number;
     maxLength?: number;
+    pattern?: string;
 }): StringProperty;
 export declare function enumOf<const V extends string>(values: readonly V[], options?: Described): {
     type: "string";

package/node_modules/@oxygen/shared/dist/contracts/schema.js

@@ -210,6 +210,9 @@ function walkValue(schema, value, path, walk) {
             else if (schema.maxLength !== undefined && value.length > schema.maxLength) {
                 walk.issues.push({ path, message: `${path} must be at most ${schema.maxLength} characters.` });
             }
+            else if (schema.pattern !== undefined && !new RegExp(schema.pattern, "u").test(value)) {
+                walk.issues.push({ path, message: `${path} must match the required pattern.` });
+            }
             return value;
         }
         case "integer":

package/node_modules/@oxygen/shared/dist/contracts/table-feed-read.d.ts

@@ -55,6 +55,7 @@ export declare function tableFeedWindowProperties(contract: typeof TABLE_FEED_GE
         enum?: readonly string[];
         minLength?: number;
         maxLength?: number;
+        pattern?: string;
     } | {
         type: "integer";
         minimum?: number;

package/node_modules/@oxygen/shared/dist/contracts/table-row-read.d.ts

@@ -11,6 +11,7 @@ export declare const TABLE_ROW_READ_WINDOW_FIELDS: {
         readonly enum?: readonly string[];
         readonly minLength?: number;
         readonly maxLength?: number;
+        readonly pattern?: string;
         readonly description: "JSON Pointer; empty=root.";
     };
     readonly value_cursor: {
@@ -18,6 +19,7 @@ export declare const TABLE_ROW_READ_WINDOW_FIELDS: {
         readonly enum?: readonly string[];
         readonly minLength?: number;
         readonly maxLength?: number;
+        readonly pattern?: string;
         readonly description: "Resume with identical selection/path.";
     };
     readonly max_chars: {

package/node_modules/@oxygen/shared/dist/mcp-event-contract.d.ts

@@ -94,6 +94,7 @@ declare const REPLY_CLASSIFIED_PAYLOAD: ContractObject<{
         enum?: readonly string[];
         minLength?: number;
         maxLength?: number;
+        pattern?: string;
         format: "date-time";
     };
     readonly url: {
@@ -102,6 +103,7 @@ declare const REPLY_CLASSIFIED_PAYLOAD: ContractObject<{
         enum?: readonly string[];
         minLength?: number;
         maxLength?: number;
+        pattern?: string;
         format: "uri";
     };
 }, "channel" | "classification" | "conversation_id" | "enrollment_id" | "occurred_at" | "record_id" | "sequence_id" | "url">;
@@ -143,6 +145,7 @@ declare const ENROLLMENT_ENDED_PAYLOAD: ContractObject<{
         enum?: readonly string[];
         minLength?: number;
         maxLength?: number;
+        pattern?: string;
         format: "date-time";
     };
     readonly url: {
@@ -151,6 +154,7 @@ declare const ENROLLMENT_ENDED_PAYLOAD: ContractObject<{
         enum?: readonly string[];
         minLength?: number;
         maxLength?: number;
+        pattern?: string;
         format: "uri";
     };
 }, "enrollment_id" | "occurred_at" | "outcome" | "sequence_id" | "steps_sent" | "url">;
@@ -205,6 +209,7 @@ declare const MEETING_COMPLETED_PAYLOAD: ContractObject<{
         enum?: readonly string[];
         minLength?: number;
         maxLength?: number;
+        pattern?: string;
         format: "date-time";
     };
     readonly url: {
@@ -213,6 +218,7 @@ declare const MEETING_COMPLETED_PAYLOAD: ContractObject<{
         enum?: readonly string[];
         minLength?: number;
         maxLength?: number;
+        pattern?: string;
         format: "uri";
     };
 }, "activity_id" | "duration_seconds" | "occurred_at" | "record_ids" | "session_id" | "url">;
@@ -277,6 +283,7 @@ declare const RECORD_STAGE_CHANGED_PAYLOAD: ContractObject<{
         enum?: readonly string[];
         minLength?: number;
         maxLength?: number;
+        pattern?: string;
         format: "date-time";
     };
     readonly url: {
@@ -285,6 +292,7 @@ declare const RECORD_STAGE_CHANGED_PAYLOAD: ContractObject<{
         enum?: readonly string[];
         minLength?: number;
         maxLength?: number;
+        pattern?: string;
         format: "uri";
     };
 }, "activity_id" | "from_stage_id" | "object" | "occurred_at" | "pipeline_id" | "record_id" | "to_stage_id" | "url">;
@@ -323,6 +331,7 @@ declare const RUN_SETTLED_PAYLOAD: ContractObject<{
         enum?: readonly string[];
         minLength?: number;
         maxLength?: number;
+        pattern?: string;
         format: "date-time";
     };
     readonly url: {
@@ -331,6 +340,7 @@ declare const RUN_SETTLED_PAYLOAD: ContractObject<{
         enum?: readonly string[];
         minLength?: number;
         maxLength?: number;
+        pattern?: string;
         format: "uri";
     };
 }, "credits_used" | "kind" | "occurred_at" | "run_id" | "status" | "url">;
@@ -362,6 +372,7 @@ declare const APPROVAL_REQUESTED_PAYLOAD: ContractObject<{
         enum?: readonly string[];
         minLength?: number;
         maxLength?: number;
+        pattern?: string;
         format: "date-time";
     };
     readonly url: {
@@ -370,6 +381,7 @@ declare const APPROVAL_REQUESTED_PAYLOAD: ContractObject<{
         enum?: readonly string[];
         minLength?: number;
         maxLength?: number;
+        pattern?: string;
         format: "uri";
     };
 }, "approval_id" | "kind" | "occurred_at" | "run_id" | "url">;

package/node_modules/@oxygen/shared/dist/otlp-log-sink.d.ts

@@ -60,7 +60,7 @@ export type OtlpLogSinkOptions = {
  * `worker.log_shipper.stats` is the Axiom shipper's once-a-minute loss accounting,
  * which by design never reaches Axiom (OXP-1.6.126).
  */
-export declare const OTLP_MONITOR_INFO_EVENTS: readonly ["diagnostics.capture_stored", "diagnostics.invocation_completed", "diagnostics.canary_completed", "diagnostics.digest_completed", "tenant.migrations.cron.done", "outbound_send.sent", "worker_workflow_cron_overlap_skipped", "worker_workflow_cron_enqueued", "copilot.turn.finished", "worker.queue.heartbeat", "worker.queue.ledger", "worker.queue.redis", "worker.queue.unregistered_kind", "automation_usage.reconcile_completed", "provider_health.cron_completed", "provider_balances.cron_completed", "cost_snapshot.cron_completed", "worker.egress_order_reconcile_sweep", "posthog_canary.round_trip_ok", "web.log_volume", "worker.log_shipper.stats"];
+export declare const OTLP_MONITOR_INFO_EVENTS: readonly ["diagnostics.capture_stored", "diagnostics.invocation_completed", "diagnostics.canary_completed", "diagnostics.digest_completed", "tenant.migrations.cron.done", "outbound_send.sent", "worker_workflow_cron_overlap_skipped", "worker_workflow_cron_enqueued", "copilot.turn.finished", "worker.queue.heartbeat", "worker.queue.depth", "worker.queue.ledger", "worker.queue.redis", "worker.queue.unregistered_kind", "automation_usage.reconcile_completed", "provider_health.cron_completed", "provider_balances.cron_completed", "cost_snapshot.cron_completed", "worker.egress_order_reconcile_sweep", "posthog_canary.round_trip_ok", "web.log_volume", "worker.log_shipper.stats"];
 export type OtlpLogSinkHandle = {
     sink: LogSink;
     flush: () => Promise<void>;

package/node_modules/@oxygen/shared/dist/otlp-log-sink.js

@@ -22,6 +22,7 @@ export const OTLP_MONITOR_INFO_EVENTS = [
     "worker_workflow_cron_enqueued",
     "copilot.turn.finished",
     "worker.queue.heartbeat",
+    "worker.queue.depth",
     "worker.queue.ledger",
     "worker.queue.redis",
     "worker.queue.unregistered_kind",

package/node_modules/@oxygen/shared/dist/sending-schedule.d.ts

@@ -15,6 +15,13 @@ export type SendingSchedule = {
     start: string;
     end: string;
 };
+export type LinkedInSequenceSchedules = {
+    schedule?: SendingSchedule | null;
+    linkedin_invite_schedule?: SendingSchedule | null;
+    linkedin_message_schedule?: SendingSchedule | null;
+};
+/** Action windows replace the general sequence window; account hours still narrow them. */
+export declare function sequenceSocialSchedule(settings: LinkedInSequenceSchedules, actionKind: string, network?: string): SendingSchedule | null | undefined;
 /**
  * The settings fragment that applies one schedule to every channel. The email
  * window keeps its recipient-timezone fields; the social window takes the same

package/node_modules/@oxygen/shared/dist/sending-schedule.js

@@ -1,3 +1,13 @@
+/** Action windows replace the general sequence window; account hours still narrow them. */
+export function sequenceSocialSchedule(settings, actionKind, network = "linkedin") {
+    if (network === "linkedin") {
+        if (actionKind === "invite")
+            return settings.linkedin_invite_schedule ?? settings.schedule;
+        if (actionKind === "message" || actionKind === "inmail")
+            return settings.linkedin_message_schedule ?? settings.schedule;
+    }
+    return settings.schedule;
+}
 /**
  * The settings fragment that applies one schedule to every channel. The email
  * window keeps its recipient-timezone fields; the social window takes the same

package/node_modules/@oxygen/shared/dist/user-capability-routing.d.ts

@@ -1,2 +1,4 @@
 import { type CapabilityRouteMatch } from "./capability-discovery.js";
+/** A null route has no command to hydrate yet. Keep recovery bounded and executable. */
+export declare function capabilityDiscoveryRecovery(query: string, surface: "cli" | "mcp"): string;
 export declare function inferUserCapabilityRoute(query: string): CapabilityRouteMatch | null;

package/node_modules/@oxygen/shared/dist/user-capability-routing.js

@@ -1,4 +1,12 @@
 import { getCapabilityRoute, getCapabilityRouteMatch, inferCapabilityRoute, } from "./capability-discovery.js";
+/** A null route has no command to hydrate yet. Keep recovery bounded and executable. */
+export function capabilityDiscoveryRecovery(query, surface) {
+    if (surface === "mcp") {
+        return 'No capability owner matched. Inspect the returned tools, or load oxygen_capabilities_schema({"names":["oxygen_tools_search"]}) and search the provider catalog with specific keywords. Discovery does not execute a provider operation.';
+    }
+    const quoted = `'${query.replace(/'/g, "'\\''")}'`;
+    return `No capability owner matched. Run \`oxygen commands search ${quoted} --limit 5 --json\`, then hydrate a returned name with \`oxygen commands get '<returned-name>' --json\`.`;
+}
 // Provider brands are intentionally not duplicated into the static capability
 // catalog. A short "connect <provider>" query would otherwise match Tables via
 // its relationship-oriented "connect" term. Correct that narrow ambiguity at

package/node_modules/@oxygen/shared/dist/version.generated.d.ts

@@ -1 +1 @@
-export declare const OXYGEN_BUILD_VERSION = "1.1014.86";
+export declare const OXYGEN_BUILD_VERSION = "1.1014.118";

package/node_modules/@oxygen/shared/dist/version.generated.js

@@ -1,2 +1,2 @@
 // GENERATED by scripts/ci/version-stamp.mjs from VERSION + git history. Do not edit; do not commit.
-export const OXYGEN_BUILD_VERSION = "1.1014.86";
+export const OXYGEN_BUILD_VERSION = "1.1014.118";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxygen-agent/cli",
-  "version": "1.1014.86",
+  "version": "1.1014.118",
   "private": false,
   "license": "UNLICENSED",
   "type": "module",