@oxygen-agent/cli 1.575.19 → 1.610.7

package/dist/index.js

@@ -8,8 +8,8 @@ import { stdin as input, stdout as output } from "node:process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { Command, CommanderError, Option } from "commander";
 import { applyOxygenHelp } from "./help.js";
-import { buildCommandManifest } from "./command-manifest.js";
-import { AGENCY_DIRECTORY_REGIONS, AGENCY_DIRECTORY_SERVICES, describeWorkflowStatusChange, formatCellForDisplay, formatPublicBudgetScopes, exitCodeForOxygenError, parseWorkflowStatusChange, isVersionGreater, isVersionLess, MAX_MCP_TOOL_NAME_LENGTH, OXYGEN_VERSION, OxygenError, parseKnowledgePageMarkdown, PLAN_LIMITS, sleep, success, TAG_KINDS_PROSE, toFailure, workflowMcpToolName, } from "@oxygen/shared";
+import { buildCommandManifest, getCommandManifestEntry, searchCommandManifest, suggestCommandNames, } from "./command-manifest.js";
+import { AGENCY_DIRECTORY_REGIONS, AGENCY_DIRECTORY_SERVICES, describeWorkflowStatusChange, formatCellForDisplay, formatPublicBudgetScopes, exitCodeForOxygenError, parseWorkflowStatusChange, isVersionGreater, isVersionLess, MAX_MCP_TOOL_NAME_LENGTH, OXYGEN_CAPABILITY_ROUTES, OXYGEN_VERSION, OxygenError, getCapabilityRouteMatch, inferCapabilityRoute, parseKnowledgePageMarkdown, PLAN_LIMITS, serializeCapabilityRoute, sleep, success, TAG_KINDS_PROSE, toFailure, workflowMcpToolName, } from "@oxygen/shared";
 import { TAG_COLORS } from "@oxygen/shared/select-options";
 import { inferImportColumnLabels, inferRowsFileFormat, normalizeImportColumnKey, normalizeRowsForNewTable, normalizeRowsFormat, parseRowsFileBuffer, } from "@oxygen/shared/file-import";
 import { assertRecipeBundleSafe, assertWorkflowGraphManifest, assertWorkflowManifest, buildRecipeManifest, compileWorkflowDefinition, isAnyWorkflowManifest, isRecipeManifest, isWorkflowDefinition, isWorkflowGraphManifest, isWorkflowManifest, } from "@oxygen/workflows";
@@ -24,7 +24,7 @@ import { formatAiPromptPreviewNotice } from "./column-run-notices.js";
 import { runLocalCustomHttpColumn } from "./local-custom-http-column.js";
 import { captureCurrentTranscript, collectFeedbackEnvironment, TranscriptCaptureError, } from "./transcript.js";
 import { addSessionOutput, addSessionStatus, getSessionUsage, startSession, updateSessionStep, } from "./session.js";
-import { doctorAgentSkills, installAgentSkills, listAgentSkills, runAutomaticSkillsInstall, } from "./skills.js";
+import { doctorAgentSkills, getAgentSkill, installAgentSkills, listAgentSkills, runAutomaticSkillsInstall, searchAgentSkills, } from "./skills.js";
 import { resolveCliBinaryName } from "./runtime.js";
 import { updateCli } from "./update.js";
 import { isRecord, readErrorMessage, readOption } from "./util.js";
