@oxygen-agent/cli 1.275.2 → 1.284.3

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.275.2
+Version: 1.284.3

package/dist/command-manifest.d.ts

@@ -0,0 +1,30 @@
+import type { Command } from "commander";
+export type CommandManifestFlag = {
+    flags: string;
+    description: string;
+    required: boolean;
+};
+export type CommandManifestArgument = {
+    name: string;
+    required: boolean;
+    description: string;
+};
+export type CommandManifestEntry = {
+    name: string;
+    group: string;
+    description: string;
+    arguments: CommandManifestArgument[];
+    flags: CommandManifestFlag[];
+    spends_credits: boolean;
+    mutates: boolean;
+    json_supported: boolean;
+    hidden: boolean;
+};
+export type CommandManifest = {
+    binary: string;
+    version: string;
+    total: number;
+    exit_codes: Record<string, string>;
+    commands: CommandManifestEntry[];
+};
+export declare function buildCommandManifest(program: Command, binaryName: string): CommandManifest;

package/dist/command-manifest.js

@@ -0,0 +1,70 @@
+import { CLI_EXIT_CODE_TABLE, OXYGEN_VERSION } from "@oxygen/shared";
+const MUTATING_VERBS = new Set([
+    "add", "apply", "approve", "archive", "assign", "buy", "cancel", "clear",
+    "configure", "connect", "create", "delete", "disable", "dispatch", "draft",
+    "emit", "enable", "enroll", "grant", "import", "insert", "invite", "launch",
+    "login", "logout", "materialize", "merge", "migrate", "order", "pause",
+    "publish", "purchase", "push", "record", "register", "remove", "rename",
+    "reorder", "reply", "rerun", "reset", "resolve", "restore", "resume",
+    "retry", "retype", "revoke", "rotate", "run", "save", "schedule", "select",
+    "send", "set", "share", "start", "stop", "subscribe", "sync", "unpublish",
+    "unshare", "unsubscribe", "update", "upload", "upsert", "use", "withdraw",
+    "write",
+]);
+export function buildCommandManifest(program, binaryName) {
+    const commands = [];
+    for (const child of program.commands) {
+        collectCommand(child, [], commands);
+    }
+    commands.sort((a, b) => a.name.localeCompare(b.name));
+    return {
+        binary: binaryName,
+        version: OXYGEN_VERSION,
+        total: commands.length,
+        exit_codes: Object.fromEntries(Object.entries(CLI_EXIT_CODE_TABLE).map(([code, meaning]) => [code, meaning])),
+        commands,
+    };
+}
+function collectCommand(command, ancestors, out) {
+    const path = [...ancestors, command.name()];
+    const children = command.commands;
+    // Group commands (e.g. `oxygen tables`) exist to hold subcommands; only leaf
+    // commands are invocable work, so only leaves become manifest entries.
+    if (children.length === 0) {
+        out.push(toManifestEntry(command, path));
+        return;
+    }
+    for (const child of children) {
+        collectCommand(child, path, out);
+    }
+}
+function toManifestEntry(command, path) {
+    const options = command.options.filter((option) => !option.hidden);
+    const flagStrings = options.map((option) => option.flags);
+    const leafVerb = path[path.length - 1] ?? "";
+    const verbPrefix = leafVerb.split("-")[0] ?? leafVerb;
+    return {
+        name: path.join(" "),
+        group: path[0] ?? "",
+        description: command.description(),
+        arguments: command.registeredArguments.map((argument) => ({
+            name: argument.name(),
+            required: argument.required,
+            description: argument.description,
+        })),
+        flags: options.map((option) => ({
+            flags: option.flags,
+            description: option.description,
+            required: option.mandatory,
+        })),
+        spends_credits: flagStrings.some((flags) => flags.includes("--approved") || flags.includes("--max-credits")),
+        mutates: MUTATING_VERBS.has(leafVerb) || MUTATING_VERBS.has(verbPrefix),
+        json_supported: flagStrings.some((flags) => flags.includes("--json")),
+        hidden: isHiddenCommand(command),
+    };
+}
+function isHiddenCommand(command) {
+    // Commander keeps hidden state private; read it defensively so a library
+    // bump degrades to hidden:false instead of a crash.
+    return Boolean(command._hidden);
+}

package/dist/help.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function applyOxygenHelp(program: Command, binaryName: string): void;

package/dist/help.js

@@ -0,0 +1,79 @@
+import { CLI_EXIT_CODE_TABLE } from "@oxygen/shared";
+// Grouped `--help` for the ~70 top-level command groups: commander's default
+// registration-order wall (login, auth, profiles, ... before any GTM noun) is
+// the first thing every fresh agent reads, so order it by the OXYGEN OS layer
+// a command belongs to and close with an agent quickstart + the reserved
+// exit-code table. Commands missing from the map land in the last group so a
+// new command never disappears from help.
+const HELP_GROUPS = [
+    {
+        heading: "Get started & account:",
+        commands: [
+            "login", "auth", "profiles", "logout", "update", "api-keys", "whoami",
+            "onboarding", "status", "orgs", "commands", "skills", "session",
+            "support", "feedback",
+        ],
+    },
+    {
+        heading: "Knowledge (context, wiki, recipes):",
+        commands: ["context", "knowledge", "prompts", "templates", "blueprints"],
+    },
+    {
+        heading: "Data (tables, CRM, dashboards):",
+        commands: [
+            "tables", "rows", "cells", "columns", "action-column", "enrich-column",
+            "enrichment", "table-runs", "table-ingestions", "runs", "crm",
+            "dashboards", "projects", "signup-leads",
+        ],
+    },
+    {
+        heading: "Sourcing & search:",
+        commands: ["sourcing", "lead-sourcing", "search", "companies", "people", "find", "tools"],
+    },
+    {
+        heading: "Outbound & channels:",
+        commands: [
+            "sequences", "senders", "inbox", "messages", "mailboxes",
+            "managed-inboxes", "deliverability", "domains", "email", "schedules",
+            "suppressions", "egress", "linkedin", "connections", "followers",
+            "viewers", "posts", "engagement", "whatsapp", "publishing", "notetaker",
+            "reviews",
+        ],
+    },
+    {
+        heading: "Automation, billing & admin:",
+        commands: [
+            "workflows", "integrations", "custom-integrations", "billing", "budget",
+            "observability", "worker", "db", "admin", "directory",
+        ],
+    },
+];
+const FALLBACK_HEADING = "Other commands:";
+export function applyOxygenHelp(program, binaryName) {
+    const headingByCommand = new Map();
+    for (const group of HELP_GROUPS) {
+        for (const name of group.commands)
+            headingByCommand.set(name, group.heading);
+    }
+    for (const command of program.commands) {
+        command.helpGroup(headingByCommand.get(command.name()) ?? FALLBACK_HEADING);
+    }
+    const exitCodeLine = Object.entries(CLI_EXIT_CODE_TABLE)
+        .map(([code, meaning]) => `${code} ${meaning.split(" (")[0]}`)
+        .join(" · ");
+    program.addHelpText("afterAll", [
+        "",
+        "Agent quickstart:",
+        `  1. ${binaryName} login                      connect this terminal (or set OXYGEN_API_KEY)`,
+        `  2. ${binaryName} onboarding start --json    load workspace context + the skill that teaches the GTM loops`,
+        `  3. ${binaryName} commands --json            full machine-readable command grammar (this CLI's self-index)`,
+        "",
+        "Conventions:",
+        "  --json prints a stable envelope {ok, data|error, meta}; errors always print it.",
+        "  Commands that spend credits or write to external platforms are gated: live runs",
+        "  require --approved --max-credits <n> and fail with a typed error until approved.",
+        "  State-changing responses include a web_url deep-link to inspect the result.",
+        "",
+        `Exit codes: ${exitCodeLine}`,
+    ].join("\n"));
+}

