@oxygen-agent/cli 1.1014.135 → 1.1014.618

package/dist/commands/publishing.js

@@ -0,0 +1,1419 @@
+import { asPayloadRecord } from "../cli-output.js";
+import { parseJsonObject, readNonNegativeInt, readPositiveInt, readRecordString } from "../cli-values.js";
+import { collectRepeatable, readFileIfPresent, readPositiveNumber, readPublishingPostText, readPublishingTextFile, splitCommaList } from "../command-support.js";
+import { addContractFlags, readContractFlags } from "../contract-flags.js";
+import { requestOxygen } from "../http-client.js";
+import { defaultApiUrl } from "../credentials.js";
+import { oxygenDocsUrl } from "../help.js";
+import { isRecord, readOption } from "../util.js";
+import { OxygenError } from "@oxygen/shared/cli-result";
+import { publishingAmplificationListQueryContract, publishingAmplificationActionsQueryContract, publishingNotesQueryContract, publishingRevisionsQueryContract, publishingAnalyticsQueryContract, publishingReadQueryParams } from "@oxygen/shared/contracts/publishing-reads";
+import { Command } from "commander";
+function buildPublishingPostsListPath(options) {
+    const query = new URLSearchParams();
+    const filters = {
+        status: options.status,
+        approval_status: options.approvalStatus,
+        tag: options.tag,
+        provider: options.provider,
+        sender_account_id: options.sender,
+        cursor: options.cursor,
+        limit: options.limit,
+        order: options.order,
+    };
+    for (const [key, value] of Object.entries(filters)) {
+        const read = readOption(value);
+        if (read)
+            query.set(key, read);
+    }
+    const suffix = query.toString();
+    return suffix ? `/api/cli/publishing/posts?${suffix}` : "/api/cli/publishing/posts";
+}
+function buildPublishingMentionsResolveBody(options) {
+    const text = readPublishingPostText(options, false);
+    const identifiers = (options.identifier ?? [])
+        .map((value) => readOption(value))
+        .filter((value) => Boolean(value));
+    const kind = readOption(options.kind);
+    if (kind && kind !== "person" && kind !== "company") {
+        throw new OxygenError("invalid_request", "--kind must be person or company.", { exitCode: 1 });
+    }
+    if (!text && identifiers.length === 0) {
+        throw new OxygenError("invalid_request", "Pass --text/--text-file or at least one --identifier.", { exitCode: 1 });
+    }
+    const source = readOption(options.source);
+    if (source && source !== "sender" && source !== "scraper") {
+        throw new OxygenError("invalid_request", "--source must be sender or scraper.", { exitCode: 1 });
+    }
+    if ((source ?? "sender") === "sender" && !readOption(options.account)) {
+        throw new OxygenError("invalid_request", "--account is required when resolving through a sender.", { exitCode: 1 });
+    }
+    return {
+        ...(options.account ? { account: options.account } : {}),
+        ...(source ? { source } : {}),
+        ...(options.approved ? { approved: true } : {}),
+        ...(options.maxCredits ? { max_credits: Number(options.maxCredits) } : {}),
+        ...(text ? { text } : {}),
+        ...(identifiers.length > 0 ? {
+            identifiers: identifiers.map((value) => ({
+                value,
+                ...(kind ? { kind } : {}),
+                ...(options.asMention ? { as_mention: true } : {}),
+            })),
+        } : {}),
+    };
+}
+function buildPublishingPostCreateBody(options) {
+    const status = resolvePublishingCreateStatus(options);
+    const body = {
+        content_text: readPublishingPostText(options, true),
+        publish_at: options.publishAt,
+        status,
+        approved: options.approved === true,
+    };
+    const sender = readOption(options.sender);
+    const provider = readOption(options.provider);
+    const channel = readOption(options.channel);
+    const providerConnection = readOption(options.providerConnection);
+    const title = readOption(options.title);
+    const timezone = readOption(options.timezone);
+    const ugcParticipationId = readOption(options.ugcParticipationId);
+    const idempotencyKey = readOption(options.idempotencyKey);
+    const content = buildPublishingContent(options);
+    if (provider)
+        body.provider = provider;
+    if (channel)
+        body.channel = channel;
+    if (sender)
+        body.sender_account_id = sender;
+    if (providerConnection)
+        body.provider_connection_id = providerConnection;
+    if (title)
+        body.title = title;
+    if (timezone)
+        body.timezone = timezone;
+    if (idempotencyKey)
+        body.idempotency_key = idempotencyKey;
+    if (options.tags !== undefined)
+        body.tags = splitCommaList(options.tags);
+    if (ugcParticipationId) {
+        if (options.approved) {
+            throw new OxygenError("ugc_draft_required", "A program-bound personal post must be saved unapproved. Remove --approved, then review it in Publishing → UGC.", { exitCode: 1 });
+        }
+        body.ugc_participation_id = ugcParticipationId;
+    }
+    const xContent = buildPublishingXContent(options, { forMerge: false });
+    const firstComment = readPublishingFirstComment(options);
+    if (content || xContent || firstComment) {
+        body.content = { ...(content ?? {}), ...(xContent ?? {}), ...(firstComment ? { first_comment: firstComment } : {}) };
+    }
+    return body;
+}
+/**
+ * `--first-comment` / `--clear-first-comment`: the comment to set, null to remove
+ * it (update only), or undefined when neither flag was passed. The API refuses a
+ * first comment on a provider that cannot post one (publishing_first_comment_unsupported),
+ * judging the post's stored provider too, so the CLI does not keep its own list.
+ */
+function readPublishingFirstComment(options) {
+    if (options.firstComment !== undefined && options.clearFirstComment) {
+        throw new OxygenError("invalid_request", "Choose --first-comment or --clear-first-comment, not both.", { exitCode: 2 });
+    }
+    if (options.clearFirstComment)
+        return null;
+    if (options.firstComment === undefined)
+        return undefined;
+    const text = options.firstComment.trim();
+    if (!text) {
+        throw new OxygenError("invalid_request", "--first-comment needs the comment text. To remove a post's first comment, use --clear-first-comment on `publishing posts update`.", { exitCode: 2 });
+    }
+    return text;
+}
+/**
+ * The X flags as content keys (see the API's X content contract). On update they
+ * become a `content_merge` so the rest of the stored content is kept; there
+ * `--reply-settings everyone` removes the key.
+ */
+function buildPublishingXContent(options, mode) {
+    const content = {};
+    const threadPosts = options.threadPost ?? [];
+    const threadMedia = parseKeyedPairs(options.threadMedia ?? [], "--thread-media", "position=media_id");
+    if (threadMedia.length > 0 && threadPosts.length === 0) {
+        throw new OxygenError("invalid_request", "--thread-media needs the thread's posts: add --thread-post for each post after the first.", { exitCode: 2 });
+    }
+    if (threadPosts.length > 0) {
+        const thread = threadPosts.map((text) => ({ text }));
+        for (const [position, mediaId] of threadMedia) {
+            const index = Number(position) - 2;
+            if (!Number.isInteger(index) || index < 0 || index >= thread.length) {
+                throw new OxygenError("invalid_request", `--thread-media ${position}=... names no thread post; positions run 2 to ${thread.length + 1}.`, { exitCode: 2 });
+            }
+            const entry = thread[index];
+            entry.media_asset_ids = [...(entry.media_asset_ids ?? []), mediaId];
+        }
+        content.thread = thread;
+    }
+    const pollOptions = options.pollOption ?? [];
+    const pollDuration = readOption(options.pollDuration);
+    if (pollDuration && pollOptions.length === 0) {
+        throw new OxygenError("invalid_request", "--poll-duration needs the poll's options: add --poll-option 2-4 times.", { exitCode: 2 });
+    }
+    if (pollOptions.length > 0) {
+        content.poll = { options: pollOptions, duration_minutes: pollDuration ? parsePollDurationMinutes(pollDuration) : 1440 };
+    }
+    const replySettings = readOption(options.replySettings);
+    if (replySettings) {
+        const map = { everyone: null, following: "following", mentioned: "mentionedUsers", subscribers: "subscribers" };
+        if (!(replySettings in map)) {
+            throw new OxygenError("invalid_request", "--reply-settings must be everyone, following, mentioned, or subscribers.", { exitCode: 2 });
+        }
+        const value = map[replySettings];
+        if (value)
+            content.reply_settings = value;
+        else if (mode.forMerge)
+            content.reply_settings = null;
+    }
+    const altText = parseKeyedPairs(options.altText ?? [], "--alt-text", "media_id=text");
+    if (altText.length > 0)
+        content.media_alt_text = Object.fromEntries(altText);
+    const photoTags = (options.photoTag ?? []).map((name) => name.trim().replace(/^@/, "")).filter(Boolean);
+    if (photoTags.length > 0)
+        content.media_tagged_usernames = photoTags;
+    return Object.keys(content).length > 0 ? content : null;
+}
+/** `key=value` pairs from a repeatable flag; the value may itself contain `=`. */
+function parseKeyedPairs(entries, flag, shape) {
+    return entries.map((entry) => {
+        const at = entry.indexOf("=");
+        const key = at > 0 ? entry.slice(0, at).trim() : "";
+        const value = at > 0 ? entry.slice(at + 1) : "";
+        if (!key || !value.trim()) {
+            throw new OxygenError("invalid_request", `${flag} takes ${shape}.`, { exitCode: 2 });
+        }
+        return [key, value];
+    });
+}
+/** `30m`, `6h`, `2d`, or a bare number of minutes. */
+function parsePollDurationMinutes(value) {
+    const match = /^(\d+)\s*([mhd]?)$/i.exec(value.trim());
+    if (!match) {
+        throw new OxygenError("invalid_request", "--poll-duration takes a number of minutes or 30m, 6h, 2d.", { exitCode: 2 });
+    }
+    const unit = match[2].toLowerCase();
+    return Number(match[1]) * (unit === "d" ? 1440 : unit === "h" ? 60 : 1);
+}
+function buildPublishingPostUpdateBody(options) {
+    const body = {};
+    const sender = readOption(options.sender);
+    const provider = readOption(options.provider);
+    const channel = readOption(options.channel);
+    const providerConnection = readOption(options.providerConnection);
+    const title = readOption(options.title);
+    const text = readPublishingPostText(options, false);
+    const publishAt = readOption(options.publishAt);
+    const timezone = readOption(options.timezone);
+    const status = readOption(options.status);
+    const content = buildPublishingContent(options);
+    if (provider)
+        body.provider = provider;
+    if (channel)
+        body.channel = channel;
+    if (sender)
+        body.sender_account_id = sender;
+    if (providerConnection)
+        body.provider_connection_id = providerConnection;
+    if (title)
+        body.title = title;
+    if (text !== null)
+        body.content_text = text;
+    if (publishAt)
+        body.publish_at = publishAt;
+    if (timezone)
+        body.timezone = timezone;
+    if (status)
+        body.status = status;
+    if (content)
+        body.content = content;
+    const merge = readOption(options.contentMergeJson);
+    const xContent = buildPublishingXContent(options, { forMerge: true });
+    // A merge key, so the post's media and other content survive the change.
+    const firstComment = readPublishingFirstComment(options);
+    if (merge || xContent || firstComment !== undefined) {
+        body.content_merge = {
+            ...(merge ? parseJsonObject(merge) : {}),
+            ...(xContent ?? {}),
+            // Clearing also nulls the legacy camelCase key the worker still falls back to.
+            ...(firstComment === null ? { first_comment: null, firstComment: null } : {}),
+            ...(typeof firstComment === "string" ? { first_comment: firstComment } : {}),
+        };
+    }
+    if (options.confirmNotPublished)
+        body.confirm_not_published = true;
+    return body;
+}
+/**
+ * The LinkedIn video cover flags: a media id, a local file uploaded first, or
+ * (update only) a clear. Sent as the top-level `video_thumbnail_media_asset_id`,
+ * which the server merges into content, so the post's attachments are untouched.
+ */
+async function withPublishingVideoThumbnailOption(body, options) {
+    const mediaId = readOption(options.videoThumbnail);
+    const filePath = readOption(options.videoThumbnailFile);
+    const chosen = [mediaId, filePath, options.clearVideoThumbnail ? "clear" : undefined].filter(Boolean);
+    if (chosen.length > 1) {
+        throw new OxygenError("invalid_request", "Choose one of --video-thumbnail, --video-thumbnail-file, or --clear-video-thumbnail.", { exitCode: 2 });
+    }
+    if (options.clearVideoThumbnail)
+        return { ...body, video_thumbnail_media_asset_id: null };
+    if (mediaId)
+        return { ...body, video_thumbnail_media_asset_id: mediaId };
+    if (!filePath)
+        return body;
+    const contentType = publishingMediaContentTypeForPath(filePath);
+    if (contentType !== "image/jpeg" && contentType !== "image/png") {
+        throw new OxygenError("invalid_request", "--video-thumbnail-file must be a .jpg, .jpeg, or .png image.", { exitCode: 2 });
+    }
+    const uploaded = await uploadPublishingMediaFile(filePath, { contentType, scheduledPostId: null });
+    const media = uploaded.media && typeof uploaded.media === "object" ? uploaded.media : {};
+    const id = readRecordString(media, "id");
+    if (!id)
+        throw new OxygenError("publishing_media_upload_failed", "The cover image uploaded but no media id came back.", { exitCode: 1 });
+    return { ...body, video_thumbnail_media_asset_id: id };
+}
+/** Extension → MIME for the types Publishing accepts; anything else needs --content-type. */
+function publishingMediaContentTypeForPath(path) {
+    const extension = path.toLowerCase().split(".").pop() ?? "";
+    const types = {
+        jpg: "image/jpeg", jpeg: "image/jpeg", png: "image/png", gif: "image/gif", webp: "image/webp",
+        mp4: "video/mp4", m4v: "video/x-m4v", mov: "video/quicktime", webm: "video/webm",
+        pdf: "application/pdf",
+    };
+    return types[extension] ?? null;
+}
+/**
+ * Presign, PUT the file straight to object storage, then have the server verify
+ * it — the three hops the web composer makes. The body is a file-backed Blob, so
+ * a large video streams from disk instead of being read into memory.
+ */
+async function uploadPublishingMediaFile(filePath, options) {
+    const { openAsBlob } = await import("node:fs");
+    const { basename } = await import("node:path");
+    const contentType = options.contentType ?? publishingMediaContentTypeForPath(filePath);
+    if (!contentType) {
+        throw new OxygenError("invalid_request", "Could not tell the file type from its extension. Pass --content-type, such as video/mp4 or image/png.", { details: { path: filePath }, exitCode: 2 });
+    }
+    const file = await openAsBlob(filePath, { type: contentType });
+    const ticket = await requestOxygen("/api/cli/publishing/media/upload-url", {
+        method: "POST",
+        body: {
+            file_name: basename(filePath),
+            content_type: contentType,
+            byte_length: file.size,
+            ...(options.scheduledPostId ? { scheduled_post_id: options.scheduledPostId } : {}),
+        },
+    });
+    const uploadUrl = readRecordString(ticket, "upload_url");
+    const mediaId = isRecord(ticket.media) ? readRecordString(ticket.media, "id") : null;
+    if (!uploadUrl || !mediaId) {
+        throw new OxygenError("publishing_media_upload_failed", "The server did not return an upload URL and media ID for that file.", { exitCode: 1 });
+    }
+    const headers = ticket.upload_headers && typeof ticket.upload_headers === "object"
+        ? Object.fromEntries(Object.entries(ticket.upload_headers).map(([key, value]) => [key, String(value)]))
+        : { "content-type": contentType };
+    const put = await fetch(uploadUrl, { method: "PUT", headers, body: file, signal: AbortSignal.timeout(15 * 60_000) });
+    if (!put.ok) {
+        throw new OxygenError("publishing_media_upload_failed", `Object storage rejected the upload (${put.status}).`, { exitCode: 1 });
+    }
+    return await requestOxygen(`/api/cli/publishing/media/${encodeURIComponent(mediaId)}/uploaded`, { method: "POST", body: {} });
+}
+function buildPublishingMediaUploadUrlBody(options) {
+    const fileName = readOption(options.fileName);
+    const contentType = readOption(options.contentType);
+    const byteLength = readPositiveInt(options.byteLength);
+    if (!fileName) {
+        throw new OxygenError("invalid_request", "--file-name is required.", { exitCode: 1 });
+    }
+    if (!contentType) {
+        throw new OxygenError("invalid_request", "--content-type is required.", { exitCode: 1 });
+    }
+    if (!byteLength) {
+        throw new OxygenError("invalid_request", "--byte-length must be a positive integer.", { exitCode: 1 });
+    }
+    const body = {
+        file_name: fileName,
+        content_type: contentType,
+        byte_length: byteLength,
+    };
+    const scheduledPost = readOption(options.scheduledPost);
+    const metadataJson = readOption(options.metadataJson);
+    if (scheduledPost)
+        body.scheduled_post_id = scheduledPost;
+    if (metadataJson)
+        body.metadata = parseJsonObject(metadataJson);
+    return body;
+}
+function buildPublishingMediaUploadedBody(options) {
+    const sha256 = readOption(options.sha256);
+    return sha256 ? { sha256 } : {};
+}
+function buildPublishingContent(options) {
+    const contentJson = readOption(options.contentJson);
+    const composioAction = readOption(options.composioAction);
+    if (!contentJson && !composioAction)
+        return null;
+    const content = contentJson ? parseJsonObject(contentJson) : {};
+    if (composioAction) {
+        const existing = content.composio && typeof content.composio === "object" && !Array.isArray(content.composio)
+            ? content.composio
+            : {};
+        content.composio = { ...existing, action_slug: composioAction };
+    }
+    return content;
+}
+function resolvePublishingCreateStatus(options) {
+    const status = readOption(options.status);
+    if (readOption(options.ugcParticipationId)) {
+        if (status && status !== "draft") {
+            throw new OxygenError("ugc_draft_required", "--ugc-participation-id only creates an unapproved draft; omit --status or pass --status draft.", { exitCode: 1 });
+        }
+        return "draft";
+    }
+    if (options.draft === true && status && status !== "draft") {
+        throw new OxygenError("conflicting_flags", "Pass either --draft or --status, not both.", { exitCode: 1 });
+    }
+    return options.draft === true ? "draft" : status ?? "scheduled";
+}
+// --source-text / --source-file for the AI draft templates that rewrite a source
+// (summarize, repurpose, podcast_clip, hashtags). Mirrors readPublishingPostText.
+function readPublishingSourceText(options) {
+    const inlineText = readOption(options.sourceText);
+    const sourceFile = readOption(options.sourceFile);
+    if (inlineText && sourceFile) {
+        throw new OxygenError("conflicting_flags", "Pass either --source-text or --source-file, not both.", {
+            exitCode: 1,
+        });
+    }
+    if (sourceFile)
+        return readPublishingTextFile(sourceFile, "--source-file");
+    return inlineText?.trim() ? inlineText : null;
+}
+function buildPublishingPostsDraftBody(options) {
+    const body = {
+        template: options.template,
+        max_credits: readPositiveNumber(options.maxCredits),
+    };
+    const topic = readOption(options.topic);
+    const channels = readOption(options.channels);
+    const variants = readPositiveInt(options.variants);
+    const sourceText = readPublishingSourceText(options);
+    const sourceUrl = readOption(options.sourceUrl);
+    if (topic)
+        body.topic = topic;
+    if (channels) {
+        body.channels = channels.split(",").map((channel) => channel.trim()).filter(Boolean);
+    }
+    if (variants !== undefined)
+        body.variants = variants;
+    // Commander's --no-ground sets ground=false; the default (true) is the API's too,
+    // so only the explicit opt-out is worth sending.
+    if (options.ground === false)
+        body.ground = false;
+    if (sourceText)
+        body.source_text = sourceText;
+    if (sourceUrl)
+        body.source_url = sourceUrl;
+    return body;
+}
+function buildPublishingDraftsListPath(options) {
+    const query = new URLSearchParams();
+    const kind = readOption(options.kind);
+    const status = readOption(options.status);
+    const limit = readOption(options.limit);
+    if (kind)
+        query.set("kind", kind);
+    if (status)
+        query.set("status", status);
+    if (limit)
+        query.set("limit", limit);
+    const suffix = query.toString();
+    return suffix ? `/api/cli/publishing/drafts?${suffix}` : "/api/cli/publishing/drafts";
+}
+function buildPublishingDraftsAcceptBody(options) {
+    const body = {
+        variant_index: readNonNegativeInt(options.variant) ?? 0,
+    };
+    const publishAt = readOption(options.publishAt);
+    const channel = readOption(options.channel);
+    const sender = readOption(options.sender);
+    const providerConnection = readOption(options.providerConnection);
+    const timezone = readOption(options.timezone);
+    if (publishAt)
+        body.publish_at = publishAt;
+    if (channel)
+        body.channel = channel;
+    if (sender)
+        body.sender_account_id = sender;
+    if (providerConnection)
+        body.provider_connection_id = providerConnection;
+    if (timezone)
+        body.timezone = timezone;
+    return body;
+}
+function buildPublishingTagsBody(options) {
+    const add = splitCommaList(options.add);
+    const remove = splitCommaList(options.remove);
+    if (add.length === 0 && remove.length === 0) {
+        throw new OxygenError("invalid_request", "Pass --add and/or --remove.", { exitCode: 1 });
+    }
+    return {
+        ...(add.length > 0 ? { add } : {}),
+        ...(remove.length > 0 ? { remove } : {}),
+    };
+}
+// A list value goes out comma-separated (`accounts=a,b`), which every list param
+// in the publishing routes reads.
+function buildPublishingAnalyticsPath(base, params) {
+    const query = new URLSearchParams();
+    const lists = [];
+    for (const [key, value] of Object.entries(params)) {
+        if (typeof value === "string") {
+            if (value)
+                query.set(key, value);
+        }
+        else if (value && value.length > 0) {
+            lists.push(`${encodeURIComponent(key)}=${value.map(encodeURIComponent).join(",")}`);
+        }
+    }
+    const suffix = [query.toString(), ...lists].filter(Boolean).join("&");
+    return suffix ? `${base}?${suffix}` : base;
+}
+function publishingReadQueryPath(path, contract, options) {
+    const [base = path, existing] = path.split("?", 2);
+    const query = new URLSearchParams(existing);
+    for (const [key, value] of publishingReadQueryParams(contract, readContractFlags(options, contract)))
+        query.set(key, value);
+    return query.size ? `${base}?${query}` : base;
+}
+const PUBLISHING_ANALYTICS_ACCOUNT_HELP = "An account key from the summary's accounts list, or a LinkedIn sender id from `oxygen senders list`. Repeatable.";
+/** Repeated and/or comma-separated `--account` values, trimmed and de-duplicated. */
+function readPublishingAnalyticsAccounts(values) {
+    return [...new Set((values ?? []).flatMap((value) => splitCommaList(value)))];
+}
+// Content analytics sums every posting profile unless --account names some. When
+// more than one posted, the last line a human reads says how to see one of them;
+// stderr, so stdout stays the payload (the writeDryRunNotice split).
+function writePublishingAnalyticsAccountHint(data) {
+    const payload = asPayloadRecord(data);
+    const accounts = Array.isArray(payload?.accounts) ? payload.accounts : [];
+    const first = asPayloadRecord(accounts[0]);
+    if (accounts.length < 2 || typeof first?.key !== "string")
+        return;
+    const channel = asPayloadRecord(payload?.scope)?.channel;
+    const channelFlag = typeof channel === "string" && channel !== "linkedin" ? ` --channel ${channel}` : "";
+    const example = typeof first.name === "string" ? `, e.g. ${first.name}` : "";
+    process.stderr.write(`Totals combine ${accounts.length} accounts. Scope to one${example}: oxygen publishing analytics summary${channelFlag} --account ${first.key}\n`);
+}
+function buildPublishingCommentsListPath(options) {
+    const view = readOption(options.view);
+    const status = readOption(options.status);
+    if (view && status) {
+        throw new OxygenError("conflicting_flags", "Pass either --view or --status, not both.", { exitCode: 1 });
+    }
+    return buildPublishingAnalyticsPath("/api/cli/publishing/comments", {
+        view,
+        status,
+        post_id: readOption(options.post),
+        assignee: readOption(options.assignee),
+        channel: readOption(options.channel),
+        cursor: readOption(options.cursor),
+        limit: readOption(options.limit),
+    });
+}
+function readPublishingCommentText(text, file, label) {
+    if (readOption(text) && readOption(file)) {
+        throw new OxygenError("conflicting_flags", `Pass either --${label} or --${label}-file, not both.`, {
+            exitCode: 1,
+        });
+    }
+    const value = readOption(file)
+        ? readPublishingTextFile(readOption(file) ?? "", `--${label}-file`)
+        : readOption(text);
+    if (!value?.trim()) {
+        throw new OxygenError("invalid_request", `Pass --${label} or --${label}-file.`, { exitCode: 1 });
+    }
+    return value.trim();
+}
+// `--file` is the whole import: a .csv is posted verbatim as `csv` (the API owns
+// the parse, so the CLI and the web importer can never disagree about a quoted
+// comma); a .json is posted as `rows`. Dry-run is the DEFAULT — a bare
+// `publishing import --file posts.csv` lints and reports, and only --approved
+// flips dry_run off, so a bulk write into the queue is never one typo away.
+function buildPublishingImportBody(options) {
+    const file = readOption(options.file);
+    if (!file)
+        throw new OxygenError("invalid_request", "Pass --file <path.csv|.json>.", { exitCode: 1 });
+    if (options.dryRun === true && options.approved === true) {
+        throw new OxygenError("conflicting_flags", "Pass either --dry-run or --approved, not both.", { exitCode: 1 });
+    }
+    const contents = readPublishingTextFile(file, "--file");
+    const tags = splitCommaList(options.tags);
+    const isJson = file.trim().toLowerCase().endsWith(".json");
+    return {
+        ...(isJson ? { rows: readPublishingImportRows(contents) } : { csv: contents }),
+        dry_run: options.approved !== true,
+        ...(tags.length > 0 ? { tags } : {}),
+    };
+}
+function readPublishingImportRows(contents) {
+    let parsed;
+    try {
+        parsed = JSON.parse(contents);
+    }
+    catch {
+        throw new OxygenError("invalid_json", "--file is not valid JSON.", { exitCode: 1 });
+    }
+    if (Array.isArray(parsed))
+        return parsed;
+    const rows = parsed?.rows;
+    if (Array.isArray(rows))
+        return rows;
+    throw new OxygenError("invalid_request", "Expected a JSON array of rows, or an object with a `rows` array.", { exitCode: 1 });
+}
+// Amplification create and post boost both arm REAL public writes from other
+// people's connected accounts and both spend credits, so the CLI refuses (exit 7)
+// before the request rather than relying on the API to bounce it. Same gate the
+// LinkedIn `posts delete` path uses: an irreversible public action never happens
+// because a flag was forgotten.
+function requirePublishingApprovalAndCap(approved, maxCredits, action, details) {
+    if (approved !== true) {
+        throw new OxygenError("approval_required", `${action} makes real public engagement from the participants' connected accounts and spends credits. Re-run with --approved --max-credits <n>.`, { details, exitCode: 7 });
+    }
+    const cap = readPositiveNumber(maxCredits);
+    if (cap === undefined) {
+        throw new OxygenError("max_credits_required", `${action} spends credits, so it needs an explicit ceiling. Re-run with --max-credits <n>.`, { details, exitCode: 7 });
+    }
+    return cap;
+}
+/** The LinkedIn-restriction acknowledgement every arming amplification call needs. */
+function requireAmplificationRiskAcknowledged(acknowledged, action, details) {
+    if (acknowledged === true)
+        return;
+    throw new OxygenError("amplification_risk_acknowledgement_required", `${action} runs automated engagement from connected LinkedIn accounts, which LinkedIn may warn, restrict or close. Pacing reduces that risk but does not remove it. Re-run with --acknowledge-risk.`, { details: { ...details, risk_acknowledged: false }, exitCode: 7 });
+}
+function buildPublishingAmplificationCreateBody(options) {
+    const maxCredits = requirePublishingApprovalAndCap(options.approved, options.maxCredits, "Creating an amplification policy", { name: options.name, scope: options.scope });
+    requireAmplificationRiskAcknowledged(options.acknowledgeRisk, "Creating an amplification policy", { name: options.name, scope: options.scope });
+    const senders = splitCommaList(options.senders);
+    const actions = splitCommaList(options.actions);
+    if (senders.length === 0)
+        throw new OxygenError("invalid_request", "Pass --senders.", { exitCode: 1 });
+    if (actions.length === 0)
+        throw new OxygenError("invalid_request", "Pass --actions.", { exitCode: 1 });
+    return {
+        name: options.name,
+        scope_kind: options.scope,
+        participant_sender_ids: senders,
+        actions,
+        max_credits_per_cycle: maxCredits,
+        approved: true,
+        risk_acknowledged: true,
+        ...publishingAmplificationScope(options),
+        ...publishingAmplificationTunables(options),
+    };
+}
+function publishingAmplificationScope(options) {
+    const tag = readOption(options.tag);
+    const post = readOption(options.post);
+    return {
+        ...(tag ? { scope_tag: tag } : {}),
+        ...(post ? { scope_post_id: post } : {}),
+    };
+}
+function publishingAmplificationTunables(options) {
+    const maxActions = readPositiveInt(options.maxActionsPerPost);
+    const commentPool = readPublishingCommentPool(options);
+    const reactionMin = readNonNegativeInt(options.reactionDelayMin);
+    const reactionMax = readNonNegativeInt(options.reactionDelayMax);
+    const commentMin = readNonNegativeInt(options.commentDelayMin);
+    const commentMax = readNonNegativeInt(options.commentDelayMax);
+    return {
+        ...(options.metadataJson !== undefined ? { metadata: parseJsonObject(readFileIfPresent(options.metadataJson)) } : {}),
+        ...(maxActions !== undefined ? { max_actions_per_post: maxActions } : {}),
+        ...(commentPool ? { comment_source: "pool", comment_pool: commentPool } : {}),
+        ...(reactionMin !== undefined ? { reaction_delay_min_seconds: reactionMin } : {}),
+        ...(reactionMax !== undefined ? { reaction_delay_max_seconds: reactionMax } : {}),
+        ...(commentMin !== undefined ? { comment_delay_min_seconds: commentMin } : {}),
+        ...(commentMax !== undefined ? { comment_delay_max_seconds: commentMax } : {}),
+    };
+}
+// Comments are prose: a comma-separated flag would split them mid-sentence. The
+// pool is a repeatable --comment-pool flag, or a file of one comment per line.
+function readPublishingCommentPool(options) {
+    const file = readOption(options.commentPoolFile);
+    const inline = Array.isArray(options.commentPool)
+        ? options.commentPool.map((entry) => entry.trim()).filter(Boolean)
+        : [];
+    if (file && inline.length > 0) {
+        throw new OxygenError("conflicting_flags", "Pass either --comment-pool or --comment-pool-file, not both.", {
+            exitCode: 1,
+        });
+    }
+    if (file) {
+        const lines = readPublishingTextFile(file, "--comment-pool-file")
+            .split("\n")
+            .map((line) => line.trim())
+            .filter(Boolean);
+        if (lines.length === 0) {
+            throw new OxygenError("invalid_request", "--comment-pool-file has no comments.", { exitCode: 1 });
+        }
+        return lines;
+    }
+    return inline.length > 0 ? inline : null;
+}
+function buildPublishingAmplificationUpdateBody(options) {
+    const name = readOption(options.name);
+    const senders = splitCommaList(options.senders);
+    const actions = splitCommaList(options.actions);
+    const maxCredits = readPositiveNumber(options.maxCredits);
+    return {
+        ...(name ? { name } : {}),
+        ...(senders.length > 0 ? { participant_sender_ids: senders } : {}),
+        ...(actions.length > 0 ? { actions } : {}),
+        ...(maxCredits !== undefined ? { max_credits_per_cycle: maxCredits } : {}),
+        ...(options.acknowledgeRisk === true ? { risk_acknowledged: true } : {}),
+        ...publishingAmplificationTunables(options),
+    };
+}
+function buildPublishingBoostBody(postId, options) {
+    const maxCredits = requirePublishingApprovalAndCap(options.approved, options.maxCredits, "Boosting a post", { post_id: postId });
+    requireAmplificationRiskAcknowledged(options.acknowledgeRisk, "Boosting a post", {
+        post_id: postId,
+    });
+    const senders = splitCommaList(options.senders);
+    const actions = splitCommaList(options.actions);
+    if (senders.length === 0)
+        throw new OxygenError("invalid_request", "Pass --senders.", { exitCode: 1 });
+    if (actions.length === 0)
+        throw new OxygenError("invalid_request", "Pass --actions.", { exitCode: 1 });
+    const maxActions = readPositiveInt(options.maxActionsPerPost);
+    const commentPool = readPublishingCommentPool(options);
+    return {
+        ...(readOption(options.name) ? { name: readOption(options.name) } : {}),
+        senders,
+        actions,
+        max_credits: maxCredits,
+        approved: true,
+        risk_acknowledged: true,
+        ...(maxActions !== undefined ? { max_actions_per_post: maxActions } : {}),
+        ...(commentPool ? { comment_pool: commentPool } : {}),
+    };
+}
+function buildPublishingIdeaBody(options) {
+    const topic = readOption(options.topic);
+    const channels = splitCommaList(options.channels);
+    return {
+        kind: "idea",
+        text: readPublishingPostText(options, true),
+        ...(topic ? { topic } : {}),
+        ...(channels.length > 0 ? { channels } : {}),
+    };
+}
+export function registerPublishingFamily(program, handleAsyncAction) {
+    program
+        .command("publishing")
+        .description(`Social publishing, performance, and public-comment operations. Start Community triage with \`oxygen publishing comments list --view unanswered --json\`. Teammates engaging on the workspace's own posts is \`oxygen publishing amplification --help\` (created disabled; enabling needs --approved and --acknowledge-risk). Docs: ${oxygenDocsUrl(defaultApiUrl(), "/execution/publishing")}`)
+        .addCommand(new Command("mentions")
+        .description("Resolve LinkedIn identities for a publish-faithful post preview.")
+        .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; 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.")
+        .option("--text-file <path>", "Read post text from a local file.")
+        .option("--identifier <value...>", "Explicit provider id, public identifier, LinkedIn URL, or URN (repeat values after the flag).")
+        .option("--kind <kind>", "Type for explicit identifiers: person or company.")
+        .option("--as-mention", "Preview explicit identifiers as mentions instead of plain identity references.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("publishing mentions resolve", options, () => requestOxygen("/api/cli/publishing/mentions/resolve", {
+            method: "POST",
+            body: buildPublishingMentionsResolveBody(options),
+        }));
+    })))
+        .addCommand(new Command("posts")
+        .description("Manage scheduled Publishing posts.")
+        .addCommand(new Command("list")
+        .description("List scheduled posts by publish time, oldest first; pass --order newest for the latest first. Follow next_cursor for more than one page.")
+        .option("--status <status>", "Filter by draft, scheduled, queued, publishing, published, failed, or canceled.")
+        .option("--approval-status <status>", "Filter by draft, needs_approval, approved, or rejected.")
+        .option("--tag <tag>", "Only posts carrying this workspace tag.")
+        .option("--provider <provider>", "Filter by provider: linkedin, x, instagram, tiktok, facebook, or youtube.")
+        .option("--sender <sender_account_id>", "Only posts belonging to this connected sender in the active workspace.")
+        .option("--order <order>", "oldest (default) or newest publish time first.")
+        .option("--cursor <cursor>", "Continue from next_cursor with the same filters and order.")
+        .option("--limit <n>", "Maximum posts to return.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("publishing posts list", options, () => requestOxygen(buildPublishingPostsListPath(options)));
+    }))
+        .addCommand(new Command("create")
+        .description("Create a personal Publishing post. Use --ugc-participation-id to save it into one program as an unapproved draft; otherwise it defaults to scheduled and publishes only after approval.")
+        .requiredOption("--publish-at <iso>", "When the post publishes, e.g. 2026-10-06T09:00:00+02:00. With Z or an offset it is that exact instant; without one (2026-10-06T09:00) it is wall-clock time in --timezone.")
+        .option("--provider <provider>", "Publishing provider: linkedin, x, instagram, tiktok, facebook, or youtube. Defaults to linkedin. LinkedIn publishes through --sender; every other provider publishes through a connected account (--provider-connection), which the worker needs before it can deliver.")
+        .option("--channel <channel>", "Publishing channel override. Defaults to provider.")
+        .option("--sender <sender_account_id>", "LinkedIn sender account id. Required for LinkedIn before the worker can publish.")
+        .option("--provider-connection <connection_id>", "Oxygen integration connection id for Composio-backed providers. Find it with `integrations list` (each integration's connection); create one with `integrations connect <provider>` (an OAuth redirect URL, or Settings > Connections on the web).")
+        .option("--title <title>", "Internal title for the queue.")
+        .option("--text <text>", "Post text. On LinkedIn, tag a person with @<public-identifier> and a company page with @<handle> from its linkedin.com/company/<handle> URL.")
+        .option("--text-file <path>", "Read post text from a local file.")
+        .option("--content-json <json>", "Structured content. Use media_asset_ids for Oxygen uploads. LinkedIn attachments require [{content:<base64>,content_type:<MIME>,filename:<name>}]; content.mentions is rejected, so put verified @<public-identifier> values in --text. X options have their own flags (--thread-post, --poll-option, --reply-settings, --alt-text, --photo-tag); raw X API keys can still ride in composio.arguments.")
+        .option("--first-comment <text>", "Comment OXYGEN posts right after the post, e.g. the link (LinkedIn, X, Instagram, YouTube). Wins over first_comment in --content-json.")
+        .option("--composio-action <slug>", "Override the Composio action slug for this scheduled post.")
+        .option("--timezone <tz>", "IANA zone (Europe/Berlin) the post is shown in and a --publish-at without an offset is read in. Defaults to the LinkedIn sender's own timezone when --sender is set, else UTC.")
+        .option("--status <status>", "draft or scheduled. Defaults to scheduled. A draft sits outside the queue until `publishing posts approve` schedules and arms it in one step; scheduled is queued for its publish time and still waits for approval.")
+        .option("--draft", "Create as a draft instead of scheduled.")
+        .option("--ugc-participation-id <id>", "Also enroll this personal post in one active creator participation. It is always saved as an unapproved draft; omit --approved.")
+        .option("--approved", "Mark an ordinary post approved for the scheduler. Invalid with --ugc-participation-id.")
+        .option("--idempotency-key <key>", "Reuse one key when retrying the same post creation to avoid a duplicate.")
+        .option("--tags <csv>", "Workspace tags to attach to the new post.")
+        .option("--thread-post <text>", "X: text of the next post in a thread (posts 2, 3, ... in order). Repeatable.", collectRepeatable, [])
+        .option("--thread-media <position=media_id>", "X: attach an uploaded media id to thread post N (2 or later), e.g. 2=<media_id>. Repeatable.", collectRepeatable, [])
+        .option("--poll-option <text>", "X: a poll option on the first post (2-4 options, 25 characters each). Repeatable.", collectRepeatable, [])
+        .option("--poll-duration <duration>", "X: how long the poll runs, e.g. 30m, 6h, 2d (5 minutes to 7 days; default 1d).")
+        .option("--reply-settings <who>", "X: who can reply: everyone, following, mentioned, or subscribers.")
+        .option("--alt-text <media_id=text>", "X: image or GIF description for screen readers (up to 1,000 characters). Repeatable.", collectRepeatable, [])
+        .option("--photo-tag <username>", "X: tag an account in the first post's images (up to 10). Repeatable.", collectRepeatable, [])
+        .option("--video-thumbnail <media_id>", "LinkedIn video cover: an uploaded JPEG or PNG media id (`publishing media upload`). Needs a video in media_asset_ids.")
+        .option("--video-thumbnail-file <path>", "Upload a local JPEG or PNG and use it as the LinkedIn video cover.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("publishing posts create", options, async () => requestOxygen("/api/cli/publishing/posts", {
+            method: "POST",
+            body: await withPublishingVideoThumbnailOption(buildPublishingPostCreateBody(options), options),
+        }));
+    }))
+        .addCommand(new Command("get")
+        .description("Get one scheduled post with the sender account it publishes from (id, name, profile URL), resolved media previews, its LinkedIn video cover, and attempt history. For an X post, publish_plan lists every post that will be sent, in order, with media, alt text, poll and reply settings (free); for a LinkedIn post that tags a company page, it shows the text sent, each company tag as its page id, once `publishing posts approve` has resolved the tags (before approval it is absent). Open web_url to preview the post as it will look on LinkedIn or X.")
+        .argument("<post_id>", "Scheduled post id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (postId, options) => {
+        await handleAsyncAction("publishing posts get", options, () => requestOxygen(`/api/cli/publishing/posts/${encodeURIComponent(postId)}`));
+    }))
+        .addCommand(new Command("update")
+        .description("Update an editable draft, scheduled, or failed post. Content edits revoke approval. Text edits keep mention_previews. A cached repair must use the preview's existing verified publicIdentifier: update text, raw, identifier and offsets, preserving identity fields. For another company handle, resolve again; changing text cannot verify a different page.")
+        .argument("<post_id>", "Scheduled post id.")
+        .option("--provider <provider>", "Publishing provider: linkedin, x, instagram, tiktok, facebook, or youtube.")
+        .option("--channel <channel>", "Publishing channel override.")
+        .option("--sender <sender_account_id>", "LinkedIn sender account id.")
+        .option("--provider-connection <connection_id>", "Oxygen integration connection id for Composio-backed providers.")
+        .option("--title <title>", "Internal title for the queue.")
+        .option("--text <text>", "Post text. On LinkedIn, tag a person with @<public-identifier> and a company page with @<handle> from its linkedin.com/company/<handle> URL.")
+        .option("--text-file <path>", "Read post text from a local file.")
+        .option("--content-json <json>", "Structured content. Use media_asset_ids for Oxygen uploads. LinkedIn attachments require [{content:<base64>,content_type:<MIME>,filename:<name>}]; content.mentions is rejected, so put verified @<public-identifier> values in --text. This replaces the existing content object; use --content-merge-json or the X flags to change single keys.")
+        .option("--first-comment <text>", "Set the comment OXYGEN posts right after the post, keeping the rest of its content. Revokes approval on an approved post.")
+        .option("--clear-first-comment", "Remove the first comment. Revokes approval on an approved post.")
+        .option("--composio-action <slug>", "Override the Composio action slug for this scheduled post.")
+        .option("--publish-at <iso>", "When the post publishes. With Z or an offset it is that exact instant; without one it is wall-clock time in --timezone, else the post's own timezone.")
+        .option("--timezone <tz>", "IANA zone the post is shown in and a --publish-at without an offset is read in. Unchanged when omitted.")
+        .option("--status <status>", "draft or scheduled. Setting scheduled does not itself approve the post.")
+        .option("--thread-post <text>", "X: text of the next post in a thread (posts 2, 3, ... in order). Repeatable.", collectRepeatable, [])
+        .option("--thread-media <position=media_id>", "X: attach an uploaded media id to thread post N (2 or later), e.g. 2=<media_id>. Repeatable.", collectRepeatable, [])
+        .option("--poll-option <text>", "X: a poll option on the first post (2-4 options, 25 characters each). Repeatable.", collectRepeatable, [])
+        .option("--poll-duration <duration>", "X: how long the poll runs, e.g. 30m, 6h, 2d (5 minutes to 7 days; default 1d).")
+        .option("--reply-settings <who>", "X: who can reply: everyone, following, mentioned, or subscribers.")
+        .option("--alt-text <media_id=text>", "X: image or GIF description for screen readers (up to 1,000 characters). Repeatable.", collectRepeatable, [])
+        .option("--photo-tag <username>", "X: tag an account in the first post's images (up to 10). Repeatable.", collectRepeatable, [])
+        .option("--content-merge-json <json>", "Merge content keys; null removes a key, e.g. '{\"poll\":null}'. Arrays, including mention_previews, are replaced whole: carry every entry you want to keep.")
+        .option("--video-thumbnail <media_id>", "Set the LinkedIn video cover to an uploaded JPEG or PNG media id (`publishing media upload`). The post needs a video attached.")
+        .option("--video-thumbnail-file <path>", "Upload a local JPEG or PNG and set it as the LinkedIn video cover. To pick a frame from the video instead, open the post's web_url and use Cover.")
+        .option("--clear-video-thumbnail", "Remove the LinkedIn video cover.")
+        .option("--confirm-not-published", "Only after you checked the account: the post OXYGEN could not confirm is NOT there. Unlocks a post that failed with publishing_effect_outcome_uncertain; if the post is live, do not use it or it publishes twice.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (postId, options) => {
+        await handleAsyncAction("publishing posts update", options, async () => requestOxygen(`/api/cli/publishing/posts/${encodeURIComponent(postId)}`, {
+            method: "PATCH",
+            body: await withPublishingVideoThumbnailOption(buildPublishingPostUpdateBody(options), options),
+        }));
+    }))
+        .addCommand(new Command("approve")
+        .description("Approve a draft or scheduled post; drafts become scheduled for their saved publish time. Costs 0 credits. LinkedIn checks person handles and page IDs before arming. Current resolved previews with handle mismatches fail before lookups. Company handles are rechecked through the selected sender and server identity cache; free provider reads may be needed even with stored previews. Fix tags with `publishing posts update` and matching mention_previews. queued_at records first arming; publish_at controls publication. Program drafts require UGC approval.")
+        .argument("<post_id>", "Draft or scheduled post id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (postId, options) => {
+        await handleAsyncAction("publishing posts approve", options, () => requestOxygen(`/api/cli/publishing/posts/${encodeURIComponent(postId)}/approve`, {
+            method: "POST",
+        }));
+    }))
+        .addCommand(new Command("cancel")
+        .description("Cancel a draft, scheduled, queued, or failed post and revoke its approval. Use `publishing posts uncancel` to reopen it as an unapproved draft; approve it again before it can publish.")
+        .argument("<post_id>", "Scheduled post id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (postId, options) => {
+        await handleAsyncAction("publishing posts cancel", options, () => requestOxygen(`/api/cli/publishing/posts/${encodeURIComponent(postId)}/cancel`, {
+            method: "POST",
+        }));
+    }))
+        .addCommand(new Command("retry")
+        .description("Move a failed post back to scheduled for another worker attempt. A post that failed with publishing_effect_outcome_uncertain stays locked until you check the account and pass --confirm-not-published.")
+        .argument("<post_id>", "Scheduled post id.")
+        .option("--confirm-not-published", "Only after you checked the account: the post OXYGEN could not confirm is NOT there. Unlocks a post that failed with publishing_effect_outcome_uncertain; if the post is live, do not use it or it publishes twice.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (postId, options) => {
+        await handleAsyncAction("publishing posts retry", options, () => requestOxygen(`/api/cli/publishing/posts/${encodeURIComponent(postId)}/retry`, {
+            method: "POST",
+            ...(options.confirmNotPublished ? { body: { confirm_not_published: true } } : {}),
+        }));
+    }))
+        .addCommand(new Command("uncancel")
+        .description("Reopen a canceled post as an unapproved draft, keeping its publish time and its attempt history. Cancelling revoked approval, so approve it again to re-arm it for that time — approving a draft schedules and arms it in one step. This is cancel's inverse, NOT revision rollback: to roll the text back to an earlier revision use `publishing posts restore`.")
+        .argument("<post_id>", "Scheduled post id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (postId, options) => {
+        await handleAsyncAction("publishing posts uncancel", options, () => requestOxygen(`/api/cli/publishing/posts/${encodeURIComponent(postId)}/uncancel`, {
+            method: "POST",
+        }));
+    }))
+        .addCommand(new Command("delete")
+        .description("Permanently delete the OXYGEN copy and its settled history, keeping the live platform post intact. Supports never-attempted draft/scheduled/queued posts, settled canceled unpublished posts, and settled published copies. Published deletions stay excluded from background discovery. Cancel failed or re-armed posts first. In-flight publishing, replies, amplification, and active amplification spend accounting remain protected. Live LinkedIn deletion is a separate action using `oxygen posts delete`.")
+        .argument("<post_id>", "Scheduled post id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (postId, options) => {
+        await handleAsyncAction("publishing posts delete", options, () => requestOxygen(`/api/cli/publishing/posts/${encodeURIComponent(postId)}`, {
+            method: "DELETE",
+        }));
+    }))
+        .addCommand(new Command("draft")
+        .description("Draft posts with AI, grounded in the workspace Knowledge Graph. PAID (one AI call) — requires --max-credits. Writes drafts only: nothing is scheduled or published until you accept a draft and approve the post.")
+        .requiredOption("--template <key>", "Draft template: summarize, repurpose, changelog, feature_launch, case_study, personal_story, startup_advice, company_milestone, hiring, fundraise, hook_generator, popular_questions, tech_stack, podcast_clip, or hashtags.")
+        .requiredOption("--max-credits <n>", "Credit cap for the AI call (required — this is a paid action).")
+        .option("--topic <topic>", "What the post is about. Required by most templates.")
+        .option("--channels <list>", "Comma-separated target channels: linkedin, x, instagram, tiktok, facebook, youtube.")
+        .option("--variants <n>", "How many angles to draft (1-5). Defaults to 3.")
+        .option("--no-ground", "Skip Knowledge-Graph page retrieval. The canonical brand voice still applies.")
+        .option("--source-text <text>", "Source text for summarize, repurpose, podcast_clip, and hashtags.")
+        .option("--source-file <path>", "Read the source text from a local file.")
+        .option("--source-url <url>", "Source URL to reference.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("publishing posts draft", options, () => requestOxygen("/api/cli/publishing/posts/draft", {
+            method: "POST",
+            body: buildPublishingPostsDraftBody(options),
+        }));
+    }))
+        .addCommand(new Command("review")
+        .description("Pre-publish review of a post: deterministic channel lint (free, and blocking at approve) plus an AI voice/claims check against the Knowledge Graph. PAID (one AI call) — requires --max-credits. AI findings never block approval.")
+        .argument("<post_id>", "Scheduled post id.")
+        .requiredOption("--max-credits <n>", "Credit cap for the AI review call (required — this is a paid action).")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (postId, options) => {
+        await handleAsyncAction("publishing posts review", options, () => requestOxygen(`/api/cli/publishing/posts/${encodeURIComponent(postId)}/review`, {
+            method: "POST",
+            body: { max_credits: readPositiveNumber(options.maxCredits) },
+        }));
+    }))
+        .addCommand(new Command("boost")
+        .description("Boost ONE post: your teammates' connected accounts react to and comment on it, once. These are REAL public LinkedIn writes from their accounts and they SPEND CREDITS — refused (exit 7) without --approved, --max-credits and --acknowledge-risk. Creates a post-scoped policy that is already enabled and plans its actions immediately. For a standing rule across many posts, use `publishing amplification create`.")
+        .argument("<post_id>", "Scheduled post id.")
+        .option("--name <name>", "Name the post-scoped amplification policy.")
+        .requiredOption("--senders <ids>", "Comma-separated connected sender account ids that will engage.")
+        .requiredOption("--actions <list>", "Comma-separated actions: reaction, comment.")
+        .option("--max-actions-per-post <n>", "Hard cap on how many actions are planned (at most 12).")
+        .option("--max-credits <n>", "Credit ceiling for the boost (required — this is a paid action).")
+        .option("--comment-pool <text>", "A comment to draw from. Repeatable. Required when --actions includes comment.", collectRepeatable, [])
+        .option("--comment-pool-file <path>", "Read the comment pool from a file, one comment per line.")
+        .option("--approved", "Confirm the real public engagement. Without it the command refuses and nothing is planned.")
+        .option("--acknowledge-risk", "Acknowledge that LinkedIn may warn, restrict or close accounts used for automated engagement. Required.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (postId, options) => {
+        await handleAsyncAction("publishing posts boost", options, () => requestOxygen(`/api/cli/publishing/posts/${encodeURIComponent(postId)}/boost`, {
+            method: "POST",
+            body: buildPublishingBoostBody(postId, options),
+        }));
+    }))
+        .addCommand(addContractFlags(new Command("revisions"), publishingRevisionsQueryContract)
+        .description("List a post's content history: newest-first revisions with their number, title, text, author, and time.")
+        .argument("<post_id>", "Scheduled post id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (postId, options) => {
+        await handleAsyncAction("publishing posts revisions", options, () => requestOxygen(publishingReadQueryPath(`/api/cli/publishing/posts/${encodeURIComponent(postId)}/revisions`, publishingRevisionsQueryContract, options)));
+    }))
+        .addCommand(new Command("restore")
+        .description("Roll a post's TEXT back to an earlier revision (see `publishing posts revisions`). The current text is snapshotted as a new revision first, so a restore is itself undoable. Refused once the post is publishing, published, or canceled — to bring a canceled post back, use `publishing posts uncancel`.")
+        .argument("<post_id>", "Scheduled post id.")
+        .requiredOption("--revision <n>", "Revision number to restore.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (postId, options) => {
+        await handleAsyncAction("publishing posts restore", options, () => {
+            const revision = readPositiveInt(options.revision);
+            if (revision === undefined) {
+                throw new OxygenError("invalid_request", "Pass --revision <n>.", { exitCode: 1 });
+            }
+            return requestOxygen(`/api/cli/publishing/posts/${encodeURIComponent(postId)}/revisions/${revision}/restore`, { method: "POST" });
+        });
+    }))
+        .addCommand(addContractFlags(new Command("notes"), publishingNotesQueryContract)
+        .description("List the internal review notes on a post. Notes are workspace-only — they are never published.")
+        .argument("<post_id>", "Scheduled post id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (postId, options) => {
+        await handleAsyncAction("publishing posts notes", options, () => requestOxygen(publishingReadQueryPath(`/api/cli/publishing/posts/${encodeURIComponent(postId)}/comments`, publishingNotesQueryContract, options)));
+    }))
+        .addCommand(new Command("note")
+        .description("Leave an internal review note on a post, or reply to one with --parent. Never published.")
+        .argument("<post_id>", "Scheduled post id.")
+        .option("--text <text>", "The note.")
+        .option("--text-file <path>", "Read the note from a local file.")
+        .option("--parent <comment_id>", "Reply to this note.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (postId, options) => {
+        await handleAsyncAction("publishing posts note", options, () => {
+            const parent = readOption(options.parent);
+            return requestOxygen(`/api/cli/publishing/posts/${encodeURIComponent(postId)}/comments`, {
+                method: "POST",
+                body: {
+                    body: readPublishingPostText(options, true),
+                    ...(parent ? { parent_comment_id: parent } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("resolve-note")
+        .description("Resolve a review note, or reopen it.")
+        .argument("<post_id>", "Scheduled post id.")
+        .requiredOption("--comment <comment_id>", "Note id from `publishing posts notes`.")
+        .option("--reopen", "Reopen the review note instead of resolving it.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (postId, options) => {
+        await handleAsyncAction("publishing posts resolve-note", options, () => requestOxygen(`/api/cli/publishing/posts/${encodeURIComponent(postId)}/comments/${encodeURIComponent(options.comment)}/resolve`, { method: "POST", body: { resolved: options.reopen !== true } }));
+    })))
+        .addCommand(new Command("drafts")
+        .description("Review the AI post-draft queue before anything reaches the publish queue.")
+        .addCommand(new Command("list")
+        .description("List post drafts. Defaults to the open queue (queued + edited).")
+        .option("--kind <kind>", "Filter by ai or idea.")
+        .option("--status <list>", "Comma-separated statuses: queued, edited, accepted, rejected.")
+        .option("--limit <n>", "Maximum drafts to return.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("publishing drafts list", options, () => requestOxygen(buildPublishingDraftsListPath(options)));
+    }))
+        .addCommand(new Command("accept")
+        .description("Accept a draft variant into the publish queue. The post is created needs-approval — approve it separately before it can publish.")
+        .argument("<draft_id>", "Post draft id.")
+        .option("--variant <i>", "Which variant to accept (0-based). Defaults to 0.")
+        .option("--publish-at <iso>", "ISO date-time to schedule the post for; without an offset it is wall-clock time in --timezone. Defaults to now (still needs approval).")
+        .option("--channel <channel>", "Channel override. Defaults to the draft's first target channel.")
+        .option("--sender <sender_account_id>", "LinkedIn sender account id.")
+        .option("--provider-connection <connection_id>", "Oxygen integration connection id for Composio-backed providers.")
+        .option("--timezone <tz>", "IANA zone the post is shown in and a --publish-at without an offset is read in. Defaults to UTC.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (draftId, options) => {
+        await handleAsyncAction("publishing drafts accept", options, () => requestOxygen(`/api/cli/publishing/drafts/${encodeURIComponent(draftId)}/accept`, {
+            method: "POST",
+            body: buildPublishingDraftsAcceptBody(options),
+        }));
+    }))
+        .addCommand(new Command("reject")
+        .description("Reject a draft. The reason is filed to the Knowledge Graph so the next drafts learn from it.")
+        .argument("<draft_id>", "Post draft id.")
+        .option("--reason <reason>", "Why this draft was rejected.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (draftId, options) => {
+        await handleAsyncAction("publishing drafts reject", options, () => requestOxygen(`/api/cli/publishing/drafts/${encodeURIComponent(draftId)}/reject`, {
+            method: "POST",
+            body: readOption(options.reason) ? { reason: readOption(options.reason) } : {},
+        }));
+    }))
+        .addCommand(new Command("edit")
+        .description("Rewrite one variant's text. The first edit snapshots the AI's original copy, so accepting it teaches the Knowledge Graph what you changed.")
+        .argument("<draft_id>", "Post draft id.")
+        .option("--variant <i>", "Which variant to edit (0-based). Defaults to 0.")
+        .option("--text <text>", "The replacement post text.")
+        .option("--text-file <path>", "Read the replacement text from a local file.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (draftId, options) => {
+        await handleAsyncAction("publishing drafts edit", options, () => requestOxygen(`/api/cli/publishing/drafts/${encodeURIComponent(draftId)}`, {
+            method: "PATCH",
+            body: {
+                variant_index: readNonNegativeInt(options.variant) ?? 0,
+                text: readPublishingPostText(options, true),
+            },
+        }));
+    })))
+        .addCommand(new Command("media")
+        .description("Manage Publishing media uploads.")
+        .addCommand(new Command("upload")
+        .description("Upload a local image, video, or PDF in one step and print its media id. Attach it with --content-json '{\"media_asset_ids\":[...]}', or use a JPEG/PNG as a LinkedIn video cover with `publishing posts update --video-thumbnail`.")
+        .argument("<path>", "Local file path.")
+        .option("--content-type <type>", "MIME type when the file extension does not say it, such as video/mp4.")
+        .option("--scheduled-post <post_id>", "Optional provenance association; it does not attach the file to the post.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (filePath, options) => {
+        await handleAsyncAction("publishing media upload", options, () => uploadPublishingMediaFile(filePath, {
+            contentType: readOption(options.contentType) ?? null,
+            scheduledPostId: readOption(options.scheduledPost) ?? null,
+        }));
+    }))
+        .addCommand(new Command("upload-url")
+        .description("Create a Publishing media asset and presigned upload URL with required upload headers.")
+        .requiredOption("--file-name <name>", "Original media filename.")
+        .requiredOption("--content-type <type>", "Media MIME type, such as image/png or video/mp4; use the returned upload_headers for PUT.")
+        .requiredOption("--byte-length <bytes>", "Exact media byte length.")
+        .option("--scheduled-post <post_id>", "Optional provenance association; also set the post content.media_asset_ids to attach it.")
+        .option("--metadata-json <json>", "Optional metadata object to store with the media asset.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("publishing media upload-url", options, () => requestOxygen("/api/cli/publishing/media/upload-url", {
+            method: "POST",
+            body: buildPublishingMediaUploadUrlBody(options),
+        }));
+    }))
+        .addCommand(new Command("uploaded")
+        .description("Verify an uploaded Publishing media object and mark the media asset uploaded.")
+        .argument("<media_id>", "Publishing media asset id.")
+        .option("--sha256 <hex>", "Optional SHA-256 digest of the uploaded bytes.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (mediaId, options) => {
+        await handleAsyncAction("publishing media uploaded", options, () => requestOxygen(`/api/cli/publishing/media/${encodeURIComponent(mediaId)}/uploaded`, {
+            method: "POST",
+            body: buildPublishingMediaUploadedBody(options),
+        }));
+    })))
+        .addCommand(new Command("tags")
+        .description("Apply unified workspace tags to scheduled posts; tags are never published.")
+        .addCommand(new Command("set")
+        .description("Add and/or remove workspace tags on a post.")
+        .argument("<post_id>", "Scheduled post id.")
+        .option("--add <tags>", "Comma-separated workspace tags to add.")
+        .option("--remove <tags>", "Comma-separated workspace tags to remove.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (postId, options) => {
+        await handleAsyncAction("publishing tags set", options, () => requestOxygen(`/api/cli/publishing/posts/${encodeURIComponent(postId)}/tags`, {
+            method: "POST",
+            body: buildPublishingTagsBody(options),
+        }));
+    })))
+        .addCommand(new Command("comments")
+        .description("Publishing Community for public comments on every recent post owned by a connected LinkedIn account, including posts created directly on LinkedIn. Start with `oxygen publishing comments list --view unanswered --json`. These are network conversations, not workspace review notes. The local queue targets a six-hour background discovery + comment poll; provider quota/backoff can delay it. Read freshness, empty_queue_is_current and guidance before trusting an empty queue. automatic_retry_at reports a future retry; next_sync_at alone does not confirm one. An unconfirmed provider read can pause refresh; contact support when guidance says to. No manual retry is available. Queue reads use 0 credits and make no provider call; only explicit approval can post a public reply.")
+        .addCommand(new Command("list")
+        .description("List the Publishing Community work queue, oldest first, with polling freshness/backoff even when empty. Defaults to the Unanswered view: needs_reply, draft, awaiting_approval, and action_unavailable. All covers every lifecycle state on published owned posts within 30 days plus UGC-linked posts, not lifetime LinkedIn history. Completed coverage counts earlier successful polls and can overlap failed coverage after a later error. Read-only: no provider call, 0 credits.")
+        .option("--view <view>", "Community view: unanswered (default) or all; all is bounded to recent owned posts.")
+        .option("--status <status>", "Advanced exact-state filter: needs_reply, draft, awaiting_approval, replied, resolved, ignored, spam, or action_unavailable. Cannot be combined with --view.")
+        .option("--post <post_id>", "Only comments on one scheduled Publishing post.")
+        .option("--assignee <actor>", "Only one actor id; pass me for your own assignments.")
+        .option("--channel <channel>", "Social channel. Defaults to linkedin.")
+        .option("--cursor <cursor>", "Opaque next_cursor from the previous page.")
+        .option("--limit <n>", "Maximum comments (default 50; maximum 100). Counts, scope and freshness accompany every page; use 1 for a compact metadata read.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("publishing comments list", options, () => requestOxygen(buildPublishingCommentsListPath(options)));
+    }))
+        .addCommand(new Command("get")
+        .description("Get one stored public comment with its provider thread and immutable reply-action history. Read-only: no provider call, 0 credits.")
+        .argument("<comment_id>", "OXYGEN public comment id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (commentId, options) => {
+        await handleAsyncAction("publishing comments get", options, () => requestOxygen(`/api/cli/publishing/comments/${encodeURIComponent(commentId)}`));
+    }))
+        .addCommand(new Command("update")
+        .description("Save local draft, notes, assignment, or triage state. Nothing is posted publicly and no credits are used.")
+        .argument("<comment_id>", "OXYGEN public comment id.")
+        .option("--draft <text>", "Save a reply draft locally.")
+        .option("--draft-file <path>", "Read the local reply draft from a file.")
+        .option("--notes <text>", "Workspace-only operator notes.")
+        .option("--assignee <actor_id>", "Assign to a workspace actor id; pass an empty string to clear.")
+        .option("--status <status>", "Set needs_reply, draft, resolved, ignored, or spam.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (commentId, options) => {
+        await handleAsyncAction("publishing comments update", options, () => {
+            const hasDraft = Boolean(readOption(options.draft) || readOption(options.draftFile));
+            if (!hasDraft && options.notes === undefined && options.assignee === undefined && options.status === undefined) {
+                throw new OxygenError("invalid_request", "Pass --draft/--draft-file, --notes, --assignee, or --status.", { exitCode: 1 });
+            }
+            return requestOxygen(`/api/cli/publishing/comments/${encodeURIComponent(commentId)}`, {
+                method: "PATCH",
+                body: {
+                    ...(hasDraft
+                        ? { draft_body: readPublishingCommentText(options.draft, options.draftFile, "draft") }
+                        : {}),
+                    ...(options.notes !== undefined ? { notes: options.notes } : {}),
+                    ...(options.assignee !== undefined
+                        ? { assignee_actor_id: readOption(options.assignee) ?? null }
+                        : {}),
+                    ...(readOption(options.status) ? { status: readOption(options.status) } : {}),
+                },
+            });
+        });
+    }))
+        .addCommand(new Command("reply")
+        .description("Preview an exact public reply and return its action_id + content_hash. Makes no provider call, posts nothing, and uses 0 credits.")
+        .argument("<comment_id>", "OXYGEN public comment id.")
+        .option("--text <text>", "Reply text to preview.")
+        .option("--text-file <path>", "Read reply text from a file.")
+        .option("--idempotency-key <key>", "Stable key for safely recreating the same preview.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (commentId, options) => {
+        await handleAsyncAction("publishing comments reply preview", options, () => requestOxygen(`/api/cli/publishing/comments/${encodeURIComponent(commentId)}/reply-actions`, {
+            method: "POST",
+            body: {
+                body: readPublishingCommentText(options.text, options.textFile, "text"),
+                ...(readOption(options.idempotencyKey)
+                    ? { idempotency_key: readOption(options.idempotencyKey) }
+                    : {}),
+            },
+        }));
+    }))
+        .addCommand(new Command("approve")
+        .description("Post one exact previewed reply publicly. A REAL LinkedIn write; refused without --approved and the preview's content hash.")
+        .argument("<action_id>", "Reply action id returned by `publishing comments reply`.")
+        .requiredOption("--content-hash <sha256>", "Exact content_hash returned by the preview.")
+        .option("--approved", "Approve this exact public reply.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (actionId, options) => {
+        await handleAsyncAction("publishing comments reply approve", options, () => {
+            if (options.approved !== true) {
+                throw new OxygenError("approval_required", "Public replies require --approved after inspecting the exact preview.", { exitCode: 7 });
+            }
+            return requestOxygen(`/api/cli/publishing/comment-replies/${encodeURIComponent(actionId)}/approve`, {
+                method: "POST",
+                body: { content_hash: options.contentHash, approved: true },
+            });
+        });
+    }))
+        .addCommand(new Command("resolve")
+        .description("Resolve, ignore, mark spam, or reopen one local public-comment work item. No provider write, 0 credits.")
+        .argument("<comment_id>", "OXYGEN public comment id.")
+        .option("--resolution <status>", "resolved (default), ignored, spam, or needs_reply.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (commentId, options) => {
+        await handleAsyncAction("publishing comments resolve", options, () => requestOxygen(`/api/cli/publishing/comments/${encodeURIComponent(commentId)}/resolve`, {
+            method: "POST",
+            body: { resolution: readOption(options.resolution) ?? "resolved" },
+        }));
+    })))
+        .addCommand(new Command("analytics")
+        .description("Stored LinkedIn and X engagement snapshots synced in the background. LinkedIn includes owned posts discovered from the provider; X includes only posts published through OXYGEN. Reading analytics makes no provider call and uses 0 credits. A snapshotted post completed a sync pass; use per-metric coverage to see which values were populated. Null is unknown, never zero. Read freshness and guidance for delayed refresh; an unconfirmed provider read can pause it. No manual provider retry is available.")
+        .addCommand(new Command("summary")
+        .description("Workspace LinkedIn or X analytics. LinkedIn includes owned posts discovered from the provider; X currently includes posts published through OXYGEN. Uses each post's latest stored snapshot; snapshotted_posts (legacy measured_posts) counts sync passes, while coverage counts non-null values. Read-only: no provider call, 0 credits.")
+        .option("--channel <channel>", "Channel to summarize: linkedin (default) or x.")
+        .option("--range <range>", "Publication window: 7d, 30d (default), 90d, or 365d.")
+        .option("--from <date>", "Custom inclusive UTC start date.")
+        .option("--to <date>", "Custom inclusive UTC end date.")
+        .option("--limit <n>", "Top posts to return. Defaults to 10, maximum 50.")
+        .option("--sort <metric>", "Rank top posts by engagements (default; reactions + comments + reposts), impressions, reactions, comments, or reposts. `leader` reports the top post's lead over the runner-up and the median.")
+        .option("--account <key>", PUBLISHING_ANALYTICS_ACCOUNT_HELP, collectRepeatable, [])
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        const accounts = readPublishingAnalyticsAccounts(options.account);
+        let data;
+        await handleAsyncAction("publishing analytics summary", options, async () => {
+            data = await requestOxygen(buildPublishingAnalyticsPath("/api/cli/publishing/analytics/summary", {
+                channel: readOption(options.channel),
+                range: readOption(options.range),
+                from: readOption(options.from),
+                to: readOption(options.to),
+                limit: readOption(options.limit),
+                sort: readOption(options.sort),
+                accounts,
+            }));
+            return data;
+        });
+        if (!options.json && accounts.length === 0)
+            writePublishingAnalyticsAccountHint(data);
+    }))
+        .addCommand(new Command("timeseries")
+        .description("Impressions and engagements EARNED per day across all tracked posts (not only posts published in the range), with reactions, comments and reposts also reported on their own, whether each is growing or shrinking (against the previous period, or when tracking began inside the range, the second half of its tracked days against the first; `trend.basis` says which and `trend.compared` shows both values), and follower change per LinkedIn account. Days without a tracked post are null, never zero; `estimated` days spread a gain across an unread gap of up to three days. Read-only: no provider call, 0 credits.")
+        .option("--channel <channel>", "Channel: linkedin (default) or x.")
+        .option("--range <range>", "Window: 7d, 30d (default), 90d, or 365d.")
+        .option("--from <date>", "Custom inclusive start date.")
+        .option("--to <date>", "Custom inclusive end date.")
+        .option("--tz <zone>", "IANA time zone for day boundaries, e.g. Europe/Berlin. Defaults to UTC.")
+        .option("--account <key>", PUBLISHING_ANALYTICS_ACCOUNT_HELP, collectRepeatable, [])
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("publishing analytics timeseries", options, () => requestOxygen(buildPublishingAnalyticsPath("/api/cli/publishing/analytics/timeseries", {
+            channel: readOption(options.channel),
+            range: readOption(options.range),
+            from: readOption(options.from),
+            to: readOption(options.to),
+            tz: readOption(options.tz),
+            accounts: readPublishingAnalyticsAccounts(options.account),
+        })));
+    }))
+        .addCommand(addContractFlags(new Command("post"), publishingAnalyticsQueryContract)
+        .description("One post's stored daily metric series, totals, growth curve, 24h/7d benchmarks against the workspace median, and earned-media value. EMV is impressions-derived; absent impressions return a reason instead of a made-up number. Read-only: no provider call, 0 credits.")
+        .argument("<post_id>", "Scheduled post id.")
+        .option("--since <date>", "ISO date to start the series from.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (postId, options) => {
+        await handleAsyncAction("publishing analytics post", options, () => requestOxygen(publishingReadQueryPath(buildPublishingAnalyticsPath(`/api/cli/publishing/analytics/posts/${encodeURIComponent(postId)}`, { since: readOption(options.since) }), publishingAnalyticsQueryContract, options)));
+    }))
+        .addCommand(addContractFlags(new Command("account"), publishingAnalyticsQueryContract)
+        .description("Stored per-account metric series (followers) for connected LinkedIn and X publishing accounts, read once a day in the background. Each account reports its snapshot freshness; stale values remain available. Read-only: no provider call, 0 credits.")
+        .option("--provider <provider>", "Channel to read: linkedin or x. Omit for every connected channel.")
+        .option("--since <date>", "ISO date to start the series from.")
+        .option("--account <key>", PUBLISHING_ANALYTICS_ACCOUNT_HELP, collectRepeatable, [])
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("publishing analytics account", options, () => requestOxygen(publishingReadQueryPath(buildPublishingAnalyticsPath("/api/cli/publishing/analytics/account", {
+            provider: readOption(options.provider),
+            since: readOption(options.since),
+            accounts: readPublishingAnalyticsAccounts(options.account),
+        }), publishingAnalyticsQueryContract, options)));
+    }))
+        .addCommand(new Command("emv")
+        .description("Set the workspace CPM used for earned-media value, per channel. EMV stays null on any channel whose provider does not expose impressions.")
+        .requiredOption("--cpm-json <json>", "Per-channel CPM object, e.g. '{\"linkedin\":30,\"x\":12}'.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("publishing analytics emv", options, () => requestOxygen("/api/cli/publishing/analytics/emv", {
+            method: "POST",
+            body: { cpm: parseJsonObject(options.cpmJson ?? "") },
+        }));
+    }))
+        .addHelpText("after", "\nExamples (stored snapshots, 0 credits, no provider call):\n  oxygen publishing analytics summary --channel linkedin --range 30d --sort impressions --json\n  oxygen publishing analytics timeseries --channel linkedin --range 30d --tz Europe/Berlin --json\n\nTotals, leader and trends combine every posting account; `accounts` lists them and `--account <key>` counts only the ones you name. `top_posts[].account` names each post's author.\nWhy a metric is null: every null carries a reason in `null_reasons`:\n  not_exposed_by_provider   the rail OXYGEN currently reads through never returns it (`capabilities.metrics.<metric>.reason` names the limit)\n  not_synced_yet            no background snapshot has landed yet\n  not_returned_by_provider  snapshots exist but the provider left it out (LinkedIn shows impressions only to the post's author)\nSee also: the oxygen-publishing product skill (`oxygen skills get oxygen-publishing --file references/analytics.md`) for reading LinkedIn performance.\n"))
+        .addCommand(new Command("import")
+        .description("Bulk-load scheduled posts from a .csv or .json file. Dry-run by DEFAULT: it parses, lints, and reports invalid rows while writing nothing. Pass --approved to actually write. Imported posts land as drafts that still need approval — import never approves and never publishes. A row whose idempotency_key was already used is skipped, so re-importing the same file cannot duplicate the queue.")
+        .requiredOption("--file <path>", "Path to a .csv (header row) or .json file ([rows] or { rows: [...] }). Columns: content_text, publish_at, and optionally sender_account_id, provider, timezone, title, first_comment, tags, idempotency_key. A publish_at without Z or an offset is wall-clock time in the row's timezone, else its sender's, else UTC.")
+        .option("--dry-run", "Parse, lint, and report without writing. Default.")
+        .option("--approved", "Write the parsed rows into the queue as needs-approval drafts.")
+        .option("--tags <tags>", "Comma-separated workspace tags for every imported post.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("publishing import", options, () => requestOxygen("/api/cli/publishing/import", {
+            method: "POST",
+            body: buildPublishingImportBody(options),
+        }));
+    }))
+        .addCommand(new Command("amplification")
+        .description("Standing auto-engagement policies: the sender accounts you name react to and comment on every post in scope, paced and capped. Default OFF — a new policy is created disabled, and arming it is a separate, deliberate call.")
+        .addCommand(addContractFlags(new Command("list"), publishingAmplificationListQueryContract)
+        .description("List amplification policies with their scope, caps, and enabled state.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("publishing amplification list", options, () => requestOxygen(publishingReadQueryPath("/api/cli/publishing/amplification", publishingAmplificationListQueryContract, options)));
+    }))
+        .addCommand(new Command("create")
+        .description("Create an amplification policy. It arms REAL public engagement from other people's connected accounts and, once enabled, draws credits each cycle (creating it spends nothing), so it is refused (exit 7) without --approved, --max-credits and --acknowledge-risk — that grant is recorded with who/when/what scope. The policy is created DISABLED: run `amplification enable` when you actually want it to run.")
+        .requiredOption("--name <name>", "Policy name.")
+        .requiredOption("--scope <kind>", "What it amplifies: all, tag, or post.")
+        .option("--tag <tag>", "Workspace tag to scope to (with --scope tag).")
+        .option("--post <post_id>", "Post to scope to (with --scope post).")
+        .requiredOption("--senders <ids>", "Comma-separated connected sender account ids that will engage.")
+        .requiredOption("--actions <list>", "Comma-separated actions: reaction, comment.")
+        .option("--max-actions-per-post <n>", "Hard cap on actions per post (at most 12).")
+        .option("--max-credits <n>", "Hard credit cap per cycle (required — this policy spends credits).")
+        .option("--comment-pool <text>", "A comment to draw from. Repeatable. Required when --actions includes comment.", collectRepeatable, [])
+        .option("--comment-pool-file <path>", "Read the comment pool from a file, one comment per line.")
+        .option("--metadata-json <json-or-file>", "Policy metadata; {} clears it on update.")
+        .option("--reaction-delay-min <seconds>", "Lower bound of the randomized reaction delay.")
+        .option("--reaction-delay-max <seconds>", "Upper bound of the randomized reaction delay.")
+        .option("--comment-delay-min <seconds>", "Lower bound of the randomized comment delay.")
+        .option("--comment-delay-max <seconds>", "Upper bound of the randomized comment delay.")
+        .option("--approved", "Grant the standing permission. Without it the command refuses and creates nothing.")
+        .option("--acknowledge-risk", "Acknowledge that LinkedIn may warn, restrict or close accounts used for automated engagement. Required.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("publishing amplification create", options, () => requestOxygen("/api/cli/publishing/amplification", {
+            method: "POST",
+            body: buildPublishingAmplificationCreateBody(options),
+        }));
+    }))
+        .addCommand(new Command("get")
+        .description("Get one policy: scope, participants, caps, pacing, enabled state, and standing approval.")
+        .argument("<policy_id>", "Amplification policy id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (policyId, options) => {
+        await handleAsyncAction("publishing amplification get", options, () => requestOxygen(`/api/cli/publishing/amplification/${encodeURIComponent(policyId)}`));
+    }))
+        .addCommand(new Command("update")
+        .description("Update a policy's participants, actions, caps, or pacing. Tightening a cap takes effect on the next cycle.")
+        .argument("<policy_id>", "Amplification policy id.")
+        .option("--name <name>", "Policy name.")
+        .option("--senders <ids>", "Comma-separated connected sender account ids.")
+        .option("--actions <list>", "Comma-separated actions: reaction, comment.")
+        .option("--max-actions-per-post <n>", "Hard cap on actions per post (at most 12).")
+        .option("--max-credits <n>", "Hard credit cap per cycle.")
+        .option("--comment-pool <text>", "A comment to draw from. Repeatable.", collectRepeatable, [])
+        .option("--comment-pool-file <path>", "Read the comment pool from a file, one comment per line.")
+        .option("--metadata-json <json-or-file>", "Policy metadata; {} clears it on update.")
+        .option("--reaction-delay-min <seconds>", "Lower bound of the randomized reaction delay.")
+        .option("--reaction-delay-max <seconds>", "Upper bound of the randomized reaction delay.")
+        .option("--comment-delay-min <seconds>", "Lower bound of the randomized comment delay.")
+        .option("--comment-delay-max <seconds>", "Upper bound of the randomized comment delay.")
+        .option("--acknowledge-risk", "Record a fresh LinkedIn-restriction risk acknowledgement on the policy.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (policyId, options) => {
+        await handleAsyncAction("publishing amplification update", options, () => requestOxygen(`/api/cli/publishing/amplification/${encodeURIComponent(policyId)}`, {
+            method: "PATCH",
+            body: buildPublishingAmplificationUpdateBody(options),
+        }));
+    }))
+        .addCommand(new Command("enable")
+        .description("Arm a policy. From here the worker engages on every post in scope from the participants' real accounts, within the caps — so this refuses (exit 7) without --approved and --acknowledge-risk. Nothing else in the policy changes.")
+        .argument("<policy_id>", "Amplification policy id.")
+        .option("--approved", "Confirm arming the standing public engagement. Without it nothing is armed.")
+        .option("--acknowledge-risk", "Acknowledge that LinkedIn may warn, restrict or close accounts used for automated engagement. Required.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (policyId, options) => {
+        await handleAsyncAction("publishing amplification enable", options, () => {
+            if (options.approved !== true) {
+                throw new OxygenError("approval_required", "Enabling a policy starts real public engagement from the participants' connected accounts. Re-run with --approved.", { details: { policy_id: policyId }, exitCode: 7 });
+            }
+            requireAmplificationRiskAcknowledged(options.acknowledgeRisk, "Enabling a policy", {
+                policy_id: policyId,
+            });
+            return requestOxygen(`/api/cli/publishing/amplification/${encodeURIComponent(policyId)}/enable`, { method: "POST", body: { risk_acknowledged: true } });
+        });
+    }))
+        .addCommand(new Command("disable")
+        .description("Disarm a policy and skip every action it had already planned. Always allowed — the off switch is never gated.")
+        .argument("<policy_id>", "Amplification policy id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (policyId, options) => {
+        await handleAsyncAction("publishing amplification disable", options, () => requestOxygen(`/api/cli/publishing/amplification/${encodeURIComponent(policyId)}/disable`, {
+            method: "POST",
+        }));
+    }))
+        .addCommand(new Command("delete")
+        .description("Delete a policy.")
+        .argument("<policy_id>", "Amplification policy id.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (policyId, options) => {
+        await handleAsyncAction("publishing amplification delete", options, () => requestOxygen(`/api/cli/publishing/amplification/${encodeURIComponent(policyId)}`, {
+            method: "DELETE",
+        }));
+    }))
+        .addCommand(addContractFlags(new Command("actions"), publishingAmplificationActionsQueryContract)
+        .description("The policy's action ledger: what each participant account did (or is about to do) on which post, with status and cost.")
+        .argument("<policy_id>", "Amplification policy id.")
+        .option("--status <status>", "Filter by planned, dispatched, failed, or skipped.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (policyId, options) => {
+        await handleAsyncAction("publishing amplification actions", options, () => requestOxygen(publishingReadQueryPath(buildPublishingAnalyticsPath(`/api/cli/publishing/amplification/${encodeURIComponent(policyId)}/actions`, { status: readOption(options.status) }), publishingAmplificationActionsQueryContract, options)));
+    })))
+        .addCommand(new Command("ideas")
+        .description("The content backlog: ideas parked for later, with no publish time and no AI spend.")
+        .addCommand(new Command("add")
+        .description("File an idea into the backlog. Free — no AI call, nothing scheduled. Turn one into a post later with `publishing drafts accept --publish-at`.")
+        .option("--text <text>", "The idea.")
+        .option("--text-file <path>", "Read the idea from a local file.")
+        .option("--topic <topic>", "Optional topic tag.")
+        .option("--channels <list>", "Comma-separated channels this idea is meant for.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("publishing ideas add", options, () => requestOxygen("/api/cli/publishing/drafts", {
+            method: "POST",
+            body: buildPublishingIdeaBody(options),
+        }));
+    }))
+        .addCommand(new Command("list")
+        .description("List the idea backlog.")
+        .option("--limit <n>", "Maximum ideas to return.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("publishing ideas list", options, () => requestOxygen(buildPublishingDraftsListPath({ ...options, kind: "idea" })));
+    })));
+}