@@ -289,6 +289,7 @@ async function handleAsyncAction(command, options, action) {
     try {
         const data = await action();
         emitSuccess(command, data, options);
+        writeDryRunNotice(data);
         writeCreditsReceipt(data);
     }
     catch (error) {
@@ -304,6 +305,24 @@ function emitCliFailure(command, error) {
     writeMaxCreditsHint(error);
     process.exitCode = error instanceof OxygenError ? exitCodeForOxygenError(error) : 1;
 }
+// A dry run's stdout envelope looks like a successful result — same shape, same
+// `ok: true` — so in a terminal the only tell that nothing was fetched was
+// `meta.mode` buried inside the payload. That is how a working provider key gets
+// reported as broken: the preview comes back empty and reads as a failed live
+// call. Mirror the server's preview banner on stderr, the same stdout/stderr
+// split the credits receipt uses, so the machine-read envelope stays clean.
+function writeDryRunNotice(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return;
+    const preview = data.preview;
+    if (!preview || typeof preview !== "object" || Array.isArray(preview))
+        return;
+    const block = preview;
+    if (typeof block.message === "string")
+        process.stderr.write(`${block.message}\n`);
+    if (typeof block.next_step === "string")
+        process.stderr.write(`${block.next_step}\n`);
+}
 // 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
@@ -639,99 +658,217 @@ function readJsonFileValue(path, inputName) {
 /**
  * Whitelist mailbox import fields before the local file crosses the network.
  * In particular, a credential cannot be silently sent through the ordinary
- * inline path: the caller must choose --from hypertide so the server applies
- * the encrypted transfer-vault contract.
+ * inline path: the caller must choose --from credentials (or the Hypertide
+ * shortcut) so the server applies the encrypted transfer-vault contract.
  */
-function normalizeMailboxImportFile(value, source) {
+function normalizeMailboxImportFile(value, mode) {
     if (!Array.isArray(value) || value.length === 0) {
         throw new OxygenError("invalid_request", "--file must contain a non-empty mailboxes array.", { exitCode: 1 });
     }
-    return value.map((entry, index) => {
+    const rows = value.map((entry, index) => {
         if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
             throw new OxygenError("invalid_request", `mailboxes[${index}] must be an object.`, { exitCode: 1 });
         }
-        const rawRow = entry;
-        const row = source === "hypertide"
-            ? normalizeHypertideMailboxExportRow(rawRow, index)
-            : rawRow;
-        const hasCredential = typeof row.app_password === "string" || typeof row.password === "string";
-        if (source === "inline" && hasCredential) {
-            throw new OxygenError("invalid_request", "Mailbox credentials require --from hypertide; the ordinary inline import never accepts or forwards passwords.", { exitCode: 1 });
-        }
-        return {
-            ...(typeof row.email_address === "string"
-                ? { email_address: row.email_address }
-                : {}),
-            ...(typeof row.provider === "string" ? { provider: row.provider } : {}),
-            ...(typeof row.workspace_external_id === "string"
-                ? { workspace_external_id: row.workspace_external_id }
-                : {}),
-            ...(source === "hypertide" && typeof row.app_password === "string"
-                ? { app_password: row.app_password }
-                : {}),
-        };
+        return normalizeMailboxExportRow(entry, index, mode);
     });
+    return dedupeMailboxImportRows(rows);
+}
+function summarizeMailboxImportValidation(mailboxes, input) {
+    const providers = { google: 0, microsoft: 0 };
+    const infrastructurePlatforms = {};
+    let credentialRows = 0;
+    for (const mailbox of mailboxes) {
+        if (mailbox.provider === "google")
+            providers.google += 1;
+        if (mailbox.provider === "microsoft")
+            providers.microsoft += 1;
+        if (typeof mailbox.infrastructure_platform === "string") {
+            const platform = mailbox.infrastructure_platform;
+            infrastructurePlatforms[platform] =
+                (infrastructurePlatforms[platform] ?? 0) + 1;
+        }
+        if (typeof mailbox.app_password === "string")
+            credentialRows += 1;
+    }
+    return {
+        valid: true,
+        source: input.source,
+        ...(input.sourceProvider
+            ? { source_provider: input.sourceProvider }
+            : {}),
+        rows: mailboxes.length,
+        providers,
+        infrastructure_platforms: infrastructurePlatforms,
+        credential_rows: credentialRows,
+        identity_only_rows: mailboxes.length - credentialRows,
+        limits: {
+            max_rows: MAILBOX_IMPORT_ROW_LIMIT,
+            max_file_bytes: MAILBOX_IMPORT_FILE_MAX_BYTES,
+        },
+        mutation: false,
+        network_request: false,
+        provider_call: false,
+        credits_used: 0,
+        next_action: "Re-run the same command without --validate-only to register these mailboxes.",
+    };
 }
-const HYPERTIDE_EMAIL_HEADERS = new Set([
+const MAILBOX_EMAIL_HEADERS = new Set([
     "address",
     "email",
     "emailaddress",
+    "fromemail",
     "mailbox",
     "mailboxaddress",
     "mailboxemail",
 ]);
-const HYPERTIDE_PROVIDER_HEADERS = new Set([
+const MAILBOX_PROVIDER_HEADERS = new Set([
     "emailprovider",
+    "esp",
     "mailboxprovider",
     "platform",
     "provider",
     "serviceprovider",
     "type",
 ]);
-const HYPERTIDE_PASSWORD_HEADERS = new Set([
+const MAILBOX_PASSWORD_HEADERS = new Set([
     "apppassword",
+    "applicationpassword",
+    "googleapppassword",
     "imappassword",
     "mailboxpassword",
     "password",
     "smtppassword",
 ]);
-const HYPERTIDE_WORKSPACE_HEADERS = new Set([
+const MAILBOX_WORKSPACE_HEADERS = new Set([
     "externalaccountid",
+    "mailboxid",
+    "mailboxuid",
+    "sourceaccountid",
+    "sourcemailboxid",
+    "uid",
     "workspaceexternalid",
 ]);
+const MAILBOX_PLATFORM_HEADERS = new Set([
+    "infrastructure",
+    "infrastructureplatform",
+    "infraplatform",
+]);
+const MAILBOX_TENANT_HEADERS = new Set([
+    "azuretenantid",
+    "entratenantid",
+    "microsofttenantid",
+    "tenantid",
+]);
+const MAILBOX_NON_TRANSFERABLE_SECRET_HEADERS = new Set([
+    "accesstoken",
+    "applicationsecret",
+    "authenticatorsecret",
+    "authorization",
+    "authorizationcode",
+    "bearertoken",
+    "clientsecret",
+    "clientprivatekey",
+    "delegationkey",
+    "idtoken",
+    "mfacode",
+    "mfasecret",
+    "oauthaccesstoken",
+    "oauthcode",
+    "oauthrefreshtoken",
+    "oauthtoken",
+    "onetimepassword",
+    "otp",
+    "otpsecret",
+    "privatekey",
+    "refreshtoken",
+    "serviceaccountkey",
+    "serviceaccountjson",
+    "serviceaccountprivatekey",
+    "totp",
+    "totpsecret",
+]);
 const MAILBOX_IMPORT_FILE_MAX_BYTES = 5 * 1024 * 1024;
 const MAILBOX_IMPORT_ROW_LIMIT = 500;
 /**
- * Hypertide's public contract promises a CSV carrying mailbox addresses,
- * app-password/OAuth credentials, and SMTP/IMAP host information, but it does
- * not publish one canonical header spelling. Normalize the common export
- * labels locally, then send only Oxygen's canonical fields. Microsoft passwords
- * are intentionally dropped because tenant consent is its only warmup path.
- * Host/DNS columns are useful for provider inference but never cross the request
- * boundary; Oxygen derives the standard Google/Microsoft endpoints itself.
+ * Normalize common mailbox-vendor export labels locally, then send only
+ * Oxygen's canonical fields. Passwords are accepted only in credential mode
+ * and only become Google app passwords; Microsoft passwords are dropped because
+ * tenant consent is its only warmup path. OAuth grants, MFA/TOTP seeds, and
+ * delegation keys are rejected in every mode. Host columns may prove the
+ * provider but never cross the request boundary.
  */
-function normalizeHypertideMailboxExportRow(row, index) {
+function normalizeMailboxExportRow(row, index, mode) {
     const byHeader = new Map();
     for (const [header, value] of Object.entries(row)) {
-        byHeader.set(normalizeMailboxExportHeader(header), value);
+        const normalizedHeader = normalizeMailboxExportHeader(header);
+        const existing = byHeader.get(normalizedHeader);
+        if (existing !== undefined &&
+            String(existing).trim() !== String(value ?? "").trim()) {
+            throw new OxygenError("invalid_request", `mailboxes[${index}] contains conflicting columns that normalize to ${normalizedHeader}.`, { exitCode: 1 });
+        }
+        byHeader.set(normalizedHeader, value);
+    }
+    const email = readUniqueMailboxExportString(byHeader, MAILBOX_EMAIL_HEADERS, index, "email_address", (value) => value.trim().toLowerCase()) ?? readEmailShapedMailboxUsername(byHeader);
+    const providerValues = readMailboxExportStrings(byHeader, MAILBOX_PROVIDER_HEADERS);
+    const provider = normalizeMailboxProvider(providerValues, byHeader, index);
+    if (!email ||
+        email.length > 320 ||
+        !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}].email_address must be a valid address of at most 320 characters.`, { exitCode: 1 });
     }
-    const email = readMailboxExportString(byHeader, HYPERTIDE_EMAIL_HEADERS) ??
-        readEmailShapedMailboxUsername(byHeader);
-    const providerRaw = readMailboxExportString(byHeader, HYPERTIDE_PROVIDER_HEADERS);
-    const provider = normalizeHypertideMailboxProvider(providerRaw, byHeader, index);
-    const passwords = readMailboxExportStrings(byHeader, HYPERTIDE_PASSWORD_HEADERS);
+    if (!provider) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}].provider could not be inferred. Oxygen imports Google Workspace and Microsoft 365/Entra identities; generic SMTP credentials are not transferable yet.`, { exitCode: 1 });
+    }
+    if (hasMailboxExportValue(byHeader, MAILBOX_NON_TRANSFERABLE_SECRET_HEADERS) ||
+        hasNonTransferableMailboxAuthLikeValue(byHeader)) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}] contains OAuth, MFA/TOTP, client-secret, or delegation material. Those credentials are never transferable; import the mailbox identity and complete the provider's administrator consent flow.`, { exitCode: 1 });
+    }
+    const passwords = readMailboxExportStrings(byHeader, MAILBOX_PASSWORD_HEADERS);
     const distinctPasswords = [...new Set(passwords)];
+    if (distinctPasswords.some((password) => password.length > 1024)) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}].app_password must be at most 1024 characters.`, { exitCode: 1 });
+    }
+    if (mode === "identity" && distinctPasswords.length > 0) {
+        throw new OxygenError("invalid_request", "Mailbox credentials require --from credentials --vendor <source> (or --from hypertide for a Hypertide export); keep --validate-only for a no-network preflight. An identity import never accepts or forwards passwords.", { exitCode: 1 });
+    }
     if (provider !== "microsoft" && distinctPasswords.length > 1) {
         throw new OxygenError("invalid_request", `mailboxes[${index}] contains conflicting SMTP/IMAP/app-password values.`, { exitCode: 1 });
     }
-    const workspaceExternalId = readMailboxExportString(byHeader, HYPERTIDE_WORKSPACE_HEADERS);
+    if (mode === "credential" &&
+        provider === "google" &&
+        distinctPasswords.length === 0) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}] needs a Google app password for credential import. OAuth tokens and an ordinary account password are not portable.`, { exitCode: 1 });
+    }
+    const workspaceExternalId = readUniqueMailboxExportString(byHeader, MAILBOX_WORKSPACE_HEADERS, index, "workspace_external_id", (value) => value.trim());
+    if (workspaceExternalId && workspaceExternalId.length > 512) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}].workspace_external_id must be at most 512 characters.`, { exitCode: 1 });
+    }
+    const tenantId = readUniqueMailboxExportString(byHeader, MAILBOX_TENANT_HEADERS, index, "tenant_id", (value) => value.trim().toLowerCase());
+    if (tenantId && provider !== "microsoft") {
+        throw new OxygenError("invalid_request", `mailboxes[${index}].tenant_id applies only to Microsoft mailboxes.`, { exitCode: 1 });
+    }
+    if (tenantId &&
+        !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(tenantId.trim())) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}].tenant_id must be a Microsoft Entra tenant GUID.`, { exitCode: 1 });
+    }
+    const infrastructurePlatformRaw = readUniqueMailboxExportString(byHeader, MAILBOX_PLATFORM_HEADERS, index, "infrastructure_platform", (value) => normalizeMailboxExportHeader(value)) ??
+        (providerValues.some((value) => ["azure", "entra", "microsoftazure"].includes(normalizeMailboxExportHeader(value)))
+            ? "microsoft_azure"
+            : null);
+    const infrastructurePlatform = normalizeMailboxInfrastructurePlatform(infrastructurePlatformRaw, provider, index);
     return {
-        ...(email !== null ? { email_address: email } : {}),
-        ...(provider !== null ? { provider } : {}),
+        email_address: email.trim().toLowerCase(),
+        provider,
         ...(workspaceExternalId !== null
-            ? { workspace_external_id: workspaceExternalId }
+            ? { workspace_external_id: workspaceExternalId.trim() }
             : {}),
-        ...(provider !== "microsoft" && distinctPasswords[0] !== undefined
+        ...(infrastructurePlatformRaw
+            ? { infrastructure_platform: infrastructurePlatform }
+            : {}),
+        ...(tenantId ? { tenant_id: tenantId.trim().toLowerCase() } : {}),
+        ...(mode === "credential" &&
+            provider === "google" &&
+            distinctPasswords[0] !== undefined
             ? { app_password: distinctPasswords[0] }
             : {}),
     };
@@ -752,6 +889,16 @@ function readMailboxExportString(byHeader, headers) {
     }
     return null;
 }
+function readUniqueMailboxExportString(byHeader, headers, index, field, normalize) {
+    const values = readMailboxExportStrings(byHeader, headers);
+    if (values.length === 0)
+        return null;
+    const normalized = [...new Set(values.map(normalize))];
+    if (normalized.length > 1) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}] contains conflicting ${field} aliases.`, { exitCode: 1 });
+    }
+    return normalized[0] ?? null;
+}
 function readMailboxExportStrings(byHeader, headers) {
     const values = [];
     for (const header of headers) {
@@ -761,24 +908,115 @@ function readMailboxExportStrings(byHeader, headers) {
     }
     return values;
 }
+function hasMailboxExportValue(byHeader, headers) {
+    for (const header of headers) {
+        const value = byHeader.get(header);
+        if (value !== undefined && value !== null && String(value).trim()) {
+            return true;
+        }
+    }
+    return false;
+}
+function hasNonTransferableMailboxAuthLikeValue(byHeader) {
+    for (const [header, value] of byHeader) {
+        if (/(?:token|secret|privatekey|totp|passcode|authorization)/.test(header) &&
+            value !== undefined &&
+            value !== null &&
+            String(value).trim()) {
+            return true;
+        }
+    }
+    return false;
+}
 function readEmailShapedMailboxUsername(byHeader) {
     for (const header of ["username", "imapusername", "smtpusername"]) {
         const value = byHeader.get(header);
         if (typeof value === "string" && value.includes("@"))
-            return value;
+            return value.trim().toLowerCase();
     }
     return null;
 }
-function normalizeHypertideMailboxProvider(providerRaw, byHeader, index) {
-    const normalized = providerRaw
-        ? normalizeMailboxExportHeader(providerRaw)
-        : "";
-    if (["google", "googleworkspace", "gmail", "gsuite"].includes(normalized)) {
-        return "google";
+function normalizeMailboxProvider(providerValues, byHeader, index) {
+    const explicit = providerValues.map((value) => {
+        const normalized = normalizeMailboxExportHeader(value);
+        if (["google", "googleworkspace", "gmail", "gsuite"].includes(normalized)) {
+            return "google";
+        }
+        if ([
+            "azure",
+            "entra",
+            "m365",
+            "microsoft",
+            "microsoft365",
+            "microsoftazure",
+            "ms365",
+            "o365",
+            "office365",
+            "outlook",
+        ].includes(normalized)) {
+            return "microsoft";
+        }
+        throw new OxygenError("invalid_request", `mailboxes[${index}].provider is unsupported; expected Google/Gmail/Workspace or Microsoft/Outlook/Office 365/Entra.`, { exitCode: 1 });
+    });
+    const explicitKinds = [...new Set(explicit)];
+    if (explicitKinds.length > 1) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}] contains conflicting provider aliases.`, { exitCode: 1 });
+    }
+    const hostValues = [
+        byHeader.get("imaphost"),
+        byHeader.get("imaphostname"),
+        byHeader.get("imapserver"),
+        byHeader.get("smtphost"),
+        byHeader.get("smtphostname"),
+        byHeader.get("smtpserver"),
+    ].filter((value) => typeof value === "string" && Boolean(value.trim()));
+    const hostKinds = hostValues.map((value) => {
+        const hostname = normalizeMailboxHost(value);
+        if (hostname === "smtp.gmail.com" || hostname === "imap.gmail.com") {
+            return "google";
+        }
+        if (hostname === "smtp.office365.com" ||
+            hostname === "outlook.office365.com") {
+            return "microsoft";
+        }
+        throw new OxygenError("invalid_request", `mailboxes[${index}] contains a non-standard SMTP/IMAP host. Oxygen imports Google Workspace and Microsoft 365/Entra identities; generic SMTP credential transport is not supported.`, { exitCode: 1 });
+    });
+    const inferredKinds = [...new Set(hostKinds)];
+    if (inferredKinds.length > 1) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}] contains conflicting Google and Microsoft mail hosts.`, { exitCode: 1 });
+    }
+    const explicitKind = explicitKinds[0];
+    const inferredKind = inferredKinds[0];
+    if (explicitKind && inferredKind && explicitKind !== inferredKind) {
+        throw new OxygenError("invalid_request", `mailboxes[${index}] has conflicting provider and SMTP/IMAP host evidence.`, { exitCode: 1 });
+    }
+    return explicitKind ?? inferredKind ?? null;
+}
+function normalizeMailboxHost(value) {
+    const withoutScheme = value
+        .trim()
+        .toLowerCase()
+        .replace(/^[a-z]+:\/\//, "");
+    return withoutScheme.split(/[/:]/, 1)[0] ?? "";
+}
+function normalizeMailboxInfrastructurePlatform(raw, provider, index) {
+    if (!raw) {
+        return provider === "google" ? "google_workspace" : "microsoft_365";
+    }
+    const normalized = normalizeMailboxExportHeader(raw);
+    if (["google", "googleworkspace", "gmail", "gsuite", "workspace"].includes(normalized)) {
+        if (provider !== "google") {
+            throw mailboxPlatformConflict(index, provider);
+        }
+        return "google_workspace";
+    }
+    if (["azure", "entra", "microsoftazure"].includes(normalized)) {
+        if (provider !== "microsoft") {
+            throw mailboxPlatformConflict(index, provider);
+        }
+        return "microsoft_azure";
     }
     if ([
-        "azure",
-        "entra",
         "m365",
         "microsoft",
         "microsoft365",
@@ -787,25 +1025,50 @@ function normalizeHypertideMailboxProvider(providerRaw, byHeader, index) {
         "office365",
         "outlook",
     ].includes(normalized)) {
-        return "microsoft";
+        if (provider !== "microsoft") {
+            throw mailboxPlatformConflict(index, provider);
+        }
+        return "microsoft_365";
     }
-    const hostEvidence = [
-        byHeader.get("imaphost"),
-        byHeader.get("imapserver"),
-        byHeader.get("smtphost"),
-        byHeader.get("smtpserver"),
-    ]
-        .filter((value) => typeof value === "string")
-        .join(" ")
-        .toLowerCase();
-    if (/(?:gmail|google)/.test(hostEvidence))
-        return "google";
-    if (/(?:microsoft|office365|outlook)/.test(hostEvidence)) {
-        return "microsoft";
-    }
-    if (!providerRaw)
+    throw new OxygenError("invalid_request", `mailboxes[${index}].infrastructure_platform is unsupported; expected Google Workspace, Microsoft 365, Azure, or Entra.`, { exitCode: 1 });
+}
+function mailboxPlatformConflict(index, provider) {
+    return new OxygenError("invalid_request", `mailboxes[${index}].infrastructure_platform conflicts with provider=${provider}.`, { exitCode: 1 });
+}
+function dedupeMailboxImportRows(rows) {
+    const unique = new Map();
+    for (const row of rows) {
+        const address = String(row.email_address).toLowerCase();
+        const existing = unique.get(address);
+        if (!existing) {
+            unique.set(address, row);
+            continue;
+        }
+        if (JSON.stringify(existing) !== JSON.stringify(row)) {
+            throw new OxygenError("invalid_request", `Duplicate mailbox ${address} has conflicting provider, platform, tenant, external id, or credential fields.`, { exitCode: 1 });
+        }
+    }
+    return [...unique.values()];
+}
+function normalizeMailboxImportVendor(raw, from) {
+    if (from === "hypertide") {
+        if (raw && raw.trim().toLowerCase() !== "hypertide") {
+            throw new OxygenError("invalid_request", "--from hypertide is fixed to --vendor hypertide.", { exitCode: 1 });
+        }
+        return null;
+    }
+    if (from === "credentials" && !raw) {
+        throw new OxygenError("invalid_request", "--vendor <source> is required with --from credentials so the imported mailbox keeps its provenance.", { exitCode: 1 });
+    }
+    if (!raw)
         return null;
-    throw new OxygenError("invalid_request", `mailboxes[${index}].provider is unsupported; expected Google/Gmail/Workspace or Microsoft/Outlook/Office 365/Entra.`, { exitCode: 1 });
+    const normalized = raw.trim().toLowerCase();
+    if (normalized.length < 1 ||
+        normalized.length > 64 ||
+        !/^[a-z0-9]+(?:[._-][a-z0-9]+)*$/.test(normalized)) {
+        throw new OxygenError("invalid_request", "--vendor must be 1-64 lowercase letters, digits, dots, underscores, or hyphens.", { exitCode: 1 });
+    }
+    return normalized;
 }
 async function readMailboxImportFile(path) {
     let buffer;
@@ -813,7 +1076,7 @@ async function readMailboxImportFile(path) {
         buffer = readFileSync(path);
     }
     catch {
-        throw new OxygenError("mailbox_import_file_unreadable", `Couldn't read --file '${basename(path)}'. Check that the path exists and is readable. Ordinary JSON accepts [{"email_address":"ada@send.acme.com","provider":"google"}] or {"mailboxes":[...]}; credential exports require --from hypertide. See https://oxygen-agent.com/docs/providers/mailbox-compatibility.`, { exitCode: 1 });
+        throw new OxygenError("mailbox_import_file_unreadable", `Couldn't read --file '${basename(path)}'. Check that the path exists and is readable. CSV/JSON/JSONL/XLSX identity files are accepted; credential exports require --from credentials (or --from hypertide). See https://oxygen-agent.com/docs/providers/mailbox-compatibility.`, { exitCode: 1 });
     }
     if (buffer.byteLength > MAILBOX_IMPORT_FILE_MAX_BYTES) {
         throw new OxygenError("invalid_request", `Mailbox import files must be ${MAILBOX_IMPORT_FILE_MAX_BYTES / 1024 / 1024} MB or smaller.`, { exitCode: 1 });
@@ -821,7 +1084,13 @@ async function readMailboxImportFile(path) {
     const format = inferRowsFileFormat(path);
     let rows;
     if (format === "json") {
-        const parsed = parseJsonValue(buffer.toString("utf8"), "--file");
+        let parsed;
+        try {
+            parsed = JSON.parse(buffer.toString("utf8"));
+        }
+        catch {
+            throw new OxygenError("invalid_json", "--file must contain valid JSON. File contents are omitted from this error because mailbox imports may contain credentials.", { exitCode: 1 });
+        }
         if (Array.isArray(parsed)) {
             rows = parsed;
         }
@@ -836,7 +1105,12 @@ async function readMailboxImportFile(path) {
         }
     }
     else {
-        rows = await parseRowsFileBuffer(buffer, format);
+        try {
+            rows = await parseRowsFileBuffer(buffer, format);
+        }
+        catch {
+            throw new OxygenError("invalid_mailbox_import_file", `Couldn't parse the ${format.toUpperCase()} mailbox file. File contents are omitted from this error because mailbox imports may contain credentials.`, { exitCode: 1 });
+        }
     }
     if (rows.length > MAILBOX_IMPORT_ROW_LIMIT) {
         throw new OxygenError("invalid_request", `Mailbox imports are limited to ${MAILBOX_IMPORT_ROW_LIMIT} rows per request.`, { exitCode: 1 });
@@ -1233,7 +1507,10 @@ function readCrmEnrichmentMaxCredits(value) {
     return credits === undefined ? {} : { max_credits: credits };
 }
 function buildCrmSearchBody(query, options) {
-    const objects = readCsvOption(options.objects);
+    // `crm search` is the only command in the family that took the plural, which
+    // cost a failed invocation every time an agent reached for the sibling
+    // spelling. Both are accepted; the plural still wins if somebody passes both.
+    const objects = readCsvOption(options.objects ?? options.object);
     const limit = readPositiveInt(options.limit);
     return {
         query,
@@ -2250,13 +2527,78 @@ export function createProgram() {
         .action(async (options) => {
         await handleAsyncAction("home standup", options, () => requestOxygen("/api/cli/home/standup"));
     });
-    program
+    const commandsCommand = program
         .command("commands")
-        .description("Print the machine-readable command manifest: every command with flags, spend/mutation markers, and the reserved exit-code table.")
+        .description("Discover CLI commands. With no subcommand, print the backwards-compatible full manifest.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("commands", options, async () => buildCommandManifest(program, binaryName));
     });
+    commandsCommand
+        .addCommand(new Command("search")
+        .description("Find a bounded set of CLI commands from a natural-language outcome.")
+        .argument("<query...>", "Outcome or capability to find.")
+        .option("--limit <n>", "Maximum results (default 10, max 25).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (queryParts, options) => {
+        const outputOptions = { ...options, json: options.json || Boolean(commandsCommand.opts().json) };
+        await handleAsyncAction("commands search", outputOptions, async () => {
+            const manifest = buildCommandManifest(program, binaryName);
+            return searchCommandManifest(manifest, queryParts.join(" "), readPositiveInt(options.limit) ?? 10);
+        });
+    }))
+        .addCommand(new Command("get")
+        .description("Hydrate one exact CLI command with its arguments, flags, and safety markers.")
+        .argument("<command...>", "Exact command name returned by commands search.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (commandParts, options) => {
+        const outputOptions = { ...options, json: options.json || Boolean(commandsCommand.opts().json) };
+        await handleAsyncAction("commands get", outputOptions, async () => {
+            const manifest = buildCommandManifest(program, binaryName);
+            const exactName = commandParts.join(" ");
+            const command = getCommandManifestEntry(manifest, exactName);
+            if (!command) {
+                throw new OxygenError("command_not_found", `Unknown Oxygen command: ${exactName}`, {
+                    details: { did_you_mean: suggestCommandNames(manifest, exactName) },
+                    exitCode: 2,
+                });
+            }
+            return command;
+        });
+    }));
+    program
+        .command("capabilities")
+        .description("Route an outcome to its owning OXYGEN layer and hosted primitive.")
+        .addCommand(new Command("search")
+        .description("Find the owning capability, boundary, gateways, and next hydration step.")
+        .argument("<query...>", "Natural-language GTM outcome.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (queryParts, options) => {
+        await handleAsyncAction("capabilities search", options, async () => {
+            const query = queryParts.join(" ");
+            return {
+                query,
+                route: serializeCapabilityRoute(inferCapabilityRoute(query)),
+                hint: "Hydrate one exact CLI command with `oxygen commands get <exact-command> --json`, or one MCP tool with `oxygen_capabilities_schema`.",
+            };
+        });
+    }))
+        .addCommand(new Command("get")
+        .description("Hydrate one exact capability card by id.")
+        .argument("<capability-id>", "Capability id returned by capabilities search.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (capabilityId, options) => {
+        await handleAsyncAction("capabilities get", options, async () => {
+            const route = getCapabilityRouteMatch(capabilityId);
+            if (!route) {
+                throw new OxygenError("capability_not_found", `Unknown OXYGEN capability: ${capabilityId}`, {
+                    details: { available_ids: OXYGEN_CAPABILITY_ROUTES.map((card) => card.id) },
+                    exitCode: 2,
+                });
+            }
+            return serializeCapabilityRoute(route);
+        });
+    }));
     program
         .command("status")
         .description("Compare the local Oxygen CLI version against the active profile's deployed Oxygen API.")
@@ -2808,7 +3150,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .addCommand(new Command("resolve")
         .description("Resolve @handles, LinkedIn profile/company links, provider ids, and URNs — through a connected sender (notify=false, free) or the managed scraper (--source scraper, paid, no sender/window needed).")
         .option("--account <account>", "LinkedIn sender id, connection id, or Unipile account id. Required unless --source scraper.")
-        .option("--source <source>", "Resolution source: sender (default, free) or scraper (managed cookieless lookup, ~10 credits per identity, needs --approved --max-credits).")
+        .option("--source <source>", "Resolution source: sender (default, free) or scraper (managed cookieless lookup; fetch current cost from tools get/dry-run; needs --approved --max-credits).")
         .option("--approved", "Approve the paid scraper lookups (required with --source scraper).")
         .option("--max-credits <n>", "Credit ceiling for scraper lookups (required with --source scraper).")
         .option("--text <text>", "Post text containing @identifiers or LinkedIn URLs.")
@@ -3402,9 +3744,10 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         }));
     })))
         .addCommand(new Command("search")
-        .description("Search CRM records by identity or record label.")
-        .argument("<query>", "Domain, email, LinkedIn URL, or record name to search for.")
+        .description("Search CRM records by identity or record label. Takes ONE query; narrow the objects with --object, not a second argument.")
+        .argument("<query>", "Domain, email, LinkedIn URL, or record name to search for. Quote it if it contains spaces; to restrict to one object use --object companies.")
         .option("--objects <objects>", "Comma-separated CRM object slugs to search. Defaults to all configured objects.")
+        .option("--object <object>", "Alias for --objects; every sibling crm command spells it singular.")
         .option("--limit <limit>", "Maximum records to return.")
         .option("--json", "Print a JSON envelope.")
         .action(async (query, options) => {
@@ -3545,9 +3888,9 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         }));
     }))
         .addCommand(new Command("timeline")
-        .description("Show a CRM record's activity timeline, newest first.")
+        .description("Show a CRM record's activity timeline, newest first. Address the record by row id OR by any of the object's identities \u2014 a company domain, a person's email or LinkedIn URL.")
         .argument("<object>", "CRM object slug, such as companies or people.")
-        .argument("<row_id>", "CRM record row id.")
+        .argument("<record>", "CRM record row id, or an identity value such as acme.com or sarah@acme.com.")
         .option("--limit <limit>", "Maximum activities to return.")
         .option("--cursor <cursor>", "Pagination cursor from a previous page.")
         .option("--json", "Print a JSON envelope.")
@@ -5567,7 +5910,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("preflight")
-        .description("Preflight a blueprint (slug, local file, or shared URL) against this workspace.")
+        .description("Preflight a blueprint (slug, local file, or shared URL) against this workspace. Price-aware seeds return a current runtime descriptor upper bound, cap adequacy, and an exact zero-credit apply command.")
         .argument("[slug]", "Blueprint slug (for stored or seed blueprints).")
         .option("--file <path>", "Read a blueprint envelope from a local JSON file.")
         .option("--from-url <url>", "Fetch a shared blueprint envelope from a public Oxygen share URL.")
@@ -5581,13 +5924,13 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("apply")
-        .description("Apply a blueprint to this workspace. Creates tables, columns, prompts, and a disabled workflow.")
+        .description("Apply a blueprint: 0 credits and no provider calls or external writes, but creates workspace tables, columns, prompts, and a disabled workflow. It does not enable or run the workflow.")
         .argument("[slug]", "Blueprint slug (for stored or seed blueprints).")
         .option("--file <path>", "Read a blueprint envelope from a local JSON file.")
         .option("--from-url <url>", "Fetch a shared blueprint envelope from a public Oxygen share URL.")
         .option("--input-json <json>", "Seed blueprint input (parameters) as JSON.")
         .option("--table-ref <ref=id...>", "Reuse an existing table for a blueprint ref (repeatable).", collectMultiple, [])
-        .option("--workflow-id <id>", "Override the resulting workflow id.")
+        .option("--workflow-id <id>", "Set the new workflow's manifest id/slug; this does not update or reuse an existing workflow.")
         .option("--workflow-name <name>", "Override the resulting workflow name.")
         .option("--json", "Print a JSON envelope.")
         .action(async (slug, options) => {
@@ -5723,7 +6066,19 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
             const qs = params.toString() ? `?${params.toString()}` : "";
             return requestOxygen(`/api/blueprints/marketplace${qs}`, { requireAuth: false });
         });
-    }));
+    }))
+        .addHelpText("after", [
+        "",
+        "Safety:",
+        "  list, describe, and preflight use 0 credits, make no provider calls, and do not change workspace state.",
+        "  Price-aware preflights fetch runtime descriptor pricing, label upper bounds versus exact-shape dry runs,",
+        "  and return the exact apply command that preserves the validated inputs.",
+        "  export has the same workspace safety; --out only writes the named local file.",
+        "  apply also uses 0 credits and makes no provider calls or external writes, but it creates workspace",
+        "  tables, prompts, and a disabled workflow. Its response reports future per-run credit ceilings.",
+        "  save, archive, tag, share, publish, and their inverse commands change workspace or publication state.",
+        "",
+    ].join("\n"));
     program
         .command("recipes")
         .description("Business-case GTM playbooks: proven plays with prerequisites, credit posture, and approval gates spelled out.")