package/dist/http-client.d.ts

@@ -10,6 +10,7 @@ type RequestOptions = {
     traceId?: string;
     fetch?: typeof fetch;
     selectedOrganization?: string;
+    idempotencyKey?: string;
 };
 export declare function requestOxygen<T>(// skipcq: JS-R1005
 path: string, options?: RequestOptions): Promise<T>;

package/dist/http-client.js

@@ -42,6 +42,17 @@ path, options = {}) {
     if (options.body) {
         headers["Content-Type"] = "application/json";
     }
+    // Every mutating request carries an idempotency key. Routes that support
+    // replay dedupe on it; others ignore the header. On a timeout the key is
+    // echoed in error details so a re-run (OXYGEN_IDEMPOTENCY_KEY=<key>) can
+    // retry without duplicating the write once the route supports replay.
+    const method = options.method ?? "GET";
+    const idempotencyKey = method === "GET"
+        ? undefined
+        : options.idempotencyKey ?? process.env.OXYGEN_IDEMPOTENCY_KEY ?? randomUUID();
+    if (idempotencyKey) {
+        headers["Idempotency-Key"] = idempotencyKey;
+    }
     let response;
     const timeoutMs = resolveRequestTimeoutMs(options.timeoutMs);
     const timeout = createTimeoutSignal(timeoutMs);
@@ -64,6 +75,7 @@ path, options = {}) {
                     path,
                     timeout_ms: timeoutMs,
                     trace_id: traceId,
+                    ...(idempotencyKey ? { idempotency_key: idempotencyKey } : {}),
                 },
                 exitCode: 1,
             });
@@ -72,6 +84,7 @@ path, options = {}) {
             details: {
                 api_url: apiUrl,
                 reason: error instanceof Error ? error.message : "unknown",
+                ...(idempotencyKey ? { idempotency_key: idempotencyKey } : {}),
             },
             exitCode: 1,
         });

package/dist/index.js

@@ -7,14 +7,16 @@ import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { Command, Option } from "commander";
-import { AGENCY_DIRECTORY_REGIONS, AGENCY_DIRECTORY_SERVICES, formatCellForDisplay, formatPublicBudgetScopes, OXYGEN_VERSION, OxygenError, success, toFailure, } from "@oxygen/shared";
+import { applyOxygenHelp } from "./help.js";
+import { buildCommandManifest } from "./command-manifest.js";
+import { AGENCY_DIRECTORY_REGIONS, AGENCY_DIRECTORY_SERVICES, formatCellForDisplay, formatPublicBudgetScopes, exitCodeForOxygenError, isVersionGreater, isVersionLess, OXYGEN_VERSION, OxygenError, parseKnowledgePageMarkdown, success, toFailure, } from "@oxygen/shared";
 import { inferImportColumnLabels, inferRowsFileFormat, normalizeImportColumnKey, normalizeRowsForNewTable, normalizeRowsFormat, parseRowsFileBuffer, } from "@oxygen/shared/file-import";
 import { assertRecipeBundleSafe, assertWorkflowManifest, buildRecipeManifest, compileWorkflowDefinition, isAnyWorkflowManifest, isRecipeManifest, isWorkflowDefinition, isWorkflowManifest, } from "@oxygen/workflows";
 import { isRecipeDefinition } from "@oxygen/recipe-sdk";
 import { createBrowserLoginSession, openBrowser } from "./browser-login.js";
 import { clearCredentials, defaultApiUrl, listCredentialProfiles, loadCredentials, normalizeApiUrl, pickProfileNameForIdentity, pickProfileNameForUserSession, resolveActiveProfile, saveCredentials, switchCredentialProfile, updateActiveOrganizationForProfile, } from "./credentials.js";
 import { ensureFreshCliForApiUrl, requestOxygen } from "./http-client.js";
-import { acquireMirrorLock, clearConflictFiles, deletePageFile, emptyMirrorState, findMirrorSlugByPageId, isFileDirty, listConflictFiles, markMirrorStale, mirrorExists, purgeMirror, resetMirrorForFullResync, quarantineDirtyFile, readMirrorState, releaseMirrorLock, resolveDefaultConfigDir, resolveMirrorDir, writeGeneratedIndexFile, writeGeneratedLogFile, writeMirrorState, writePageFile, } from "./knowledge-mirror.js";
+import { acquireMirrorLock, clearConflictFiles, deletePageFile, emptyMirrorState, findMirrorSlugByPageId, isFileDirty, listConflictFiles, localPageSha256, markMirrorStale, mirrorExists, pageFilePath, planMirrorPush, purgeMirror, resetMirrorForFullResync, quarantineDirtyFile, readMirrorState, releaseMirrorLock, resolveDefaultConfigDir, resolveMirrorDir, writeGeneratedIndexFile, writeGeneratedLogFile, writeMirrorState, writePageFile, } from "./knowledge-mirror.js";
 import { waitForCliRun } from "./run-wait.js";
 import { runLocalCustomHttpColumn } from "./local-custom-http-column.js";
 import { captureCurrentTranscript, collectFeedbackEnvironment, TranscriptCaptureError, } from "./transcript.js";
@@ -119,12 +121,35 @@ async function handleAsyncAction(command, options, action) {
     try {
         const data = await action();
         emitSuccess(command, data, options);
+        writeCreditsReceipt(data);
     }
     catch (error) {
         const failure = toFailure(command, error);
         writeJson(failure);
         writeMaxCreditsHint(error);
-        process.exitCode = error instanceof OxygenError ? error.exitCode : 1;
+        process.exitCode = error instanceof OxygenError ? exitCodeForOxygenError(error) : 1;
+    }
+}
+// Paid envelopes (push 3 legibility) carry a `credits` block: quote on
+// dry_run, receipt on live, remaining balance on both. Mirror it as one
+// stderr line so spend stays visible in a terminal without polluting the
+// machine-read stdout envelope.
+function writeCreditsReceipt(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return;
+    const credits = data.credits;
+    if (!credits || typeof credits !== "object" || Array.isArray(credits))
+        return;
+    const block = credits;
+    const remaining = typeof block.credits_remaining === "number"
+        ? block.credits_remaining.toLocaleString("en-US")
+        : null;
+    if (typeof block.credits_used === "number") {
+        process.stderr.write(`spent ${block.credits_used.toLocaleString("en-US")} credits${remaining !== null ? `, ${remaining} remaining` : ""}\n`);
+        return;
+    }
+    if (typeof block.estimated_credits === "number") {
+        process.stderr.write(`estimated ${block.estimated_credits.toLocaleString("en-US")} credits for a live run${remaining !== null ? `, ${remaining} available` : ""}\n`);
     }
 }
 // Paid live runs are refused server-side with typed spend-gate errors
@@ -1069,7 +1094,7 @@ export function createProgram() {
     const binaryName = resolveCliBinaryName();
     program
         .name(binaryName)
-        .description("CLI/API-first GTM platform for GTM tool and workflow primitives.")
+        .description("Revenue infrastructure for B2B startups — agent-operated GTM: tables, enrichment, sequences, workflows, CRM, knowledge. MCP + CLI first; every state-changing action returns a web_url deep-link.")
         .version(OXYGEN_VERSION)
         .option("--profile <name>", "Use a stored CLI profile for this command.")
         .option("--org <organization>", "Use an organization id, Clerk org id, or slug for this command.");
@@ -1201,9 +1226,17 @@ export function createProgram() {
         .command("whoami")
         .description("Show the current Oxygen CLI identity.")
         .option("--json", "Print a JSON envelope.")
+        .option("--summary-json", "Print a compact identity envelope with no credential-shaped fields (safe for health probes and logs).")
         .action(async (options) => {
         await handleWhoamiAction(options);
     });
+    program
+        .command("commands")
+        .description("Print the machine-readable command manifest: every command with flags, spend/mutation markers, and the reserved exit-code table.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("commands", options, async () => buildCommandManifest(program, binaryName));
+    });
     program
         .command("onboarding")
         .description("Onboarding helpers.")
@@ -1239,14 +1272,26 @@ export function createProgram() {
                 requireAuth: false,
                 enforceMinimumCliVersion: false,
             });