@@ -5856,7 +6211,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .command("columns")
         .description("Workspace table column commands.")
         .addCommand(new Command("add")
-        .description("Add a nullable column to a workspace table.")
+        .description("Add a nullable column to a workspace table. Writes the definition only — this never runs the column and never spends credits; use `columns run` for that, with --dry-run first to see the cost.")
         .argument("<table>", "Table id or slug.")
         .option("--label <label>", "Display label for the new column. Required unless --prompt-key supplies a default title.")
         .option("--key <key>", "Optional stable column key. Defaults to a normalized label.")
@@ -6017,7 +6372,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .description("Run an executable AI, tool, formula, enrichment, bind, lookup, or local custom HTTP column for one row or a bounded batch. Paid server-side columns always run durably in the background. Bind create-mode (onNoMatch=create) needs --approved.")
         .argument("<table>", "Table id or slug.")
         .argument("<column>", "Column id or key.")
-        .option("--row-id <row_id>", "Workspace row id to run.")
+        .option("--row-id <row_id>", "Workspace row id to run. Get one from `oxygen tables query <table> --limit 1 --json` — the field is `_row_id`, not `id`.")
         .option("--limit <n>", "Run the next N rows whose target cell is still empty (--force runs the first N regardless). Repeat until rowCount is 0 to page through a table. Defaults to 10; inline deterministic runs have a hard cap of 25.")
         .option("--all", "Run all rows. Requires --background.")
         .option("--filter-json <json>", "Row selector filter object or array for background runs. Do not combine with --all, --limit, or --row-id.")
@@ -6181,6 +6536,11 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--research-mode <mode>", "Research columns: strict (answer only from the sources) or estimate (reason to a figure from them).")
         .option("--research-results <n>", "Research columns: how many search results to ground each row on (1-25).")
         .option("--research-engine <engine>", "Research columns: pin the search provider (exa, parallel, or firecrawl).")
+        // Declaring BOTH forms leaves the default undefined (Commander only
+        // defaults to true when --no- is declared alone), so an update that
+        // doesn't mention visibility leaves it untouched.
+        .option("--always-show", "Keep this column visible even when it holds no values.")
+        .option("--no-always-show", "Stop pinning this column, so it collapses again while empty.")
         .option("--dry-run", "Return the would-be merged definition without writing.")
         .option("--json", "Print a JSON envelope.")
         .action(async (table, column, options) => {
@@ -6225,6 +6585,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
                     ...(definition ? { definition } : {}),
                     ...(definitionUnset.length > 0 ? { definition_unset: definitionUnset } : {}),
                     ...(readOption(options.dataType) ? { data_type: readOption(options.dataType) } : {}),
+                    ...(typeof options.alwaysShow === "boolean" ? { always_show: options.alwaysShow } : {}),
                     ...(options.dryRun ? { dry_run: true } : {}),
                 },
             });
@@ -7108,7 +7469,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
     })));
     program
         .command("billing")
-        .description("Plan and managed credit commands. Spend splits into FLEXIBLE (ad-hoc: enrichment, AI, automation — drawn from your free-to-spend balance) and FIXED recurring per-resource monthly commitments blocked out of it; see `billing commitments`.")
+        .description("Plan and managed credit commands. Spend splits into FLEXIBLE (ad-hoc: enrichment, AI, automation — drawn from your free-to-spend balance) and FIXED recurring per-resource monthly commitments blocked out of it; see `billing commitments`. THREE CLOCKS, deliberately different: the CREDIT CYCLE that `billing allowance` reports against (your plan's monthly grant window); each resource's own COMMITMENT RENEWAL, anchored to the day you connected it, so `billing commitments --json` next_due_at rarely matches the cycle end; and your SUBSCRIPTION PERIOD in `billing balance` (annual plans span many credit cycles). A number from one clock will not reconcile against another. Failed-payment grace, suspension, and recovery: https://oxygen-agent.com/docs/safety/billing.")
         .addCommand(new Command("change")
         .description("Preview an upgrade or downgrade and return a Stripe confirmation link. Nothing changes until confirmed in Stripe.")
         .requiredOption("--to <tier>", "Target plan: starter, pro, or team.")
@@ -7120,19 +7481,19 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         }));
     }))
         .addCommand(new Command("balance")
-        .description("Show the current plan and managed credit balance: available and reserved credits, FIXED credits committed to recurring per-resource charges, and the FLEXIBLE free-to-spend remainder. Credits are Oxygen's native unit; the plan's price and $-per-credit are at https://oxygen-agent.com/billing.")
+        .description("Show the current plan, subscription entitlement, and managed credit balance: available and reserved credits, FIXED credits committed to recurring per-resource charges, and the FLEXIBLE free-to-spend remainder. After failed-payment grace expires, mutations stop while read/export and billing recovery remain available. Recovery: https://oxygen-agent.com/billing. Policy: https://oxygen-agent.com/docs/safety/billing.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("billing balance", options, () => requestOxygen("/api/cli/billing/balance"));
     }))
         .addCommand(new Command("commitments")
-        .description("List the fixed monthly credit commitments blocked at your subscription renewal — per connected sending mailbox, OXYGEN-sold mailbox, warm-up, deliverability, and connected LinkedIn account — with unit price, quantity, and next-due date. Read-only, 0 Oxygen credits.")
+        .description("List the fixed monthly credit commitments blocked at your subscription renewal — per connected sending mailbox, OXYGEN-sold mailbox, warm-up, deliverability, and connected LinkedIn account — with unit price, quantity, and next-due date. This is the FORWARD run-rate: what your currently-connected resources will cost at their next renewal. It is NOT this cycle's charges — compare `billing allowance` fixed_spent_credits for that, and expect the two to differ. Each resource renews on its OWN anchor (the day it was connected), so next_due_at is per-resource and rarely lines up with the credit cycle. Read-only, 0 Oxygen credits.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("billing commitments", options, () => requestOxygen("/api/cli/billing/commitments"));
     }))
         .addCommand(new Command("allowance")
-        .description("Show this billing cycle's credit pool as one breakdown: fixed spend, flexible spend, credits committed to the next renewal, and what is free to spend — the numbers behind the bar on the credit-usage page. The parts always sum to the total. Read-only, 0 Oxygen credits.")
+        .description("Show this billing cycle's credit pool as one breakdown: fixed spend, flexible spend, credits committed to the next renewal, and what is free to spend — the numbers behind the bar on the credit-usage page. The parts always sum to the total. fixed_spent_credits is what has ALREADY been charged this cycle, NOT your monthly run-rate — for the forward figure billed at the next renewal see `billing commitments`, which is normally much larger. reserved_credits is in-flight spend already carved out of free_to_spend_credits, so treat free_to_spend as the ceiling and free_to_spend minus reserved as what is genuinely uncommitted. Every segment carries region=fixed|flexible. Read-only, 0 Oxygen credits.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("billing allowance", options, () => requestOxygen("/api/cli/billing/allowance"));
@@ -7504,6 +7865,19 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
     program
         .command("admin")
         .description("Staff-only commands.")
+        .addCommand(new Command("kpis")
+        .description("Show company acquisition with self-reported signup-channel attribution, signup-to-CLI/MCP activation, matured seven-day trial conversion, positive-paid MRR/ARR, and paid churn separated from trial loss. OXYGEN staff only; workspace admin role alone does not grant access.")
+        .addOption(new Option("--range <range>", "Range for acquisition, actor-and-surface-tracked activation, seven-day trial cohorts, and churn; current MRR/ARR and scheduled cancellations remain point-in-time.")
+        .choices(["7d", "30d", "90d"])
+        .default("30d"))
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("admin kpis", options, () => {
+            const range = readOption(options.range);
+            const suffix = range && range !== "30d" ? `?range=${encodeURIComponent(range)}` : "";
+            return requestOxygen(`/api/cli/admin/kpis${suffix}`);
+        });
+    }))
         .addCommand(new Command("costs")
         .description("Show provider costs (COGS) per workspace. Staff only.")
         .option("--top <n>", "Limit number of workspace columns. Defaults to all.")
@@ -8394,10 +8768,11 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .command("tools")
         .description("Tool catalog commands.")
         .addCommand(new Command("search")
-        .description("Search the tool catalog. A response listing partial_sources means an optional catalog source timed out and totals may be understated — rerun for the complete catalog.")
+        .description("Search a bounded, compact provider-operation catalog; hydrate one result with tools get. A response listing partial_sources means an optional catalog source timed out and totals may be understated — rerun for the complete catalog.")
         .argument("[query]", "Search text.")
-        .option("--verbosity <verbosity>", "minimal, summary, or full. Defaults to summary. Use minimal for high-fanout discovery sweeps that need to stay under the MCP token budget.")
+        .option("--verbosity <verbosity>", "minimal, summary, or full. Defaults to minimal; hydrate one result with tools get.")
         .option("--terse", "Alias for --verbosity minimal.")
+        .option("--all", "Return the complete matching catalog. Explicit because the default is bounded to 10.")
         .option("--only-runnable", "Only return tools runnable by the active organization.")
         .option("--workflow-eligible", "Only return tools a hosted workflow step may call, each annotated with the canonical `workflow_effect` its manifest step must declare. This is a narrower set than the table-column catalog — use it when authoring a workflow manifest so lint cannot reject a tool at apply time.")
         .option("--no-access-check", "Skip per-tool availability checks for a fast complete-catalog listing. Tools are returned without availability info; pair with --terse for discovery sweeps.")
@@ -8413,6 +8788,8 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
             const verbosity = options.terse ? "minimal" : readOption(options.verbosity);
             if (verbosity)
                 params.set("verbosity", verbosity);
+            if (options.all)
+                params.set("all", "true");
             if (options.onlyRunnable)
                 params.set("only_runnable", "true");
             if (options.workflowEligible)
@@ -9377,7 +9754,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     })));
     program.addCommand(new Command("engagement")
-        .description("Harvest a LinkedIn post's engagers (reactors + commenters) into an enrollable workspace table. The harvest runs as a slow, durable background drip under a dedicated conservative read budget — it never bursts and never starves the sequencer's own reads.")
+        .description("Capture LinkedIn intent from one known post (harvest needs its public URL or the composite social_id from `oxygen posts get`) or from your connected account's viewers, followers, and connections. For recurring competitor-profile monitoring that discovers future posts, start with `oxygen recipes list competitor --json`. Harvests run as a slow, durable drip under a conservative read budget.")
         .addCommand(new Command("harvest")
         .description("Start (or re-arm) a harvest of a post's engagers into a workspace table you can enroll into a sequence. Engagers drip into the table over many ticks; poll `engagement status` to watch it fill. No messages are sent. Cookieless harvests spend Oxygen credits per scraper page and require --max-credits.")
         .requiredOption("--post <social_id_or_url>", "Composite post social_id from `oxygen posts get` (NOT the activity URN), or the public LinkedIn post URL for cookieless.")
@@ -9493,6 +9870,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
     }))
         .addCommand(new Command("watch")
         .description("Declarative engagement watches (the signals wedge): stand up a watch on a post's engagers, 'who viewed my profile', or the sender's inbound network (new followers / new connections) that harvests people into a table and, under a standing approval, auto-enrolls them into a sequence. The watch materializes the harvest drip and enrolls newly-harvested people each cycle — the sequence still gates its own sends.")
+        .addHelpText("after", "\nScope: this watches one known post or one connected-account signal. For daily discovery across one or more public profiles' recent posts, use `oxygen blueprints describe linkedin-profile-engager-monitor --json`.\n")
         .addCommand(new Command("create")
         .description("Arm an engagement watch. `--kind post` watches a post's reactors + commenters (needs --post social_id; a cookieless post also needs --post-url); `--kind profile_viewers` watches 'who viewed my profile' (source unipile); `--kind followers` / `--kind connections` watch the sender's inbound network — people NEW to the org's orbit stream into the watch table as they follow/connect (source unipile, no credits, reads metered against the account's daily ingest budget). With --auto-enroll it enrolls harvested people into --sequence, capped by --max-enrolls-per-day — the inbound-led-outbound loop. --max-credits-per-cycle is the standing per-cycle spend cap (required for --auto-enroll and cookieless). No messages are sent by the watch itself.")
         .requiredOption("--kind <kind>", "post | profile_viewers | followers | connections.")
@@ -10578,24 +10956,57 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
             const suffix = params.toString();
             return requestOxygen(`/api/cli/sequences${suffix ? `?${suffix}` : ""}`);
         });