+            // Explicit skew semantics: in_sync=false alone forced every ops sweep
+            // to hand-interpret whether a version gap was safe (fleet friction,
+            // recurring since 2026-06-18). `skew` names the direction and
+            // `compatible` answers the only question that matters: is this CLI at
+            // or above the server's enforced minimum?
+            const minimum = server.minimum_cli_version ?? null;
             return {
                 client_version: OXYGEN_VERSION,
                 api_url: apiUrl,
                 server_version: server.server_version,
-                minimum_cli_version: server.minimum_cli_version ?? null,
+                minimum_cli_version: minimum,
                 sha: server.sha,
                 region: server.region,
                 in_sync: server.server_version === OXYGEN_VERSION,
+                skew: isVersionGreater(OXYGEN_VERSION, server.server_version)
+                    ? "client_ahead"
+                    : isVersionLess(OXYGEN_VERSION, server.server_version)
+                        ? "client_behind"
+                        : "in_sync",
+                compatible: minimum === null || !isVersionLess(OXYGEN_VERSION, minimum),
             };
         });
     });
@@ -3160,6 +3205,28 @@ export function createProgram() {
             method: "POST",
             body: {},
         }));
+    }))
+        .addCommand(new Command("synthesize")
+        .description("Synthesize knowledge from workspace evidence (one low-cost AI call): campaign learnings from auto-filed outreach outcomes, or a voice guide from sent messages. Previews by default; --approved writes the result.")
+        .option("--kind <kind>", "What to synthesize: campaign_learnings (default) or voice.", "campaign_learnings")
+        .option("--sequence <sequence_id>", "Scope campaign learnings to one sequence's learnings page. Omit for the org-wide [[outreach-learnings]] page.")
+        .option("--approved", "Write the synthesized result (learnings page revision / pinned voice guide) instead of previewing.")
+        .option("--body <markdown>", "With --approved: save this edited body verbatim instead of re-synthesizing.")
+        .option("--title <title>", "Optional title for a newly created page/asset.")
+        .option("--limit <n>", "Voice only: how many recent sent messages to learn from (max 200).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("knowledge synthesize", options, () => requestOxygen("/api/cli/knowledge/synthesize", {
+            method: "POST",
+            body: {
+                kind: options.kind ?? "campaign_learnings",
+                ...(readOption(options.sequence) ? { sequence: readOption(options.sequence) } : {}),
+                ...(options.approved ? { approved: true } : {}),
+                ...(readOption(options.body) ? { body: readOption(options.body) } : {}),
+                ...(readOption(options.title) ? { title: readOption(options.title) } : {}),
+                ...(readPositiveInt(options.limit) !== undefined ? { limit: readPositiveInt(options.limit) } : {}),
+            },
+        }));
     }))
         .addCommand(new Command("sync")
         .description("Clone or refresh the local knowledge mirror: server-rendered page markdown under the CLI config dir.")
@@ -3169,6 +3236,13 @@ export function createProgram() {
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("knowledge sync", options, () => runKnowledgeMirrorSync(options));
+    }))
+        .addCommand(new Command("push")
+        .description("Push locally edited or newly created mirror pages back to the workspace wiki. Edits to canonical voice/brand/positioning pages become approval proposals instead of writing live.")
+        .option("--dry-run", "List what would be pushed without writing anything.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("knowledge push", options, () => runKnowledgeMirrorPush(options));
     }))
         .addCommand(new Command("status")
         .description("Report the local knowledge mirror: path, page count, last sync, quarantined conflicts.")
@@ -7282,6 +7356,95 @@ export function createProgram() {
             });
         });
     })));