+    }))
+        .addCommand(new Command("send")
+        .description("Initiate one net-new LinkedIn message through a one-recipient, one-step hosted Sequence. First call without a sequence id: pass --recipient, --text/--text-file, and --sender to create the inert draft and preview (no message, no credits). After showing that preview, re-run with the returned sequence id plus --approved --max-credits N. Existing-thread replies stay in `oxygen inbox send`.")
+        .argument("[sequence]", "Sequence id returned by the preview call. Omit when creating the preview; required with --approved.")
+        .option("--recipient <url-or-id>", "LinkedIn personal-profile URL or provider member id. Preview call only.")
+        .option("--recipient-name <name>", "Optional display name stored on the enrollment. Preview call only.")
+        .option("--text <text>", "Message body. Preview call only; use either --text or --text-file.")
+        .option("--text-file <path>", "Read the message body from a file. Preview call only; use either --text-file or --text.")
+        .option("--sender <ref>", "Connected LinkedIn sender id, connection id, or Unipile account id. List choices with `oxygen senders list`.")
+        .option("--approved", "Approve the previewed Sequence for live dispatch. Requires the returned sequence id and --max-credits.")
+        .option("--max-credits <n>", "Positive credit ceiling for the live LinkedIn dispatch.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (sequence, options) => {
+        await handleAsyncAction("sequences send", options, () => {
+            const sequenceId = readOption(sequence);
+            const maxCredits = readPositiveNumber(options.maxCredits);
+            if (sequenceId) {
+                if (readOption(options.recipient) || readOption(options.recipientName) || readOption(options.text) || readOption(options.textFile) || readOption(options.sender)) {
+                    throw new OxygenError("conflicting_flags", "With a sequence id, pass only --approved and --max-credits; recipient, copy, and sender are fixed by the previewed draft.", { exitCode: 1 });
+                }
+                return requestOxygen("/api/cli/sequences/send", { method: "POST", body: { sequence: sequenceId, ...(options.approved ? { approved: true } : {}), ...(maxCredits !== undefined ? { max_credits: maxCredits } : {}) } });
+            }
+            if (options.approved)
+                throw new OxygenError("sequence_preview_required", "Preview first without --approved; then pass the returned sequence id with --approved --max-credits N.", { exitCode: 1 });
+            const recipient = readOption(options.recipient);
+            const sender = readOption(options.sender);
+            const text = readPublishingPostText(options, true);
+            if (!recipient)
+                throw new OxygenError("invalid_request", "--recipient is required for the preview call.", { exitCode: 1 });
+            if (!sender)
+                throw new OxygenError("invalid_request", "--sender is required for the preview call; list choices with `oxygen senders list`.", { exitCode: 1 });
+            return requestOxygen("/api/cli/sequences/send", { method: "POST", body: { recipient, text, sender, ...(readOption(options.recipientName) ? { recipient_name: readOption(options.recipientName) } : {}) } });
+        });
     }))
         .addCommand(new Command("workflows")
-        .description("Configure the sequencer's editable reply workflows: internal CRM routing and positive-reply Microsoft Teams notifications.")
+        .description("Compatibility-only maintenance for existing sequencer presets. Do not create new Teams notifications here: use `oxygen workflows` (web: Sequence → Launch → Connected workflows) with a sequence event trigger and Microsoft Teams Send Message.")
         .addCommand(new Command("list")
-        .description("List reply workflows with armed state, editable config, and workflow deep-links.")
+        .description("List the two legacy sequencer presets with armed state, editable config, and ordinary workflow deep-links.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("sequences workflows list", options, () => requestOxygen("/api/cli/sequencer/reply-workflows"));
     }))
         .addCommand(new Command("configure")
-        .description("Preview or save one editable reply workflow. Live arming requires --armed --approved and a positive per-delivery --max-credits cap; Microsoft Teams requires at least 20.02.")
-        .argument("<template>", "crm-lead-stage-router or sequencer-positive-reply-teams.")
+        .description("Preview or maintain an existing legacy preset. New Teams notifications must use an ordinary connected workflow; this command remains only for compatibility. Omit --live for a zero-write preview. Live arming requires --armed --approved and a positive per-delivery --max-credits cap.")
+        .argument("<template>", "crm-lead-stage-router or the legacy sequencer-positive-reply-teams preset (existing configurations only).")
         .option("--config-file <path>", "JSON object containing the managed workflow configuration.")
         .option("--armed", "Arm the workflow.")
         .option("--disarmed", "Disarm the workflow.")
         .option("--live", "Persist the configuration. Omit for a dry-run preview.")
         .option("--approved", "Explicitly approve standing authority for this exact workflow revision.")
-        .option("--max-credits <n>", "Hard per-delivery credit ceiling (Teams requires at least 20.02).")
+        .option("--max-credits <n>", "Hard per-delivery credit ceiling (the legacy Teams preset requires at least 0.02).")
         .option("--json", "Print a JSON envelope.")
         .action(async (template, options) => {
         await handleAsyncAction("sequences workflows configure", options, () => {
@@ -10624,15 +11035,15 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     })))
         .addCommand(new Command("hubspot-sync")
-        .description("Map actual sequencer events to contact datetime fields in the connected HubSpot portal. Event-driven and workspace-wide; no polling interval, direction, row batch, or operator credit-cap controls.")
+        .description("Map actual sequencer events to contact datetime fields in the connected HubSpot portal. Reuses native or provider-managed authorization and only requests known-missing property access if a preview needs new fields.")
         .addCommand(new Command("show")
-        .description("Fetch supported sequencer events, the connected portal's writable contact datetime fields, current mappings, and enabled state.")
+        .description("Show the connected portal and fetch its writable contact datetime fields, supported sequencer events, current mappings, and enabled state.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("sequences hubspot-sync show", options, () => requestOxygen("/api/cli/sequencer/hubspot-sync"));
     }))
         .addCommand(new Command("configure")
-        .description("Preview or save event → HubSpot property mappings. A live enable requires --approved after preview; missing recommended Oxygen properties are created on enable.")
+        .description("Preview or save event → HubSpot property mappings. Existing fields need no new grant; creating missing properties requires --approved and HubSpot property-creation access.")
         .option("--mappings-file <path>", "JSON object mapping every sequencer event key to a HubSpot contact datetime-property internal name; use an empty string to disable an event.")
         .option("--armed", "Enable future event delivery.")
         .option("--disarmed", "Disable future event delivery.")
@@ -11109,7 +11520,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
     program.addCommand(new Command("voice")
         .description("The call channel. `tasks` works the call queue — leads waiting for a HUMAN to dial, queued by sequence call steps, CRM records, table rows, and replies. Claiming takes a lease so two reps never dial the same prospect. Nothing here places a call: dialing is a separate, metered, guardrail-gated action. Consumes 0 credits.")
         .addCommand(new Command("tasks")
-        .description("Work the call queue: queue | list | claim | complete | skip | override.\n\nWhat blocks a dial, and what you can do about it:\n  calling_window     lead's local time outside 09:00-20:00      waivable per lead\n  unknown_timezone   no timezone on the lead, so the window\n                     cannot be checked (fails closed)          waivable per lead\n  daily_cap          the chosen number hit today's dial cap     waivable per lead\n  suppressed         on the workspace do-not-call list          NEVER waivable\n  destination_blocked your numbers cannot reach that country    NEVER waivable\n\n`list` reports dialable, block_reason and block_detail per lead, plus\ndialable_count and blocked_by_reason for the page. Waive one with `override`.")
+        .description("Work the call queue: queue | list | claim | complete | extend | skip | override.\n\nA call that nobody answers is dispositioned for you from the call itself, which\nalso resumes any sequence enrollment parked on it — so `complete` and `skip`\nreport already_recorded:true rather than failing when that has happened. You log\nonly what a person said.\n\nWhat blocks a dial, and what you can do about it:\n  calling_window     lead's local time outside 09:00-20:00      waivable per lead\n  unknown_timezone   no timezone on the lead, so the window\n                     cannot be checked (fails closed)          waivable per lead\n  daily_cap          the chosen number hit today's dial cap     waivable per lead\n  suppressed         on the workspace do-not-call list          NEVER waivable\n  destination_blocked your numbers cannot reach that country    NEVER waivable\n\n`list` reports dialable, block_reason and block_detail per lead, plus\ndialable_count and blocked_by_reason for the page. Waive one with `override`.")
         .addCommand(new Command("queue")
         .description("Put a lead INTO the call queue. Idempotent: a lead who already has an open task comes back with created:false rather than a duplicate, because the queue guarantees one open call per person. Queuing is not dialing — it writes a row a human later acts on. Consumes 0 credits.")
         .requiredOption("--phone <e164>", "The lead's number in E.164 (a leading + then 2-15 digits).")
@@ -11269,6 +11680,25 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
                 },
             });
         });
+    }))
+        .addCommand(new Command("extend")
+        .description("Renew a claimed task's 15-minute lease. Completing needs a live lease, so a longer call must heartbeat or its outcome and notes are rejected as stale.")
+        .requiredOption("--task <id>", "The claimed task's id.")
+        .requiredOption("--lease <token>", "The lease_token returned by `claim`.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("voice tasks extend", options, () => {
+            const task = readOption(options.task);
+            if (!task)
+                throw new Error("--task is required.");
+            const lease = readOption(options.lease);
+            if (!lease)
+                throw new Error("--lease is required.");
+            return requestOxygen("/api/cli/voice/tasks", {
+                method: "POST",
+                body: { action: "extend", task_id: task, lease_token: lease },
+            });
+        });
     }))
         .addCommand(new Command("skip")
         .description("Drop a task out of the queue without dialing (bad data, a rep pass, a guardrail block). Needs no lease — the guardrail gate skips tasks it never claimed.")
@@ -11567,7 +11997,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     })));
     program.addCommand(new Command("managed-inboxes")
-        .description("Whitelabel sending inboxes bought through OXYGEN: subscribe a domain + N mailboxes (google/microsoft/azure) as a recurring MONTHLY subscription billed in USD to your Oxygen Email Infrastructure subscription, list/get your subscriptions, verify that Oxygen/Stripe/the vendor agree, and cancel. Subscribe/cancel are approval-gated (preview → re-run with --approved --quote). The vendor is chosen for you; --vendor pins one.")
+        .description("Whitelabel sending inboxes bought through OXYGEN: subscribe a domain + N mailboxes (google/microsoft/azure) as a recurring MONTHLY subscription billed in USD to your Oxygen Email Infrastructure subscription, add-inboxes to a domain you already own, list/get your subscriptions, verify that Oxygen/Stripe/the vendor agree, and cancel. Subscribe/add-inboxes/cancel are approval-gated (preview → re-run with --approved --quote). The vendor is chosen for you; --vendor pins one.")
         .addCommand(new Command("verify")
         .description("Check that OXYGEN, STRIPE, and the VENDOR agree about what this org is buying. The truth about a managed inbox lives in three systems — what the customer asked for, what they are charged, and what is actually running — and a 200 from any one of them proves nothing. Reports every disagreement with WHO IS LOSING MONEY while it stands (customer_overbilled first, then oxygen_pays). Read-only, no writes, 0 Oxygen credits.")
         .option("--json", "Print a JSON envelope.")
@@ -11581,7 +12011,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         await handleAsyncAction("managed-inboxes registrant", options, () => requestOxygen("/api/cli/managed-inboxes/registrant"));
     }))
         .addCommand(new Command("subscribe")
-        .description("Subscribe a domain + mailboxes as a managed monthly inbox subscription. WITHOUT --approved this prints a priced PREVIEW with a quote_id (nothing ordered, nothing charged); re-run with --approved --quote <id> to place the order. Prices come from the vendor's LIVE rate card and LIVE domain price, and are refused if they sit below vendor cost. Fails closed until the vendor key + founder-signed per-platform pricing are configured.")
+        .description("Subscribe a NEW domain + mailboxes as a managed monthly inbox subscription. WITHOUT --approved this prints a priced PREVIEW with a quote_id (nothing ordered, nothing charged); re-run with --approved --quote <id> to place the order. Prices come from the vendor's LIVE rate card and LIVE domain price, and are refused if they sit below vendor cost. Fails closed until the vendor key + founder-signed per-platform pricing are configured. To add mailboxes to a domain you ALREADY own use `managed-inboxes add-inboxes` — this command always registers a new domain and fails on one you own.")
         .argument("[domain]", "Sending domain to register + host the mailboxes (e.g. send.acme.com). May also be passed as --domain.")
         .option("--domain <domain>", "Sending domain (alternative to the positional argument).")
         .requiredOption("--provider <provider>", "Mailbox PLATFORM: google, microsoft, or azure. (google/microsoft cap at 5 mailboxes per domain; azure allows 100.)")
@@ -11646,6 +12076,75 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
                 },
             });
         });