+    program.addCommand(new Command("managed-inboxes")
+        .description("Managed whitelabel sending inboxes on the OXYGEN-managed Cold Mail Reseller (CMR) account: subscribe a domain + N mailboxes (google/microsoft) as a recurring MONTHLY subscription billed to Oxygen credits, list/get your subscriptions, and cancel. Subscribe/cancel are approval-gated (preview → re-run with --approved --quote).")
+        .addCommand(new Command("subscribe")
+        .description("Subscribe a domain + mailboxes as a managed monthly CMR inbox subscription. WITHOUT --approved this prints a priced PREVIEW with a quote_id (nothing ordered or charged); re-run with --approved --quote <id> to place the order. Fails closed until the managed CMR wallet (CMR_RESELLER_API_KEY) + founder-signed pricing (CMR_MANAGED_INBOX_CREDITS_PER_MAILBOX) are configured.")
+        .requiredOption("--domain <domain>", "Sending domain to register + host the mailboxes (e.g. send.acme.com).")
+        .requiredOption("--provider <provider>", "Mailbox provider: google or microsoft.")
+        .option("--mailboxes <json>", "JSON array of mailboxes: [{\"username\",\"first_name\",\"last_name\",\"profile_picture?\"}].")
+        .option("--file <path>", "Path to a JSON file { \"mailboxes\": [...] } (alternative to --mailboxes).")
+        .option("--years <n>", "Years to register the domain for (positive whole number). Defaults to 1.")
+        .option("--billing <path>", "Path to a JSON file with the CMR billing address (required on the FIRST subscribe for an org that has no CMR account yet).")
+        .option("--zapshield", "Add the Zapshield deliverability-protection add-on to the domain (a one-time per-domain add-on billed once its price is founder-signed; recorded but not charged until then).")
+        .option("--approved", "Place the order (requires --quote). Without it, a priced preview is returned.")
+        .option("--quote <id>", "The quote_id from a fresh preview. Required with --approved.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("managed-inboxes subscribe", options, () => {
+            const domain = readOption(options.domain);
+            const provider = readOption(options.provider);
+            if (!domain)
+                throw new Error("--domain is required.");
+            if (!provider)
+                throw new Error("--provider is required (google or microsoft).");
+            let mailboxes;
+            const mailboxesJson = readOption(options.mailboxes);
+            const filePath = readOption(options.file);
+            if (mailboxesJson) {
+                mailboxes = JSON.parse(mailboxesJson);
+            }
+            else if (filePath) {
+                const parsed = readJsonFileValue(resolve(filePath), "--file");
+                mailboxes = parsed.mailboxes ?? [];
+            }
+            else {
+                throw new Error("Provide --mailboxes <json> or --file <path>.");
+            }
+            const years = readOption(options.years);
+            const billingPath = readOption(options.billing);
+            const billing = billingPath ? readJsonFileValue(resolve(billingPath), "--billing") : undefined;
+            const quote = readOption(options.quote);
+            return requestOxygen("/api/cli/managed-inboxes/subscribe", {
+                method: "POST",
+                body: {
+                    domain,
+                    provider,
+                    mailboxes,
+                    ...(years ? { years: Number(years) } : {}),
+                    ...(billing ? { billing } : {}),
+                    ...(options.zapshield ? { zapshield: true } : {}),
+                    ...(options.approved ? { approved: true } : {}),
+                    ...(quote ? { quote_id: quote } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("list")
+        .description("List the org's managed inbox subscriptions with provider, mailbox count, monthly price, CMR lifecycle status, and internal billing posture. Read-only, 0 Oxygen credits.")
+        .option("--status <status>", "Filter by status: pending, active, renewing, past_due, expired, cancelled, or failed.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("managed-inboxes list", options, () => {
+            const params = new URLSearchParams();
+            const status = readOption(options.status);
+            if (status)
+                params.set("status", status);
+            const suffix = params.toString();
+            return requestOxygen(`/api/cli/managed-inboxes${suffix ? `?${suffix}` : ""}`);
+        });
+    }))
+        .addCommand(new Command("get")
+        .description("Get one managed inbox subscription by domain (provider, mailbox count, monthly price, CMR subscription id, lifecycle status, auto-renew, period end, internal billing status). Read-only, 0 Oxygen credits.")
+        .argument("<domain>", "The managed inbox domain (e.g. send.acme.com).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (domain, options) => {
+        await handleAsyncAction("managed-inboxes get", options, () => requestOxygen(`/api/cli/managed-inboxes/${encodeURIComponent(domain)}`));
+    }))
+        .addCommand(new Command("cancel")
+        .description("Cancel a managed inbox subscription by domain (stops CMR's recurring monthly charge and frees the domain at period end). WITHOUT --approved prints a preview; re-run with --approved to cancel. Cancelling is free — 0 Oxygen credits.")
+        .argument("<domain>", "The managed inbox domain to cancel.")
+        .option("--approved", "Actually cancel (otherwise a preview is returned).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (domain, options) => {
+        await handleAsyncAction("managed-inboxes cancel", options, () => requestOxygen("/api/cli/managed-inboxes/cancel", {
+            method: "POST",
+            body: {
+                domain,
+                ...(options.approved ? { approved: true } : {}),
+            },
+        }));
+    })));
     program.addCommand(new Command("mailboxes")
         .description("Native email sending pool: register/refresh Google/Microsoft mailboxes a campaign rotates over, pause/disable inboxes, and delegate warmup to Instantly (BYOK — Instantly bills your account, 0 Oxygen credits).")
         .addCommand(new Command("list")
@@ -7528,6 +7691,28 @@ export function createProgram() {
             const suffix = params.toString();
             return requestOxygen(`/api/cli/mailboxes/warmup/status${suffix ? `?${suffix}` : ""}`);
         });
+    }))
+        .addCommand(new Command("provision")
+        .description("Export sending mailboxes into the Instantly workspace via Zapmail (the prerequisite for warmup), then let the worker enable warmup once the export completes. Targets the whole pool unless --mailboxes is given. Uses the org's Zapmail connection (BYOK) or the OXYGEN-managed wallet.")
+        .option("--mailboxes <list>", "Comma-separated mailbox ids or addresses to provision. Omit for the whole pool.")
+        .option("--connection <id>", "Zapmail connection id. Defaults to the org's active Zapmail connection (or the managed wallet).")
+        .option("--force", "Re-export mailboxes already exporting/warming/active (default skips them).")
+        .option("--dry-run", "Simulate without calling Zapmail (reports the mailboxes that would be exported).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("mailboxes warmup provision", options, () => {
+            const mailboxes = readCsvOption(options.mailboxes);
+            const connection = readOption(options.connection);
+            return requestOxygen("/api/cli/mailboxes/warmup/provision", {
+                method: "POST",
+                body: {
+                    ...(mailboxes.length > 0 ? { mailboxes } : {}),
+                    ...(connection ? { connection_id: connection } : {}),
+                    ...(options.force ? { force: true } : {}),
+                    ...(options.dryRun ? { dry_run: true } : {}),
+                },
+            });
+        });
     })))
         .addCommand(new Command("order")
         .description("Order NEW sending mailboxes (domain + inboxes + warmup) on the OXYGEN-managed Zapmail wallet, billed to Oxygen credits. Without --approved returns a priced preview + quote_id. FAILS CLOSED (409) until managed ordering is enabled.")
@@ -8195,6 +8380,7 @@ export function createProgram() {
         .action(async (options) => {
         await handleAsyncAction("skills install", options, () => installAgentSkills(options));
     }));
+    applyOxygenHelp(program, binaryName);
     return program;
 }
 /**
@@ -10772,6 +10958,27 @@ async function handleWhoamiAction(options) {
             enforceMinimumCliVersion: false,
         });
         const context = await resolveActiveProfileWithSource();
+        // Compact, credential-free identity shape for health probes and ops
+        // sweeps: the full envelope carries apiKey token prefix/suffix metadata,
+        // which forced every automated consumer to sanitize before logging
+        // (recurring fleet friction since 2026-06-18).
+        if (options.summaryJson) {
+            writeJson(success("whoami", {
+                user: { id: identity.user.id, email: identity.user.email },
+                organization: {
+                    id: identity.organization.id,
+                    name: identity.organization.name,
+                    slug: identity.organization.slug,
+                },
+                auth_type: identity.authType ?? identity.apiKey?.kind ?? null,
+                onboarding_complete: identity.onboarding?.complete ?? null,
+                profile: context.resolution.exists ? context.resolution.name : null,
+                profile_source: context.source,
+                api_url: context.resolution.credentials?.apiUrl ?? null,
+                cli_version: OXYGEN_VERSION,
+            }));
+            return;
+        }
         if (context.resolution.exists) {
             const existingCredentials = context.resolution.credentials;
             const cached = existingCredentials?.identity;
@@ -10807,7 +11014,7 @@ async function handleWhoamiAction(options) {
     catch (error) {
         const failure = toFailure("whoami", error);
         writeJson(failure);
-        process.exitCode = error instanceof OxygenError ? error.exitCode : 1;
+        process.exitCode = error instanceof OxygenError ? exitCodeForOxygenError(error) : 1;
     }
 }
 async function handleOnboardingStartAction(options) {
@@ -10822,7 +11029,7 @@ async function handleOnboardingStartAction(options) {
     catch (error) {
         const failure = toFailure("onboarding start", error);
         writeJson(failure);
-        process.exitCode = error instanceof OxygenError ? error.exitCode : 1;
+        process.exitCode = error instanceof OxygenError ? exitCodeForOxygenError(error) : 1;
     }
 }
 async function handleOnboardingResetAction(options) {
@@ -10846,7 +11053,7 @@ async function handleOnboardingResetAction(options) {
     catch (error) {
         const failure = toFailure("onboarding reset", error);
         writeJson(failure);
-        process.exitCode = error instanceof OxygenError ? error.exitCode : 1;
+        process.exitCode = error instanceof OxygenError ? exitCodeForOxygenError(error) : 1;
     }
 }
 function formatOnboardingReset(data) {
@@ -10904,7 +11111,7 @@ async function handleLoginAction(options) {
     catch (error) {
         const failure = toFailure("login", error);
         writeJson(failure);
-        process.exitCode = error instanceof OxygenError ? error.exitCode : 1;
+        process.exitCode = error instanceof OxygenError ? exitCodeForOxygenError(error) : 1;
     }
 }
 async function handleAuthUseTokenAction(options) {
@@ -10934,7 +11141,7 @@ async function handleAuthUseTokenAction(options) {
             writeJson(failure);
         else
             process.stderr.write(`${failure.error.message}\n`);
-        process.exitCode = error instanceof OxygenError ? error.exitCode : 1;
+        process.exitCode = error instanceof OxygenError ? exitCodeForOxygenError(error) : 1;
     }
 }
 async function handleAuthDoctorAction(options) {
@@ -10949,7 +11156,7 @@ async function handleAuthDoctorAction(options) {
     catch (error) {
         const failure = toFailure("auth doctor", error);
         writeJson(failure);
-        process.exitCode = error instanceof OxygenError ? error.exitCode : 1;
+        process.exitCode = error instanceof OxygenError ? exitCodeForOxygenError(error) : 1;
     }
 }
 async function runAuthDoctor() {
@@ -11040,7 +11247,7 @@ async function handleOrgUseAction(organization, options, command) {
     catch (error) {
         const failure = toFailure(command, error);
         writeJson(failure);
-        process.exitCode = error instanceof OxygenError ? error.exitCode : 1;
+        process.exitCode = error instanceof OxygenError ? exitCodeForOxygenError(error) : 1;
     }
 }
 async function handleProfilesListAction(options) {
@@ -11059,7 +11266,7 @@ async function handleProfilesListAction(options) {
     catch (error) {
         const failure = toFailure("profiles list", error);
         writeJson(failure);
-        process.exitCode = error instanceof OxygenError ? error.exitCode : 1;
+        process.exitCode = error instanceof OxygenError ? exitCodeForOxygenError(error) : 1;
     }
 }
 async function handleProfilesUseAction(profile, options) {
@@ -11080,7 +11287,7 @@ async function handleProfilesUseAction(profile, options) {
     catch (error) {
         const failure = toFailure("profiles use", error);
         writeJson(failure);
-        process.exitCode = error instanceof OxygenError ? error.exitCode : 1;
+        process.exitCode = error instanceof OxygenError ? exitCodeForOxygenError(error) : 1;
     }
 }
 async function handleProfilesEnvAction(profile, options) {
@@ -11119,7 +11326,7 @@ async function handleProfilesEnvAction(profile, options) {
     catch (error) {
         const failure = toFailure("profiles env", error);
         writeJson(failure);
-        process.exitCode = error instanceof OxygenError ? error.exitCode : 1;
+        process.exitCode = error instanceof OxygenError ? exitCodeForOxygenError(error) : 1;
     }
 }
 async function handleProfilesCurrentAction(options) {
@@ -11143,7 +11350,7 @@ async function handleProfilesCurrentAction(options) {
     catch (error) {
         const failure = toFailure("profiles current", error);
         writeJson(failure);
-        process.exitCode = error instanceof OxygenError ? error.exitCode : 1;
+        process.exitCode = error instanceof OxygenError ? exitCodeForOxygenError(error) : 1;
     }
 }
 function shellQuote(value) {
@@ -11172,7 +11379,7 @@ async function handleLogoutAction(options) {
     catch (error) {
         const failure = toFailure("logout", error);
         writeJson(failure);
-        process.exitCode = error instanceof OxygenError ? error.exitCode : 1;
+        process.exitCode = error instanceof OxygenError ? exitCodeForOxygenError(error) : 1;
     }
 }
 async function handleUpdateAction(options) {
@@ -11187,7 +11394,7 @@ async function handleUpdateAction(options) {
     catch (error) {
         const failure = toFailure("update", error);
         writeJson(failure);
-        process.exitCode = error instanceof OxygenError ? error.exitCode : 1;
+        process.exitCode = error instanceof OxygenError ? exitCodeForOxygenError(error) : 1;
     }
 }
 function buildApiKeyCreateBody(options) {
@@ -11798,7 +12005,7 @@ async function handleSequenceSignalAction(sequence, options) {
         const failure = toFailure("sequences signal", error);
         writeJson(failure);
         writeMaxCreditsHint(error);
-        process.exitCode = error instanceof OxygenError ? error.exitCode : 1;
+        process.exitCode = error instanceof OxygenError ? exitCodeForOxygenError(error) : 1;
     }
 }
 async function handleSequenceVariantsAction(sequence, options) {
@@ -11835,7 +12042,7 @@ async function handleSequenceVariantsAction(sequence, options) {
         const failure = toFailure("sequences variants", error);
         writeJson(failure);
         writeMaxCreditsHint(error);
-        process.exitCode = error instanceof OxygenError ? error.exitCode : 1;
+        process.exitCode = error instanceof OxygenError ? exitCodeForOxygenError(error) : 1;
     }
 }
 function formatVariantCell(value) {
@@ -11966,7 +12173,7 @@ async function handleTablesTidySuggestAction(table, options) {
         const failure = toFailure("tables tidy-suggest", error);
         writeJson(failure);
         writeMaxCreditsHint(error);
-        process.exitCode = error instanceof OxygenError ? error.exitCode : 1;
+        process.exitCode = error instanceof OxygenError ? exitCodeForOxygenError(error) : 1;
     }
 }
 function formatTidyCount(value) {
@@ -12349,7 +12556,7 @@ async function handleSupportAdminWorkflowAction(ticketId, options) {
     catch (error) {
         const failure = toFailure("support admin workflow", error);
         writeJson(failure);
-        process.exitCode = error instanceof OxygenError ? error.exitCode : 1;
+        process.exitCode = error instanceof OxygenError ? exitCodeForOxygenError(error) : 1;
     }
 }
 async function handleSupportAdminUpdateAction(ticketId, options) {
@@ -12365,7 +12572,7 @@ async function handleSupportAdminUpdateAction(ticketId, options) {
     catch (error) {
         const failure = toFailure("support admin update", error);
         writeJson(failure);
-        process.exitCode = error instanceof OxygenError ? error.exitCode : 1;
+        process.exitCode = error instanceof OxygenError ? exitCodeForOxygenError(error) : 1;
     }
 }
 function formatSupportAdminWorkflowStep(styles, label, status, artifactLabel, artifact) {
@@ -12916,6 +13123,152 @@ async function runKnowledgeMirrorSync(options) {
         releaseMirrorLock(target.dir);
     }
 }
+// One page's push: parse the local file, guard identity, upsert with the manifest
+// revision as the optimistic-concurrency base, and translate the two expected
+// gate outcomes (approval proposal, revision conflict) into statuses.
+async function pushOneMirrorPage(dir, state, candidate) {
+    const { slug, kind, record } = candidate;
+    let contents;
+    try {
+        contents = readFileSync(pageFilePath(dir, slug), "utf8");
+    }
+    catch {
+        return { slug, kind, status: "skipped", reason: "file_unreadable" };
+    }
+    const parsed = parseKnowledgePageMarkdown(contents);
+    if (record && parsed.id && parsed.id !== record.id) {
+        return { slug, kind, status: "skipped", reason: "id_mismatch_with_manifest" };
+    }
+    if (parsed.slug && parsed.slug !== slug) {
+        return { slug, kind, status: "skipped", reason: "frontmatter_slug_differs_from_filename" };
+    }
+    const body = {
+        slug,
+        body: parsed.body,
+        ...(parsed.title ? { title: parsed.title } : {}),
+        ...(parsed.type ? { type: parsed.type } : {}),
+        ...(parsed.status ? { status: parsed.status } : {}),
+        ...(parsed.tags ? { tags: parsed.tags } : {}),
+        // A frontmatter block owns the summary line: pushing an emptied summary
+        // clears it server-side; a plain new file leaves summary untouched.
+        ...(parsed.hasFrontmatter ? { summary: parsed.summary } : {}),
+        ...(record ? { expected_revision: record.revision } : {}),
+    };
+    try {
+        const data = await requestOxygen("/api/cli/knowledge/pages/upsert", { method: "POST", body });
+        const page = data.page ?? {};
+        if (typeof page.id === "string" && typeof page.revision === "number") {
+            // Record the pushed bytes as the manifest truth so the follow-up sync
+            // overwrites this file with the server rendering instead of quarantining
+            // the very edit we just pushed.
+            const localSha = localPageSha256(dir, slug);
+            if (localSha) {
+                state.pages[slug] = { id: page.id, revision: page.revision, content_sha256: localSha };
+            }
+        }
+        return {
+            slug,
+            kind,
+            status: "pushed",
+            ...(typeof page.revision === "number" ? { revision: page.revision } : {}),
+        };
+    }
+    catch (error) {
+        if (error instanceof OxygenError && error.code === "knowledge_approval_required") {
+            const details = (error.details ?? {});
+            return {
+                slug,
+                kind,
+                status: "proposal_created",
+                ...(typeof details.proposalId === "string" ? { proposal_id: details.proposalId } : {}),
+                ...(typeof details.proposalSlug === "string" ? { proposal_slug: details.proposalSlug } : {}),
+                reason: typeof details.reason === "string" ? details.reason : "sensitive_page",
+            };
+        }
+        if (error instanceof OxygenError && error.code === "knowledge_page_conflict") {
+            return { slug, kind, status: "conflict", reason: "revision_moved_run_knowledge_sync_first" };
+        }
+        if (error instanceof OxygenError) {
+            return { slug, kind, status: "failed", reason: error.code };
+        }
+        throw error;
+    }
+}
+// `oxygen knowledge push` — the write half of the local mirror: locally edited
+// (dirty) and brand-new mirror files upsert back to the workspace wiki through
+// the same gate as every other write surface, then a delta sync converges the
+// mirror onto the server rendering. This is what lets a local agent (Claude
+// Code, Codex) work the wiki as plain markdown files.
+async function runKnowledgeMirrorPush(options) {
+    const target = await resolveKnowledgeMirrorTarget();
+    const state = readMirrorState(target.dir);
+    if (!state) {
+        throw new OxygenError("knowledge_mirror_missing", "No local knowledge mirror exists for this organization yet. Run `oxygen knowledge sync` first.", {
+            details: { mirror_path: target.dir },
+            exitCode: 1,
+        });
+    }
+    const plan = planMirrorPush(target.dir, state);
+    if (options.dryRun) {
+        return {
+            dry_run: true,
+            candidates: plan.candidates.map(({ slug, kind, record }) => ({
+                slug,
+                kind,
+                ...(record ? { base_revision: record.revision } : {}),
+            })),
+            skipped: plan.skipped,
+            mirror_path: target.dir,
+            web_url: target.webUrl,
+        };
+    }
+    // Hold the mirror lock through the push phase so a concurrent sync can't
+    // rewrite files or the manifest mid-push; released before the convergence
+    // sync below, which takes the lock itself.
+    if (!acquireMirrorLock(target.dir)) {
+        throw new OxygenError("knowledge_sync_locked", "Another knowledge sync is running for this mirror. Retry shortly; a crashed sync's lock self-clears after 10 minutes.", {
+            details: { mirror_path: target.dir },
+            exitCode: 1,
+        });
+    }
+    const outcomes = [];
+    let pushedCount = 0;
+    try {
+        for (const candidate of plan.candidates) {
+            outcomes.push(await pushOneMirrorPage(target.dir, state, candidate));
+        }
+        pushedCount = outcomes.filter((outcome) => outcome.status === "pushed").length;
+        if (pushedCount > 0) {
+            writeMirrorState(target.dir, state);
+        }
+    }
+    finally {
+        releaseMirrorLock(target.dir);
+    }
+    // Converge: pull the server's rendering of everything just pushed (plus any
+    // proposal draft pages the gate filed) so local bytes match the server again.
+    let syncedAfter = false;
+    if (pushedCount > 0 || outcomes.some((outcome) => outcome.status === "proposal_created")) {
+        await runKnowledgeMirrorSync({});
+        syncedAfter = true;
+    }
+    return {
+        pushed: pushedCount,
+        proposals: outcomes.filter((outcome) => outcome.status === "proposal_created"),
+        conflicts: outcomes.filter((outcome) => outcome.status === "conflict"),
+        failures: outcomes.filter((outcome) => outcome.status === "failed"),
+        skipped: [
+            ...plan.skipped,
+            ...outcomes
+                .filter((outcome) => outcome.status === "skipped")
+                .map(({ slug, reason }) => ({ file: `${slug}.md`, reason: reason ?? "skipped" })),
+        ],
+        outcomes,
+        synced_after: syncedAfter,
+        mirror_path: target.dir,
+        web_url: target.webUrl,
+    };
+}
 async function runKnowledgeMirrorStatus(options) {
     const target = await resolveKnowledgeMirrorTarget();
     const clearedConflicts = options.clearConflicts ? clearConflictFiles(target.dir) : undefined;
@@ -12949,7 +13302,7 @@ async function handleKnowledgeMirrorPrintPathAction() {
     catch (error) {
         const failure = toFailure("knowledge status", error);
         writeJson(failure);
-        process.exitCode = error instanceof OxygenError ? error.exitCode : 1;
+        process.exitCode = error instanceof OxygenError ? exitCodeForOxygenError(error) : 1;
     }
 }
 // Knowledge page routes accept either a UUID (`id`) or a slug (`slug`); split
@@ -13194,4 +13547,13 @@ function muteTokenEcho() {
         return () => undefined;
     }
 }
+// Piping CLI output into a consumer that exits early (`oxygen whoami --json |
+// head -c 20`) otherwise crashes with a raw EPIPE stack after the consumer
+// closes the pipe; a closed pipe is normal shell behavior, not an error.
+process.stdout.on("error", (error) => {
+    if (error.code === "EPIPE")
+        process.exit(0);
+    process.stderr.write(`stdout error: ${error.message}\n`);
+    process.exit(1);
+});
 await createProgram().parseAsync(process.argv);

package/dist/knowledge-mirror.d.ts

@@ -92,6 +92,28 @@ export declare function acquireMirrorLock(dir: string, options?: {
 export declare function releaseMirrorLock(dir: string): void;
 export declare function writeGeneratedIndexFile(dir: string, index: MirrorIndexSnapshot): void;
 export declare function writeGeneratedLogFile(dir: string, entries: MirrorLogEntry[]): void;
+export type MirrorPushCandidate = {
+    slug: string;
+    /** dirty = tracked page whose local bytes drifted; new = untracked local file. */
+    kind: "dirty" | "new";
+    path: string;
+    /** Manifest record for dirty pages — its revision is the optimistic-concurrency base. */
+    record?: MirrorPageRecord;
+};
+export type MirrorPushPlan = {
+    candidates: MirrorPushCandidate[];
+    skipped: Array<{
+        file: string;
+        reason: "invalid_slug" | "reserved_slug" | "generated_file";
+    }>;
+};
+/**
+ * Scan the mirror for pushable local state: tracked pages whose bytes drifted
+ * from the manifest sha (edited locally) and untracked `.md` files (created
+ * locally). Generated index/log summaries and reserved slugs are skipped.
+ * Read-only — the push command decides what to do with the plan.
+ */
+export declare function planMirrorPush(dir: string, state: MirrorState | null): MirrorPushPlan;
 /** Delete the whole mirror (pages, generated files, sidecar). Safe on a missing dir. */
 export declare function purgeMirror(dir: string): void;
 /**

package/dist/knowledge-mirror.js

@@ -327,6 +327,62 @@ function writeGeneratedFile(dir, name, lines) {
 function oneLine(value) {
     return value.replace(/\s+/g, " ").trim();
 }
+// Slugs the server write path refuses (RESERVED_KNOWLEDGE_SLUGS) — an untracked
+// local file under one of these names can never push. A TRACKED page under one
+// (legacy rows may predate the reservation) still pushes by id.
+const PUSH_RESERVED_SLUGS = new Set(["index", "log", "schema", "company-profile", "readme"]);
+/**
+ * Scan the mirror for pushable local state: tracked pages whose bytes drifted
+ * from the manifest sha (edited locally) and untracked `.md` files (created
+ * locally). Generated index/log summaries and reserved slugs are skipped.
+ * Read-only — the push command decides what to do with the plan.
+ */
+export function planMirrorPush(dir, state) {
+    const plan = { candidates: [], skipped: [] };
+    let entries = [];
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return plan; // no mirror directory — nothing to push
+    }
+    for (const entry of entries.sort((a, b) => a.localeCompare(b))) {
+        if (!entry.endsWith(".md"))
+            continue;
+        const slug = entry.slice(0, -3);
+        const path = join(dir, entry);
+        const record = state?.pages[slug];
+        if (record) {
+            if (isFileDirty(dir, slug, record.content_sha256)) {
+                plan.candidates.push({ slug, kind: "dirty", path, record });
+            }
+            continue;
+        }
+        if (slug.length > MIRROR_SLUG_MAX_LENGTH || !MIRROR_SLUG_PATTERN.test(slug)) {
+            plan.skipped.push({ file: entry, reason: "invalid_slug" });
+            continue;
+        }
+        // Untracked generated summaries (index.md / log.md before their slugs are
+        // ever page-backed) carry the marker header — never push those.
+        let head = "";
+        try {
+            head = readFileSync(path, "utf8").slice(0, GENERATED_MIRROR_FILE_HEADER.length);
+        }
+        catch {
+            continue;
+        }
+        if (head === GENERATED_MIRROR_FILE_HEADER) {
+            plan.skipped.push({ file: entry, reason: "generated_file" });
+            continue;
+        }
+        if (PUSH_RESERVED_SLUGS.has(slug)) {
+            plan.skipped.push({ file: entry, reason: "reserved_slug" });
+            continue;
+        }
+        plan.candidates.push({ slug, kind: "new", path });
+    }
+    return plan;
+}
 // ── Purge ───────────────────────────────────────────────────────────────────────
 /** Delete the whole mirror (pages, generated files, sidecar). Safe on a missing dir. */
 export function purgeMirror(dir) {

package/node_modules/@oxygen/shared/dist/billing.d.ts

@@ -26,6 +26,8 @@ export type PricingPlanDefinition = {
 };
 export type PricingPlanMetadata = Record<string, unknown> | null | undefined;
 export declare const CONTACT_SALES_URL = "https://cal.com/tim-scheuer-mxbib9/45";
+export declare const TRIAL_PERIOD_DAYS = 7;
+export declare const TRIAL_CREDIT_GRANT = 1000;
 export declare const BASE_PRICING_PLANS: {
     readonly free: {
         readonly tier: "free";

package/node_modules/@oxygen/shared/dist/billing.js

@@ -2,6 +2,12 @@ export const WEEKLY_USAGE_WINDOW_DAYS = 7;
 export const BILLING_CURRENCIES = ["usd"];
 export const DEFAULT_BILLING_CURRENCY = "usd";
 export const CONTACT_SALES_URL = "https://cal.com/tim-scheuer-mxbib9/45";
+// Card-required free trial: every new signup starts a Stripe trial on the Starter
+// plan, gets TRIAL_CREDIT_GRANT credits (a value-demonstration budget sized to the
+// guided first outcome — NOT the full plan allowance), and converts to paid on
+// credit exhaustion or when the trial clock elapses, whichever comes first.
+export const TRIAL_PERIOD_DAYS = 7;
+export const TRIAL_CREDIT_GRANT = 1_000;
 export const BASE_PRICING_PLANS = {
     free: {
         tier: "free",

package/node_modules/@oxygen/shared/dist/cli-result.d.ts

@@ -30,6 +30,9 @@ export declare class OxygenError extends Error {
         exitCode?: number;
     });
 }
+export declare const CLI_EXIT_CODE_TABLE: Readonly<Record<number, string>>;
+export declare function exitCodeForErrorCode(code: string): number;
+export declare function exitCodeForOxygenError(error: OxygenError): number;
 export declare function success<T>(command: string, data: T, version?: string, minimumCliVersion?: string): CliSuccess<T>;
 export declare function failure(command: string, error: {
     code: string;

package/node_modules/@oxygen/shared/dist/cli-result.js

@@ -19,6 +19,71 @@ export class OxygenError extends Error {
         this.exitCode = options.exitCode ?? 1;
     }
 }
+// Reserved CLI exit codes, so shell agents can branch on failure class without
+// parsing the JSON envelope. Documented in `oxygen --help` and in the
+// `oxygen commands --json` manifest; treat as a stable contract.
+//
+//   0 ok · 1 unclassified error · 2 usage / input validation · 3 auth or CLI
+//   compatibility (not_authenticated, cli_update_required) · 4 not found ·
+//   5 provider / server failure · 6 rate limit (details.retry_after_seconds
+//   says how long to wait) · 7 approval / spend gate (re-run with --approved
+//   --max-credits <n>) · 8 timeout.
+export const CLI_EXIT_CODE_TABLE = {
+    0: "ok",
+    1: "unclassified error",
+    2: "usage / input validation",
+    3: "auth or CLI compatibility",
+    4: "not found",
+    5: "provider or server failure",
+    6: "rate limited (wait details.retry_after_seconds, then retry)",
+    7: "approval / spend gate (re-run with --approved --max-credits <n>)",
+    8: "timeout",
+};
+export function exitCodeForErrorCode(code) {
+    switch (code) {
+        case "not_authenticated":
+        case "unauthorized":
+        case "invalid_token":
+        case "cli_update_required":
+            return 3;
+        case "rate_limit_exceeded":
+            return 6;
+        case "max_credits_required":
+        case "approval_required":
+        case "spend_cap_required":
+        case "spend_cap_too_low":
+        case "insufficient_credits":
+        case "workspace_credit_cap_exceeded":
+        case "byok_requires_paid_plan":
+            return 7;
+        case "network_timeout":
+            return 8;
+        case "provider_error":
+        case "upstream_error":
+        case "internal_error":
+        case "server_error":
+            return 5;
+        default:
+            break;
+    }
+    if (code === "not_found" || code.endsWith("_not_found"))
+        return 4;
+    if (code === "timeout" || code.endsWith("_timeout"))
+        return 8;
+    if (code.startsWith("invalid_")
+        || code.startsWith("missing_")
+        || code === "unknown_fields"
+        || code === "validation_failed") {
+        return 2;
+    }
+    return 1;
+}
+// exitCode 1 is the legacy constructor default at ~170 OxygenError call sites;
+// treat a stored 1 as "unset" and derive the reserved code from the typed
+// error code instead. An explicit non-1 exitCode option always wins.
+export function exitCodeForOxygenError(error) {
+    return error.exitCode !== 1 ? error.exitCode : exitCodeForErrorCode(error.code);
+}
 export function success(command, data, version = OXYGEN_VERSION, minimumCliVersion = OXYGEN_MINIMUM_CLI_VERSION) {
     return {
         ok: true,

package/node_modules/@oxygen/shared/dist/deprecation-registry.d.ts

@@ -0,0 +1,12 @@
+export type DeprecationRegistryEntry = {
+    /** What is deprecated, precisely enough to grep for. */
+    surface: string;
+    /** OXYGEN_VERSION at which the surface became deprecated. */
+    deprecated_in: string;
+    /** Semver deadline, or "floor-bump" (see header). */
+    sunset_version: string;
+    /** Where the surface lives and what removal entails. */
+    note: string;
+};
+export declare const FLOOR_BUMP_SENTINEL = "floor-bump";
+export declare const DEPRECATION_REGISTRY: DeprecationRegistryEntry[];

package/node_modules/@oxygen/shared/dist/deprecation-registry.js

@@ -0,0 +1,58 @@
+// Deprecation sunset registry — the build-enforced list of deprecated agent
+// surfaces and when each one must actually be removed.
+//
+// Why this exists: deprecated aliases ("kept for old clients") historically
+// outlive every intention to remove them because nothing ever fails. The
+// registry inverts that: packages/shared/src/index.test.ts asserts that
+// OXYGEN_VERSION has NOT passed any entry's semver `sunset_version`. Once the
+// version crosses a sunset, the build goes red until the surface is deleted —
+// and removal means deleting the surface AND its registry entry in the same
+// PR.
+//
+// sunset_version values:
+//   - "1.x.y" semver — hard deadline, gated by the test.
+//   - "floor-bump"   — sentinel for surfaces that can only be removed when
+//     OXYGEN_MINIMUM_CLI_VERSION next rises past the clients that still use
+//     them (old CLIs on users' machines send/read these). The test validates
+//     the entry's shape but skips the version gate; whoever bumps the CLI
+//     floor must sweep the "floor-bump" entries in the same change.
+export const FLOOR_BUMP_SENTINEL = "floor-bump";
+export const DEPRECATION_REGISTRY = [
+    {
+        surface: "oxygen_templates_* MCP alias tools",
+        deprecated_in: "1.80.0",
+        sunset_version: "1.290.0",
+        note: "Deprecated alias tree of oxygen_prompts_* (packages/mcp-server/src/tools/" +
+            "prompt-template-tools.ts, prefix \"oxygen_templates\"). Removal: drop the " +
+            "alias prefix from the generated tools and the CLI `templates` alias " +
+            "command tree, then update the pinned tool counts.",
+    },
+    {
+        surface: "oxygen.linkedin-inbox widget alias",
+        deprecated_in: "1.226.0",
+        sunset_version: "1.290.0",
+        note: "Legacy alias of oxygen.unibox kept so MCP clients that cached " +
+            "ui://oxygen/linkedin-inbox keep resolving (packages/mcp-server/src/widgets/" +
+            "definitions.ts). Removal: delete the alias widget definition and any " +
+            "bindings that still point at it.",
+    },
+    {
+        surface: "CLI deepLink/deep_link response keys",
+        deprecated_in: "1.8.2",
+        sunset_version: FLOOR_BUMP_SENTINEL,
+        note: "web_url has been the canonical deep-link key since at least v1.8.2; " +
+            "/api/cli responses still duplicate it as deepLink/deep_link because " +
+            "CLIs at or below the current minimum version read the legacy keys. " +
+            "Remove the duplicated keys (and the CLI readers) when " +
+            "OXYGEN_MINIMUM_CLI_VERSION next rises past those clients.",
+    },
+    {
+        surface: "CLI --return/--org legacy flags",
+        deprecated_in: "1.0.0",
+        sunset_version: FLOOR_BUMP_SENTINEL,
+        note: "Legacy aliases of --return-mode/--org-id on `oxygen tools run` " +
+            "(packages/cli/src/index.ts); aliased since before versioned commits. " +
+            "Remove the flags and their request-body mappings when " +
+            "OXYGEN_MINIMUM_CLI_VERSION next rises past CLIs that send them.",
+    },
+];

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

@@ -21,3 +21,28 @@ export type KnowledgePageRenderInput = {
  * verbatim with exactly one trailing newline.
  */
 export declare function renderKnowledgePageMarkdown(page: KnowledgePageRenderInput): string;
+export type ParsedKnowledgePageMarkdown = {
+    /** True when the file opened with a `---` frontmatter block (any keys). */
+    hasFrontmatter: boolean;
+    /** Raw scalar frontmatter values by key (tags stay in their `[a, b]` form here). */
+    frontmatter: Record<string, string>;
+    id: string | null;
+    slug: string | null;
+    type: string | null;
+    title: string | null;
+    status: string | null;
+    tags: string[] | null;
+    summary: string | null;
+    revision: number | null;
+    /** Body text below the frontmatter (whole file when none), no trailing newline. */
+    body: string;
+};
+/**
+ * Parse a mirror page file back into its fields — the inverse of
+ * renderKnowledgePageMarkdown, tolerant of human/agent edits (`oxygen knowledge
+ * push` runs this on locally edited files). Line-based like the renderer's
+ * contract: `key: value` pairs between `---` fences, tags as `[a, b]`. A file
+ * without a frontmatter block parses as pure body; a plain-markdown title is
+ * derived from the first `# heading` so brand-new local files can push.
+ */
+export declare function parseKnowledgePageMarkdown(contents: string): ParsedKnowledgePageMarkdown;

package/node_modules/@oxygen/shared/dist/knowledge-markdown.js

@@ -55,3 +55,77 @@ export function renderKnowledgePageMarkdown(page) {
     const body = (page.body ?? "").replace(/\r\n/g, "\n").replace(/\n+$/, "");
     return `${lines.join("\n")}\n${body}\n`;
 }
+/**
+ * Parse a mirror page file back into its fields — the inverse of
+ * renderKnowledgePageMarkdown, tolerant of human/agent edits (`oxygen knowledge
+ * push` runs this on locally edited files). Line-based like the renderer's
+ * contract: `key: value` pairs between `---` fences, tags as `[a, b]`. A file
+ * without a frontmatter block parses as pure body; a plain-markdown title is
+ * derived from the first `# heading` so brand-new local files can push.
+ */
+export function parseKnowledgePageMarkdown(contents) {
+    const text = contents.replace(/\r\n/g, "\n");
+    const lines = text.split("\n");
+    const parsed = {
+        hasFrontmatter: false,
+        frontmatter: {},
+        id: null,
+        slug: null,
+        type: null,
+        title: null,
+        status: null,
+        tags: null,
+        summary: null,
+        revision: null,
+        body: "",
+    };
+    let bodyStart = 0;
+    if (lines[0]?.trim() === "---") {
+        const closing = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+        if (closing > 0) {
+            parsed.hasFrontmatter = true;
+            for (const line of lines.slice(1, closing)) {
+                const separator = line.indexOf(":");
+                if (separator <= 0)
+                    continue;
+                const key = line.slice(0, separator).trim();
+                if (!/^[A-Za-z0-9_-]+$/.test(key))
+                    continue;
+                parsed.frontmatter[key] = line.slice(separator + 1).trim();
+            }
+            bodyStart = closing + 1;
+            // The renderer emits exactly one blank line after the closing fence.
+            if (lines[bodyStart] === "")
+                bodyStart += 1;
+        }
+    }
+    parsed.body = lines.slice(bodyStart).join("\n").replace(/\n+$/, "");
+    const fm = parsed.frontmatter;
+    const str = (key) => {
+        const value = fm[key];
+        return value !== undefined && value !== "" ? value : null;
+    };
+    parsed.id = str("id");
+    parsed.slug = str("slug");
+    parsed.type = str("type");
+    parsed.title = str("title");
+    parsed.status = str("status");
+    parsed.summary = str("summary");
+    if (fm.tags !== undefined) {
+        const inner = fm.tags.replace(/^\[/, "").replace(/\]$/, "");
+        parsed.tags = inner
+            .split(",")
+            .map((tag) => tag.trim())
+            .filter((tag) => tag.length > 0);
+    }
+    if (fm.revision !== undefined) {
+        const revision = Number.parseInt(fm.revision, 10);
+        parsed.revision = Number.isFinite(revision) ? revision : null;
+    }
+    if (!parsed.title) {
+        const heading = lines.slice(bodyStart).find((line) => /^#\s+\S/.test(line));
+        if (heading)
+            parsed.title = heading.replace(/^#\s+/, "").trim() || null;
+    }
+    return parsed;
+}

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

@@ -1,2 +1,2 @@
-export declare const OXYGEN_VERSION = "1.275.2";
+export declare const OXYGEN_VERSION = "1.284.3";
 export declare const OXYGEN_MINIMUM_CLI_VERSION = "1.181.0";

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

@@ -1,4 +1,4 @@
-export const OXYGEN_VERSION = "1.275.2";
+export const OXYGEN_VERSION = "1.284.3";
 // Bump this only when deployed CLI/API contracts require a newer CLI.
 // 1.181.0: paid table action runs and background columns run require
 // approved=true in addition to max_credits; older CLIs cannot send the flag.

package/package.json

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