+    }))
+        .addCommand(new Command("add-inboxes")
+        .description("Add mailboxes to a managed domain you ALREADY own — no new domain is registered and there is NO domain registration charge, only the extra inboxes' monthly rate (plus their add-ons). WITHOUT --approved this prints a priced PREVIEW with a quote_id and orders nothing; re-run with --approved --quote <id> to place the order. Capped per domain by the platform the domain was bought on (5 google/microsoft, 100 azure) COUNTING the inboxes already on it. To register a NEW domain use `managed-inboxes subscribe` instead.")
+        .argument("[domain]", "A managed domain this workspace already owns (e.g. send.acme.com). May also be passed as --domain.")
+        .option("--domain <domain>", "The managed inbox domain (alternative to the positional argument).")
+        .option("--mailboxes <json>", "JSON array of mailboxes: [{\"username\",\"first_name\",\"last_name\"}]. The vendor stamps the names on each mailbox, so real names belong here.")
+        .option("--file <path>", "Path to a JSON file { \"mailboxes\": [...] } (alternative to --mailboxes).")
+        .option("--count <n>", "Shorthand for --mailboxes: how many inboxes to add. Requires --prefix.")
+        .option("--prefix <base>", "Shorthand username base for --count: `--count 3 --prefix ada` adds ada1, ada2, ada3 with placeholder names (Ada 1, Ada 2, Ada 3). Pass --mailboxes/--file instead when the inboxes need real human names.")
+        .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 (domainArg, options) => {
+        await handleAsyncAction("managed-inboxes add-inboxes", options, () => {
+            const domain = requireDomainArg(domainArg, options.domain);
+            let mailboxes;
+            const mailboxesJson = readOption(options.mailboxes);
+            const filePath = readOption(options.file);
+            const prefix = readOption(options.prefix);
+            const count = readPositiveInt(options.count);
+            if (mailboxesJson) {
+                mailboxes = JSON.parse(mailboxesJson);
+            }
+            else if (filePath) {
+                const parsed = readJsonFileValue(resolve(filePath), "--file");
+                mailboxes = parsed.mailboxes ?? [];
+            }
+            else if (count !== undefined || prefix) {
+                if (count === undefined || !prefix) {
+                    throw new Error("--count and --prefix must be passed together (e.g. --count 3 --prefix ada).");
+                }
+                // The vendor stamps a first/last name on every mailbox, so there is no
+                // name-less order shape to fall back on — the shorthand invents
+                // placeholders rather than pretending names are optional. Anyone who
+                // wants real human identities on the inboxes passes --mailboxes/--file.
+                const base = prefix.toLowerCase();
+                const label = `${base.charAt(0).toUpperCase()}${base.slice(1)}`;
+                mailboxes = Array.from({ length: count }, (_entry, index) => ({
+                    username: `${base}${index + 1}`,
+                    first_name: label,
+                    last_name: String(index + 1),
+                }));
+            }
+            else {
+                throw new Error("Provide --mailboxes <json>, --file <path>, or --count <n> --prefix <base>.");
+            }
+            const quote = readOption(options.quote);
+            // Refuse locally rather than spending a round trip on a PAID path: the
+            // route requires the quote that priced this exact expansion, so
+            // `--approved` alone can only ever come back as a 400.
+            if (options.approved && !quote) {
+                // Typed, not a bare Error: a bare throw surfaces as
+                // `unexpected_error`, which an agent cannot tell apart from a
+                // real failure on a PAID command. Refusing to order is an
+                // ordinary, expected outcome and must say so in its code.
+                throw new OxygenError("invalid_request", "--approved requires --quote <id> from a fresh preview. Re-run without --approved to get one.", { exitCode: 2 });
+            }
+            return requestOxygen(`/api/cli/managed-inboxes/${encodeURIComponent(domain)}/mailboxes`, {
+                method: "POST",
+                body: {
+                    // Always an explicit mailboxes[]: --count/--prefix is client-side
+                    // sugar, so the server sees exactly one shape and the preview it
+                    // prices is the list that gets ordered.
+                    mailboxes,
+                    ...(options.approved ? { approved: true } : {}),
+                    ...(quote ? { quote_id: quote } : {}),
+                },
+            });
+        });
     }))
         .addCommand(new Command("list")
         .description("List the org's managed inbox orders: vendor, platform, live inbox count, lifecycle status, internal billing posture, and each order's FULL monthly cost — the inbox line plus the warm-up and inbox-placement add-ons billing per inbox on top of it (`orders[].total_monthly_credits`, `total_monthly_credits` across the workspace). Read-only, 0 Oxygen credits.")
@@ -11697,9 +12196,9 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     })));
     program.addCommand(new Command("mailboxes")
-        .description("Native email sending pool: register/refresh Google/Microsoft mailboxes (including secure local Hypertide transfer), pause/disable inboxes, connect EmailGuard monitoring, and run managed TrulyInbox warmup with explicit plans and credit caps.")
+        .description("Native email sending pool: register/refresh Google/Microsoft mailboxes (including secure local Hypertide transfer), pause/disable inboxes, connect EmailGuard monitoring, and run managed TrulyInbox warmup with explicit plans and credit caps. Safe import preflight: run `oxygen mailboxes compatibility --catalog-only --json`, then `oxygen mailboxes import --file <path> --validate-only --json` (add the credential source flags shown by import help when the file contains credentials).")
         .addCommand(new Command("list")
-        .description("List the org's sending mailboxes with provider, status, warmup state, and a pool overview.")
+        .description("List the org's sending mailboxes with provider, status, warmup state, source (managed = bought through Oxygen, byok = bring-your-own), and a pool overview (including counts by source).")
         .option("--status <status>", "Filter by status: active, paused, or disabled.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
@@ -11713,7 +12212,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("get")
-        .description("Get one sending mailbox's detail (provider, status, daily cap, warmup state, auth mode) plus a one-row pool summary. An ineligible native-send transport includes transport_reason + transport_hint; it does not by itself block TrulyInbox warmup or EmailGuard monitoring. <mailbox> accepts a mailbox id or email address.")
+        .description("Get one sending mailbox's detail (provider, status, daily cap, warmup state, auth mode, and source — managed vs bring-your-own) plus a one-row pool summary. An ineligible native-send transport includes transport_reason + transport_hint; it does not by itself block TrulyInbox warmup or EmailGuard monitoring. <mailbox> accepts a mailbox id or email address.")
         .argument("<mailbox>", "Mailbox id or email address.")
         .option("--json", "Print a JSON envelope.")
         .action(async (mailbox, options) => {
@@ -11726,13 +12225,20 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         await handleAsyncAction("mailboxes health", options, () => requestOxygen("/api/cli/mailboxes/health"));
     }))
         .addCommand(new Command("compatibility")
-        .description("Read-only compatibility report for every selected mailbox: origin vendor, real infrastructure tier (including InboxKit Azure), mailbox auth, TrulyInbox warmup path, EmailGuard monitoring path, and the exact next action. JSON data.compatibility contains checked mailbox rows; data.provider_matrix always contains the complete current 13-pair product matrix even when mailboxes are filtered; data.summary rolls up states; data.web_url opens the pool. States distinguish credential_required, consent_required, and vendor_blocked. Never decrypts a credential or calls a downstream provider.")
+        .description("Read-only compatibility report for every selected mailbox: origin vendor, real infrastructure tier (including InboxKit Azure), OXYGEN native-send connection quality, TrulyInbox warmup path, EmailGuard monitoring path, and exact next actions. Native send distinguishes destination-bound OAuth, provider-managed API transport, admin delegation, and authorization_required. Use --catalog-only for the compact workspace-independent import contract. JSON data.compatibility contains checked rows; data.import_methods and data.import_fields describe accepted transfer inputs; data.provider_matrix is the complete current 18-pair product matrix; data.non_transferable_auth names credentials that must be reconnected; data.summary rolls up states; data.web_url opens the pool. Downstream states distinguish credential_required, consent_required, and vendor_blocked. Never decrypts a credential or calls a downstream provider.")
         .option("--mailboxes <list>", "Comma-separated mailbox ids or addresses. Omit for the whole pool.")
+        .option("--catalog-only", "Return only the bounded import-method, field, auth-boundary, and 18-pair provider catalogs; do not read or return workspace mailbox rows.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("mailboxes compatibility", options, () => {
             const mailboxes = readCsvOption(options.mailboxes);
+            if (options.catalogOnly === true && mailboxes.length > 0) {
+                throw new OxygenError("invalid_scope", "--catalog-only cannot be combined with --mailboxes.", { exitCode: 1 });
+            }
             const params = new URLSearchParams();
+            if (options.catalogOnly === true) {
+                params.set("catalog_only", "true");
+            }
             if (mailboxes.length > 0) {
                 params.set("mailboxes", mailboxes.join(","));
             }
@@ -11741,38 +12247,54 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("import")
-        .description("Register (or refresh) sending mailboxes in bulk. This is a 0-credit state mutation with no dry-run; the complete file is validated locally before the first request and the upsert is idempotent by mailbox address. Provide --file for identities, --from hypertide --file for a local secure CSV/JSON/JSONL/XLSX credential transfer, or --from zapmail to pull the connected workspace. A Hypertide app_password is Google-only: Microsoft password fields are discarded locally and Microsoft warmup uses Entra tenant-admin consent later; continuous EmailGuard monitoring remains vendor_blocked for Microsoft. Google passwords are sent only in the request body, encrypted server-side, and never returned.")
+        .description("Register (or refresh) sending mailboxes in bulk. Use --validate-only with a local file for a non-mutating, no-network preflight; without it, import is a 0-credit state mutation whose upsert is idempotent by mailbox address. CSV/JSON/JSONL/XLSX identity files from any vendor use --file plus optional --vendor. Compatible Google app-password exports use --from credentials --vendor <source>; --from hypertide remains a shortcut. Connected Zapmail inventories use --from zapmail. In credential files, app_password is Google-only; Microsoft password fields are discarded locally. OAuth grants, MFA/TOTP seeds, and delegation keys never transfer: Microsoft warmup requires Entra tenant-admin consent and EmailGuard remains vendor_blocked for Microsoft. Google app passwords are sent only in the request body, encrypted server-side, and never returned.")
         .addHelpText("after", [
         "",
-        "Ordinary identity file contract:",
-        '  JSON: [{"email_address":"ada@send-acme.com","provider":"google","workspace_external_id":"optional"}] or {"mailboxes":[...]}. Credentials are rejected.',
+        "Ordinary identity file contract (CSV / JSON / JSONL / XLSX):",
+        "  Canonical fields: email_address, provider, workspace_external_id?, infrastructure_platform?, tenant_id?. Common vendor aliases such as Email, From Email, ESP, Mailbox ID, and Entra Tenant ID are mapped locally. Credentials are rejected.",
         "",
-        "Hypertide file contract:",
-        "  Limits: 500 rows / 5 MB.",
+        "All local file imports:",
+        "  Limits: 500 rows / 5 MB for identity, credential, and Hypertide files.",
+        "",
+        "Credential file contract:",
         '  JSON: {"mailboxes":[{"email_address":"ada@send-acme.com","provider":"google","app_password":"<Google mailbox app password>"}]}',
-        "  Validation: any parse, shape, provider, or credential-conflict error rejects the entire file before the first mailbox write and names mailboxes[index]. A later infrastructure failure may interrupt the upsert; re-run the same file because import is idempotent by address.",
+        "  Only Google app passwords enter the encrypted seven-day transfer vault. Microsoft rows remain identity-only. Generic SMTP passwords and OAuth/MFA/delegation secrets are rejected.",
+        "  Validation: add --validate-only to parse the complete real file and return safe aggregate counts without authentication, a network request, or a workspace write. Any parse, shape, provider, platform, tenant, secret-policy, or duplicate-conflict error rejects the entire file before the first mailbox write and names mailboxes[index]; validation-only never writes. A later import infrastructure failure may interrupt the upsert; re-run the same file because import is idempotent by address.",
         "  Docs: https://oxygen-agent.com/docs/providers/mailbox-compatibility",
         "  Skill: oxygen-email-infra (`oxygen skills install --skill oxygen-email-infra`).",
         "",
     ].join("\n"))
-        .option("--file <path>", "Local JSON file for ordinary identity import. With --from hypertide, accepts the provider's CSV/JSON/JSONL/XLSX export and maps common Email Address, Provider, and App Password headers locally.")
-        .option("--from <source>", "Import source: 'hypertide' with --file for encrypted local credential transfer, or 'zapmail' to pull a connected workspace.")
+        .option("--file <path>", "Local CSV/JSON/JSONL/XLSX file. Common mailbox-vendor headers are normalized locally; only canonical allowlisted fields cross the network.")
+        .option("--from <source>", "Import source: 'credentials' for a compatible Google app-password export, 'hypertide' as its provider shortcut, or 'zapmail' to pull a connected workspace.")
+        .option("--vendor <slug>", "Non-secret source provenance (for example instantly, mailforge, or smartlead). Required with --from credentials; optional for identity files.")
         .option("--connection <id>", "Zapmail connection id (--from zapmail). Defaults to the org's active Zapmail connection.")
         .option("--provider <provider>", "Zapmail pool to pull (--from zapmail): google or microsoft. Zapmail's mailbox list is provider-scoped, so the Microsoft pool is only reachable with --provider microsoft; Microsoft mailboxes get their Entra tenant id stamped on import.")
+        .option("--validate-only", "Parse, normalize, and policy-check a local file, then return non-secret aggregate counts without authentication, network access, provider calls, or workspace writes.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("mailboxes import", options, async () => {
             const from = readOption(options.from);
             const filePath = readOption(options.file);
+            const vendor = readOption(options.vendor);
             const connection = readOption(options.connection);
             const provider = readOption(options.provider);
-            if (from && from !== "zapmail" && from !== "hypertide") {
-                throw new Error("--from must be hypertide or zapmail.");
+            const validateOnly = options.validateOnly === true;
+            if (from &&
+                from !== "zapmail" &&
+                from !== "hypertide" &&
+                from !== "credentials") {
+                throw new Error("--from must be credentials, hypertide, or zapmail.");
             }
             if (from === "zapmail") {
+                if (validateOnly) {
+                    throw new Error("--validate-only applies to local --file imports and cannot be combined with --from zapmail.");
+                }
                 if (filePath) {
                     throw new Error("--file cannot be combined with --from zapmail.");
                 }
+                if (vendor) {
+                    throw new Error("--vendor cannot be combined with --from zapmail; the connected integration is authoritative.");
+                }
                 return requestOxygen("/api/cli/mailboxes", {
                     method: "POST",
                     body: {
@@ -11784,13 +12306,36 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
             }
             if (provider)
                 throw new Error("--provider only applies with --from zapmail (inline files carry a per-mailbox provider).");
+            if (connection) {
+                throw new Error("--connection only applies with --from zapmail.");
+            }
+            const sourceProvider = normalizeMailboxImportVendor(vendor, from);
             if (!filePath)
-                throw new Error("Provide --file <path>, --from hypertide --file <path>, or --from zapmail.");
-            const mailboxes = normalizeMailboxImportFile(await readMailboxImportFile(resolve(filePath)), from === "hypertide" ? "hypertide" : "inline");
+                throw new Error("Provide --file <path>, --from credentials --vendor <source> --file <path>, --from hypertide --file <path>, or --from zapmail.");
+            const mailboxes = normalizeMailboxImportFile(await readMailboxImportFile(resolve(filePath)), from === "hypertide" || from === "credentials"
+                ? "credential"
+                : "identity");
+            if (validateOnly) {
+                return summarizeMailboxImportValidation(mailboxes, {
+                    source: from === "hypertide"
+                        ? "hypertide_file"
+                        : from === "credentials"
+                            ? "credential_file"
+                            : "identity_file",
+                    sourceProvider,
+                });
+            }
             return requestOxygen("/api/cli/mailboxes", {
                 method: "POST",
                 body: {
-                    ...(from === "hypertide" ? { source: "hypertide" } : {}),
+                    ...(from === "hypertide"
+                        ? { source: "hypertide" }
+                        : from === "credentials"
+                            ? { source: "credential_file" }
+                            : {}),
+                    ...(sourceProvider
+                        ? { source_provider: sourceProvider }
+                        : {}),
                     mailboxes,
                 },
             });
@@ -11913,40 +12458,60 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("connect-oauth")
-        .description("Zapmail-provisioned pools only — not Hypertide imports. Provision Zapmail Custom OAuth for Google/Microsoft mailboxes so native send needs no per-Workspace delegation. BYOK — Zapmail bills your account, 0 Oxygen credits. Pass --status <export_id> to poll.")
+        .description("Connect Google/Microsoft mailboxes to OXYGEN native send with fresh destination-bound OAuth. Preview by default; pass --approved only after reviewing exact candidates. --vendor oxygen handles imported, Hypertide, external, or manual mailboxes: it requires an exact list (max 10), returns one OXYGEN browser link per candidate, and stores a grant only after that exact mailbox completes provider consent/MFA. Source tokens, passwords, authenticator seeds, and one-time codes never transfer. --vendor zapmail (default) hands a provisioned pool to Zapmail Custom OAuth; --vendor inboxkit requests domain-gated consent with one canary on unproven domains and a 10-write live cap. All paths cost 0 Oxygen credits. Poll --status <id>; connected means an encrypted refresh token actually landed, never merely that a request was accepted.")
         .option("--provider <provider>", "Mailbox provider to provision: google or microsoft.")
-        .option("--mailboxes <list>", "Comma-separated mailbox addresses to provision. Omit to provision the whole pool for the provider.")
+        .option("--vendor <vendor>", "Authorization path: oxygen for imported/manual mailboxes, zapmail (default), or inboxkit.")
+        .option("--mailboxes <list>", "Comma-separated mailbox addresses. Required for vendor=oxygen (max 10); omit for vendor-provisioned whole-pool flows.")
+        .option("--domains <list>", "Comma-separated sending domains to limit an inboxkit run to. Omit to cover every domain in the pool.")
+        .option("--no-canary", "inboxkit only: fan out to every eligible mailbox on a domain that has never connected one, instead of firing a single canary first.")
         .option("--connection <id>", "Zapmail connection id. Defaults to the org's active Zapmail connection.")
-        .option("--status <export_id>", "Poll a previously started Custom OAuth export instead of starting a new one.")
+        .option("--status <id>", "Poll a previously started Zapmail, InboxKit, or OXYGEN direct-consent run.")
+        .option("--dry-run", "Preview the requested mailbox/domain scope and external writes without changing vendor or ledger state. This is the default for starts; a successful preview can still have zero eligible mailboxes, so check InboxKit candidates with oauth-health before approval.")
+        .option("--approved", "Start the reviewed authorization run. For vendor=oxygen this records expiring browser steps; provider consent still occurs only when the user opens each link.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("mailboxes connect-oauth", options, () => {
+            const vendor = readOption(options.vendor);
             const exportId = readOption(options.status);
             if (exportId) {
                 const params = new URLSearchParams({ export_id: exportId });
                 const pollConnection = readOption(options.connection);
                 if (pollConnection)
                     params.set("connection_id", pollConnection);
+                // Omitted, the server reads the vendor off the id's shape (numeric
+                // export id vs run uuid); this is the override for the rare id that
+                // does not look like either.
+                if (vendor)
+                    params.set("vendor", vendor);
                 return requestOxygen(`/api/cli/mailboxes/connect-oauth?${params.toString()}`);
             }
             const provider = readOption(options.provider);
             if (!provider) {
-                throw new Error("--provider <google|microsoft> is required (or pass --status <export_id> to poll a run).");
+                throw new Error("--provider <google|microsoft> is required (or pass --status <id> to poll a run).");
             }
             const mailboxes = readCsvOption(options.mailboxes);
+            const domains = readCsvOption(options.domains);
             const connection = readOption(options.connection);
             return requestOxygen("/api/cli/mailboxes/connect-oauth", {
                 method: "POST",
                 body: {
                     provider,
+                    // Every key stays absent unless it was asked for, so a run
+                    // without the new flags is the request this command has always
+                    // sent — the server reads an absent vendor as zapmail.
+                    ...(vendor ? { vendor } : {}),
                     ...(mailboxes.length > 0 ? { mailboxes } : {}),
+                    ...(domains.length > 0 ? { domains } : {}),
+                    ...(options.canary === false ? { canary: false } : {}),
                     ...(connection ? { connection_id: connection } : {}),
+                    ...(options.dryRun ? { dry_run: true } : {}),
+                    ...(options.approved ? { approved: true } : {}),
                 },
             });
         });
     }))
         .addCommand(new Command("oauth-health")
-        .description("Show the delegation-stuck sending mailboxes: Zapmail-linked google inboxes still on auth_mode=delegation with no OAuth grant, each with its Custom OAuth budget (attempts in the last 7 days, remaining re-export posts before Zapmail's 3-per-mailbox-per-7-day cap, last error, and next safe retry time). Read-only — 0 Oxygen credits.")
+        .description("Show every Google/Microsoft inbox with neither a per-mailbox OAuth token nor covered Google delegation. Remedies are connect_oauth for Zapmail, connect_oauth_inboxkit for InboxKit, and connect_oauth_oxygen for imported/manual mailboxes. Zapmail rows include their 3-per-7-day export budget; OXYGEN direct rows require exact browser consent and may invoke provider MFA. Read-only — 0 Oxygen credits.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("mailboxes oauth-health", options, () => requestOxygen("/api/cli/mailboxes/oauth-health"));
@@ -12774,7 +13339,7 @@ Run completion:
         .description("Deprecated alias for `oxygen blueprints apply`. Creates a disabled workflow (plus its tables, columns, and prompts) from a blueprint.")
         .argument("<template_id>", "Blueprint slug (formerly workflow template id).")
         .requiredOption("--input-json <json>", "Blueprint input as a JSON object.")
-        .option("--workflow-id <workflow_id>", "Override the resulting workflow id.")
+        .option("--workflow-id <workflow_id>", "Set the new workflow's manifest id/slug; this does not update or reuse an existing workflow.")
         .option("--workflow-name <workflow_name>", "Override the resulting workflow name.")
         .option("--mode <mode>", "Deprecated and ignored: the workflow is created disabled.")
         .option("--max-credits <credits>", "Credit ceiling; folded into inputs.max_credits.")
@@ -12876,7 +13441,8 @@ Run completion:
                 params.set("tag", tag);
             const qs = params.toString() ? `?${params.toString()}` : "";
             const data = await requestOxygen(`/api/cli/workflows${qs}`);
-            writeDisabledWorkflowNotices(data);
+            if (!options.json)
+                writeDisabledWorkflowNotices(data);
             return data;
         });
     }))
@@ -12891,7 +13457,8 @@ Run completion:
                 method: "POST",
                 body: { workflow },
             });
-            writeDisabledWorkflowNotices(data);
+            if (!options.json)
+                writeDisabledWorkflowNotices(data);
             return prepareWorkflowCliOutput(data, options);
         });
     }))
@@ -13386,11 +13953,28 @@ Run completion:
         .command("skills")
         .description("Agent skill discovery and installation commands.")
         .addCommand(new Command("list")
-        .description("List Oxygen agent skills available from the public skill index.")
+        .description("List Oxygen agent skills available from the hosted skill index.")
         .option("--api-url <url>", "Oxygen app URL. Defaults to OXYGEN_API_URL or https://oxygen-agent.com.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("skills list", options, () => listAgentSkills(options));
+    }))
+        .addCommand(new Command("search")
+        .description("Find a bounded set of Oxygen skills and matching documents from an outcome.")
+        .argument("<query...>", "Outcome, primitive, provider, or operating task.")
+        .option("--limit <n>", "Maximum results (default 5, max 10).")
+        .option("--api-url <url>", "Oxygen app URL. Defaults to OXYGEN_API_URL or https://oxygen-agent.com.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (queryParts, options) => {
+        await handleAsyncAction("skills search", options, () => searchAgentSkills(queryParts.join(" "), options));
+    }))
+        .addCommand(new Command("get")
+        .description("Hydrate one exact Oxygen skill entrypoint and its document index.")
+        .argument("<skill-name>", "Exact name returned by skills search.")
+        .option("--api-url <url>", "Oxygen app URL. Defaults to OXYGEN_API_URL or https://oxygen-agent.com.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (skillName, options) => {
+        await handleAsyncAction("skills get", options, () => getAgentSkill(skillName, options));
     }))
         .addCommand(new Command("doctor")
         .description("Check Oxygen skill index reachability and local installer prerequisites.")
@@ -13400,7 +13984,7 @@ Run completion:
         await handleAsyncAction("skills doctor", options, () => doctorAgentSkills(options));
     }))
         .addCommand(new Command("install")
-        .description("Install Oxygen agent skills into local agent skill directories.")
+        .description("Install Oxygen agent skills into local agent skill directories only; uses 0 credits and does not change the Oxygen workspace or call a provider.")
         .option("--api-url <url>", "Oxygen app URL. Defaults to OXYGEN_API_URL or https://oxygen-agent.com.")
         .option("--agents <agents...>", "Space or comma separated agents. Defaults to codex, claude-code, and cursor.")
         .option("--skill <skill>", "Skill name or '*'. Defaults to '*'.")