@oxygen-agent/cli 1.922.14 → 1.948.1

package/dist/ugc-commands.js

@@ -0,0 +1,1089 @@
+import { requestOxygen } from "./http-client.js";
+function parseField(value, field) {
+    if (field.kind === "array" || field.kind === "object") {
+        const parsed = JSON.parse(String(value));
+        if (field.kind === "array"
+            ? !Array.isArray(parsed) ||
+                !parsed.every((item) => typeof item === "string")
+            : !parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            throw new Error(`${field.name} must be a JSON ${field.kind === "array" ? "array of strings" : "object"}.`);
+        return parsed;
+    }
+    if (field.kind === "number") {
+        const parsed = Number(value);
+        if (!Number.isFinite(parsed) || parsed < 0)
+            throw new Error(`${field.name} must be a nonnegative finite number.`);
+        return parsed;
+    }
+    if (field.kind === "boolean") {
+        if (value === true || value === "true")
+            return true;
+        if (value === false || value === "false")
+            return false;
+        throw new Error(`${field.name} must be true or false.`);
+    }
+    return value;
+}
+export function registerUgcCommands(program, handle) {
+    const ugc = program
+        .command("ugc")
+        .description("Manage UGC programs and independent creator participations: briefs, voice, posts, approvals, sponsorship and bounded amplification. Requires UGC availability.");
+    const groupDescriptions = {
+        programs: "Programs you operate or joined. Lifecycle: create, update, duplicate (settings + briefs), archive (stops future work, keeps shared history, reversible with restore) and delete (permanent; only while no creator has ever joined).",
+        creators: "Creator participations: invite, revoke an invite, accept in the creator workspace, connect a sender, change approval authority, or revoke.",
+        briefs: "Program briefs with ordered questions for creators.",
+        posts: "Enrolled program posts: enroll existing posts, draft from briefs, edit, schedule, and record creator or brand approval.",
+        analytics: "Stored daily program and creator performance.",
+        knowledge: "Master Knowledge pages shared live with a program.",
+        voice: "Creator voice profiles and imports.",
+        sponsorship: "Seat and credit sponsorship per participation.",
+        amplification: "Bounded, approval-gated amplification of enrolled posts.",
+        calendar: "Bounded enrolled-post calendar reads.",
+    };
+    const groups = new Map();
+    const group = (name) => {
+        let command = groups.get(name);
+        if (!command) {
+            command = ugc.command(name);
+            const description = groupDescriptions[name];
+            if (description)
+                command.description(description);
+            groups.set(name, command);
+        }
+        return command;
+    };
+    group("programs")
+        .command("list")
+        .description("Read UGC programs in the active workspace, archived ones included unless --status filters. Read-only.")
+        .option("--program-id <id>", "Program ID.")
+        .option("--participation-id <id>", "Creator participation ID.")
+        .option("--status <active|archived>", "Only programs in this status.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("ugc programs list", options, () => {
+        const query = new URLSearchParams({ view: "programs" });
+        if (options.programId)
+            query.set("program_id", String(options.programId));
+        if (options.participationId)
+            query.set("participation_id", String(options.participationId));
+        if (options.status)
+            query.set("status", String(options.status));
+        return requestOxygen(`/api/cli/ugc?${query}`);
+    }));
+    group("programs")
+        .command("get")
+        .description("Read UGC program in the active workspace. Read-only.")
+        .requiredOption("--program-id <id>", "Program ID.")
+        .option("--participation-id <id>", "Creator participation ID.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("ugc programs get", options, () => {
+        const query = new URLSearchParams({ view: "program" });
+        if (options.programId)
+            query.set("program_id", String(options.programId));
+        if (options.participationId)
+            query.set("participation_id", String(options.participationId));
+        return requestOxygen(`/api/cli/ugc?${query}`);
+    }));
+    group("creators")
+        .command("list")
+        .description("Read creators and invitations, including persisted email delivery status. Read-only.")
+        .option("--program-id <id>", "Program ID.")
+        .option("--participation-id <id>", "Creator participation ID.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("ugc creators list", options, () => {
+        const query = new URLSearchParams({ view: "participations" });
+        if (options.programId)
+            query.set("program_id", String(options.programId));
+        if (options.participationId)
+            query.set("participation_id", String(options.participationId));
+        return requestOxygen(`/api/cli/ugc?${query}`);
+    }));
+    group("briefs")
+        .command("list")
+        .description("Read one program's UGC briefs. Read-only; requires --program-id.")
+        .showHelpAfterError(`Briefs belong to a program. Run \`${program.name() || "oxygen"} ugc programs list --json\` to find its ID, then \`${program.name() || "oxygen"} ugc briefs list --program-id <id> --json\`.`)
+        .requiredOption("--program-id <id>", "Program ID.")
+        .option("--participation-id <id>", "Creator participation ID.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("ugc briefs list", options, () => {
+        const query = new URLSearchParams({ view: "briefs" });
+        if (options.programId)
+            query.set("program_id", String(options.programId));
+        if (options.participationId)
+            query.set("participation_id", String(options.participationId));
+        return requestOxygen(`/api/cli/ugc?${query}`);
+    }));
+    group("posts")
+        .command("list")
+        .description("Read UGC posts in the active workspace. Read-only.")
+        .requiredOption("--program-id <id>", "Program ID.")
+        .option("--participation-id <id>", "Creator participation ID.")
+        .option("--cursor <cursor>", "Opaque next_cursor from the previous page.")
+        .option("--limit <count>", "Posts per page, 1–500.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("ugc posts list", options, () => {
+        const query = new URLSearchParams({ view: "posts" });
+        if (options.programId)
+            query.set("program_id", String(options.programId));
+        if (options.participationId)
+            query.set("participation_id", String(options.participationId));
+        if (options.cursor)
+            query.set("cursor", String(options.cursor));
+        if (options.limit)
+            query.set("limit", String(options.limit));
+        return requestOxygen(`/api/cli/ugc?${query}`);
+    }));
+    group("analytics")
+        .command("get")
+        .description("Read UGC analytics in the active workspace. Read-only.")
+        .requiredOption("--program-id <id>", "Program ID.")
+        .option("--participation-id <id>", "Creator participation ID.")
+        .option("--post-cursor <cursor>", "Next post_performance page from next_post_cursor; totals still cover all enrolled posts.")
+        .option("--limit <count>", "Post performance rows per page, up to 100.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("ugc analytics get", options, () => {
+        const query = new URLSearchParams({ view: "analytics" });
+        if (options.programId)
+            query.set("program_id", String(options.programId));
+        if (options.participationId)
+            query.set("participation_id", String(options.participationId));
+        if (options.postCursor)
+            query.set("post_cursor", String(options.postCursor));
+        if (options.limit)
+            query.set("limit", String(options.limit));
+        return requestOxygen(`/api/cli/ugc?${query}`);
+    }));
+    group("knowledge")
+        .command("list")
+        .description("Read UGC knowledge in the active workspace. Read-only.")
+        .requiredOption("--program-id <id>", "Program ID.")
+        .option("--participation-id <id>", "Creator participation ID.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("ugc knowledge list", options, () => {
+        const query = new URLSearchParams({ view: "knowledge" });
+        if (options.programId)
+            query.set("program_id", String(options.programId));
+        if (options.participationId)
+            query.set("participation_id", String(options.participationId));
+        return requestOxygen(`/api/cli/ugc?${query}`);
+    }));
+    group("voice")
+        .command("get")
+        .description("Read UGC voice in the active workspace. Read-only.")
+        .option("--program-id <id>", "Program ID.")
+        .requiredOption("--participation-id <id>", "Creator participation ID.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("ugc voice get", options, () => {
+        const query = new URLSearchParams({ view: "voice" });
+        if (options.programId)
+            query.set("program_id", String(options.programId));
+        if (options.participationId)
+            query.set("participation_id", String(options.participationId));
+        return requestOxygen(`/api/cli/ugc?${query}`);
+    }));
+    group("posts")
+        .command("draft-status")
+        .description("Read the original paid draft request and saved result without generating again. Creator workspace only, 0 credits.")
+        .requiredOption("--participation-id <id>", "Creator participation ID.")
+        .requiredOption("--request-id <id>", "Original draft request ID.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("ugc posts draft-status", options, () => {
+        const query = new URLSearchParams({
+            view: "draft_run",
+            participation_id: String(options.participationId),
+            request_id: String(options.requestId),
+        });
+        return requestOxygen(`/api/cli/ugc?${query}`);
+    }));
+    group("sponsorship")
+        .command("get")
+        .description("Read sponsorship in the active workspace. Creators see their remaining credits and exact organizer access; masters see program payment status. Read-only.")
+        .requiredOption("--program-id <id>", "Program ID.")
+        .option("--participation-id <id>", "Creator participation ID.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("ugc sponsorship get", options, () => {
+        const query = new URLSearchParams({ view: "sponsorship" });
+        if (options.programId)
+            query.set("program_id", String(options.programId));
+        if (options.participationId)
+            query.set("participation_id", String(options.participationId));
+        return requestOxygen(`/api/cli/ugc?${query}`);
+    }));
+    for (const spec of [
+        {
+            group: "calendar",
+            command: "list",
+            view: "calendar",
+            description: "Read the program's enrolled post calendar in a bounded UTC date range (up to 42 days). Stored data only, 0 credits.",
+            fields: [
+                ["date_from", "Start ISO instant, inclusive.", true],
+                ["date_to", "End ISO instant, exclusive.", true],
+                [
+                    "calendar_cursor",
+                    "Calendar next_cursor from the previous page.",
+                    false,
+                ],
+                ["participation_id", "Filter to one creator participation.", false],
+            ],
+        },
+        {
+            group: "posts",
+            command: "history",
+            view: "post_history",
+            description: "Read retained public comments, metrics, and publication receipts for one enrolled post. Stored data only, 0 credits.",
+            fields: [
+                ["post_id", "Enrolled source post UUID.", true],
+                ["cursor", "next_comments_cursor from the previous page.", false],
+                ["metric_cursor", "next_metrics_cursor from the previous page.", false],
+                ["action_cursor", "next_actions_cursor from the previous page.", false],
+            ],
+        },
+        {
+            group: "amplification",
+            command: "get",
+            view: "amplification",
+            description: "Read this program's current amplification authority and immutable action history. Master workspace only; 0 credits, no provider call.",
+            fields: [["cursor", "next_cursor from the previous action page.", false]],
+        },
+    ]) {
+        const command = group(spec.group)
+            .command(spec.command)
+            .description(spec.description)
+            .requiredOption("--program-id <id>", "Program ID.")
+            .option("--limit <count>", "Rows per page, up to 100.")
+            .option("--json", "Print a JSON envelope.");
+        for (const [name, description, required] of spec.fields)
+            command[required ? "requiredOption" : "option"](`--${name.replaceAll("_", "-")} <value>`, description);
+        command.action((options) => handle(`ugc ${spec.group} ${spec.command}`, options, () => {
+            const query = new URLSearchParams({
+                view: spec.view,
+                program_id: String(options.programId),
+            });
+            for (const [name] of spec.fields) {
+                const key = name.replace(/_([a-z])/g, (_match, letter) => letter.toUpperCase());
+                if (options[key] !== undefined)
+                    query.set(name, String(options[key]));
+            }
+            if (options.limit)
+                query.set("limit", String(options.limit));
+            return requestOxygen(`/api/cli/ugc?${query}`);
+        }));
+    }
+    const writes = [
+        {
+            action: "program_create",
+            command: "programs create",
+            description: "Create a master UGC program. Free: 0 credits, no provider call.",
+            fields: [
+                {
+                    name: "name",
+                    kind: "string",
+                    description: "Program name.",
+                    required: true,
+                },
+                {
+                    name: "product_url",
+                    kind: "string",
+                    description: "Product website URL.",
+                    required: true,
+                },
+                {
+                    name: "description",
+                    kind: "string",
+                    description: "Program description.",
+                    required: false,
+                },
+                {
+                    name: "knowledge_slugs",
+                    kind: "array",
+                    description: "Selected live master wiki slugs shared with creators; empty array clears sharing.",
+                    required: false,
+                },
+                {
+                    name: "brand_approval_required",
+                    kind: "boolean",
+                    description: "Require a separate brand approval before publishing.",
+                    required: false,
+                },
+            ],
+        },
+        {
+            action: "program_update",
+            command: "programs update",
+            description: "Update program settings and selected shared knowledge.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+                {
+                    name: "name",
+                    kind: "string",
+                    description: "Program name.",
+                    required: false,
+                },
+                {
+                    name: "product_url",
+                    kind: "string",
+                    description: "Product website URL.",
+                    required: false,
+                },
+                {
+                    name: "description",
+                    kind: "string",
+                    description: "Program description.",
+                    required: false,
+                },
+                {
+                    name: "knowledge_slugs",
+                    kind: "array",
+                    description: "Selected live master wiki slugs shared with creators; empty array clears sharing.",
+                    required: false,
+                },
+                {
+                    name: "brand_approval_required",
+                    kind: "boolean",
+                    description: "Require a separate brand approval before publishing.",
+                    required: false,
+                },
+                {
+                    name: "status",
+                    kind: "string",
+                    description: "active or archived; prefer `programs archive` / `programs restore`.",
+                    required: false,
+                },
+            ],
+        },
+        {
+            action: "program_update",
+            command: "programs archive",
+            description: "Archive a program: stop future access, publishing, tracking and amplification, revoke pending invitations and request cancellation of sponsorship renewals. Shared history is retained; `programs restore` re-activates it.",
+            fixed: { status: "archived" },
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+            ],
+        },
+        {
+            action: "program_update",
+            command: "programs restore",
+            description: "Restore an archived program. Creators removed earlier stay removed, revoked invitations stay revoked, and cancelled sponsorships need a new preview and confirmation.",
+            fixed: { status: "active" },
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+            ],
+        },
+        {
+            action: "program_duplicate",
+            command: "programs duplicate",
+            description: "Copy a program's settings, shared knowledge and brand review into a new active program, with its briefs by default. Free: 0 credits. Never copies creators, invitations, posts or sponsorship.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Source program ID.",
+                    required: true,
+                },
+                {
+                    name: "name",
+                    kind: "string",
+                    description: 'Name of the copy; defaults to "<name> (copy)".',
+                    required: false,
+                },
+                {
+                    name: "include_briefs",
+                    kind: "boolean",
+                    description: "Copy the program's briefs (default true).",
+                    required: false,
+                },
+            ],
+        },
+        {
+            action: "program_delete",
+            command: "programs delete",
+            description: "Permanently delete a program with its briefs and pending invitations. A bare call previews the counts and whether it is deletable; pass --approved to delete. Allowed only while no creator has ever joined; otherwise use `programs archive`.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+                {
+                    name: "approved",
+                    kind: "boolean",
+                    description: "Confirm the previewed permanent deletion.",
+                    required: false,
+                },
+            ],
+        },
+        {
+            action: "invite_create",
+            command: "creators invite",
+            description: "Preview an invitation email (0 credits); send with --approved --preview-token from that preview. Use --link-only to create a link without email.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+                {
+                    name: "email",
+                    kind: "string",
+                    description: "Exact creator email to receive the invitation.",
+                    required: true,
+                },
+                {
+                    name: "approved",
+                    kind: "boolean",
+                    description: "Authorize sending the exact previewed invitation email.",
+                    required: false,
+                },
+                {
+                    name: "preview_token",
+                    kind: "string",
+                    description: "Exact token from the invitation email preview.",
+                    required: false,
+                },
+            ],
+        },
+        {
+            action: "invite_send",
+            command: "creators send-invite",
+            description: "Preview email for an existing pending invitation; send or resend with --approved --preview-token. Replaces the old link, keeps its expiry. Sent means provider accepted, not inbox delivery.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+                {
+                    name: "invitation_id",
+                    kind: "string",
+                    description: "Exact pending invitation ID from creators list.",
+                    required: true,
+                },
+                {
+                    name: "approved",
+                    kind: "boolean",
+                    description: "Authorize the exact previewed email send or resend.",
+                    required: false,
+                },
+                {
+                    name: "preview_token",
+                    kind: "string",
+                    description: "Exact token from this invitation email preview.",
+                    required: false,
+                },
+            ],
+        },
+        {
+            action: "invite_revoke",
+            command: "creators revoke-invite",
+            description: "Revoke an unaccepted invitation.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+                {
+                    name: "invitation_id",
+                    kind: "string",
+                    description: "Exact invitation ID to revoke.",
+                    required: true,
+                },
+            ],
+        },
+        {
+            action: "invite_accept",
+            command: "creators accept",
+            description: "Accept an exact invitation in the creator workspace and choose who may approve.",
+            fields: [
+                {
+                    name: "token",
+                    kind: "string",
+                    description: "Exact invitation token.",
+                    required: true,
+                },
+                {
+                    name: "approval_mode",
+                    kind: "string",
+                    description: "creator: creator approves; delegated: master operators may approve and schedule.",
+                    required: true,
+                },
+                {
+                    name: "linkedin_url",
+                    kind: "string",
+                    description: "Creator LinkedIn profile URL.",
+                    required: true,
+                },
+            ],
+        },
+        {
+            action: "participation_update",
+            command: "creators update",
+            description: "Connect an existing LinkedIn sender, change approval authority, or revoke participation.",
+            fields: [
+                {
+                    name: "participation_id",
+                    kind: "string",
+                    description: "Creator participation ID.",
+                    required: true,
+                },
+                {
+                    name: "approval_mode",
+                    kind: "string",
+                    description: "creator: creator approves; delegated: master operators may approve and schedule.",
+                    required: false,
+                },
+                {
+                    name: "sender_account_id",
+                    kind: "string",
+                    description: "Existing physical LinkedIn connection ID; reused across programs.",
+                    required: false,
+                },
+                {
+                    name: "status",
+                    kind: "string",
+                    description: "Program status, or revoked for a participation.",
+                    required: false,
+                },
+            ],
+        },
+        {
+            action: "brief_create",
+            command: "briefs create",
+            description: "Create a brief with ordered questions. Free: 0 credits, no provider call.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+                {
+                    name: "title",
+                    kind: "string",
+                    description: "Brief or post title.",
+                    required: true,
+                },
+                {
+                    name: "prompt",
+                    kind: "string",
+                    description: "Instructions for this brief.",
+                    required: true,
+                },
+                {
+                    name: "questions",
+                    kind: "array",
+                    description: "Ordered questions for the creator.",
+                    required: true,
+                },
+                {
+                    name: "cycle",
+                    kind: "string",
+                    description: "Brief cycle label.",
+                    required: false,
+                },
+            ],
+        },
+        {
+            action: "brief_update",
+            command: "briefs update",
+            description: "Update a program brief.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+                {
+                    name: "brief_id",
+                    kind: "string",
+                    description: "Brief ID.",
+                    required: true,
+                },
+                {
+                    name: "title",
+                    kind: "string",
+                    description: "Brief or post title.",
+                    required: false,
+                },
+                {
+                    name: "prompt",
+                    kind: "string",
+                    description: "Instructions for this brief.",
+                    required: false,
+                },
+                {
+                    name: "questions",
+                    kind: "array",
+                    description: "Ordered questions for the creator.",
+                    required: false,
+                },
+                {
+                    name: "cycle",
+                    kind: "string",
+                    description: "Brief cycle label.",
+                    required: false,
+                },
+            ],
+        },
+        {
+            action: "post_enroll",
+            command: "posts enroll",
+            description: "Enroll one existing creator-owned post in this participation.",
+            fields: [
+                {
+                    name: "participation_id",
+                    kind: "string",
+                    description: "Creator participation ID.",
+                    required: true,
+                },
+                {
+                    name: "post_id",
+                    kind: "string",
+                    description: "Canonical post ID.",
+                    required: true,
+                },
+            ],
+        },
+        {
+            action: "draft_create",
+            command: "posts draft",
+            description: "Preview AI drafting from brief answers. Execute only in the creator workspace with approved and a credit ceiling; publishing delegation does not grant authority to spend creator credits.",
+            fields: [
+                {
+                    name: "request_id",
+                    kind: "string",
+                    description: "Request ID from preview. Reuse it after a timeout; a new ID is a new paid draft.",
+                    required: false,
+                },
+                {
+                    name: "participation_id",
+                    kind: "string",
+                    description: "Creator participation ID.",
+                    required: true,
+                },
+                {
+                    name: "brief_id",
+                    kind: "string",
+                    description: "Brief ID.",
+                    required: true,
+                },
+                {
+                    name: "answers",
+                    kind: "array",
+                    description: "Answers in brief question order.",
+                    required: true,
+                },
+                {
+                    name: "approved",
+                    kind: "boolean",
+                    description: "Explicit authorization of the exact preview or approval. Never inferred.",
+                    required: false,
+                },
+                {
+                    name: "max_credits",
+                    kind: "number",
+                    description: "Explicit credit ceiling from preview.",
+                    required: false,
+                },
+            ],
+        },
+        {
+            action: "post_update",
+            command: "posts update",
+            description: "Edit or schedule an enrolled post with creator or delegated authority; publishing gates still apply.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+                {
+                    name: "post_id",
+                    kind: "string",
+                    description: "Canonical post ID.",
+                    required: true,
+                },
+                {
+                    name: "title",
+                    kind: "string",
+                    description: "Brief or post title.",
+                    required: false,
+                },
+                {
+                    name: "content_text",
+                    kind: "string",
+                    description: "Edited post text.",
+                    required: false,
+                },
+                {
+                    name: "scheduled_for",
+                    kind: "string",
+                    description: "Future ISO-8601 publishing time with timezone.",
+                    required: false,
+                },
+            ],
+        },
+        {
+            action: "post_approve",
+            command: "posts approve",
+            description: "Record creator or explicitly delegated operator approval of the current post.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+                {
+                    name: "post_id",
+                    kind: "string",
+                    description: "Canonical post ID.",
+                    required: true,
+                },
+                {
+                    name: "source_revision",
+                    kind: "string",
+                    description: "Exact reviewed content fingerprint returned by posts list.",
+                    required: true,
+                },
+                {
+                    name: "approved",
+                    kind: "boolean",
+                    description: "Explicit authorization of the exact preview or approval. Never inferred.",
+                    required: true,
+                },
+            ],
+        },
+        {
+            action: "brand_approve",
+            command: "posts brand-approve",
+            description: "Record separate master brand approval of the current post.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+                {
+                    name: "post_id",
+                    kind: "string",
+                    description: "Canonical post ID.",
+                    required: true,
+                },
+                {
+                    name: "source_revision",
+                    kind: "string",
+                    description: "Exact reviewed content fingerprint returned by posts list.",
+                    required: true,
+                },
+                {
+                    name: "approved",
+                    kind: "boolean",
+                    description: "Explicit authorization of the exact preview or approval. Never inferred.",
+                    required: true,
+                },
+            ],
+        },
+        {
+            action: "voice_import",
+            command: "voice import",
+            description: "Preview all retrievable LinkedIn history and voice inference; approve a total credit ceiling to start. Use --import-id to resume a safely interrupted import with its saved progress and spend.",
+            fields: [
+                {
+                    name: "participation_id",
+                    kind: "string",
+                    description: "Creator participation ID.",
+                    required: true,
+                },
+                {
+                    name: "import_id",
+                    kind: "string",
+                    description: "Existing safely interrupted import to resume; max-credits is its total ceiling including credits already used.",
+                    required: false,
+                },
+                {
+                    name: "approved",
+                    kind: "boolean",
+                    description: "Explicit authorization of the exact preview or approval. Never inferred.",
+                    required: false,
+                },
+                {
+                    name: "max_credits",
+                    kind: "number",
+                    description: "Explicit credit ceiling from preview.",
+                    required: false,
+                },
+            ],
+        },
+        {
+            action: "voice_save",
+            command: "voice save",
+            description: "Save your own writing preferences and examples as a private provisional Knowledge voice. Free: 0 credits, no provider call or connected account required. Existing voice edits require its current revision.",
+            fields: [
+                {
+                    name: "participation_id",
+                    kind: "string",
+                    description: "Your creator participation ID.",
+                    required: true,
+                },
+                {
+                    name: "body",
+                    kind: "string",
+                    description: "Your own writing preferences or voice guide (Markdown).",
+                    required: true,
+                },
+                {
+                    name: "writing_examples",
+                    kind: "array",
+                    description: "JSON array of up to five examples you actually wrote; do not invent personal experiences.",
+                    required: false,
+                },
+                {
+                    name: "expected_revision",
+                    kind: "number",
+                    description: "Current profile revision returned by voice get, required when editing it.",
+                    required: false,
+                },
+            ],
+        },
+        {
+            action: "sponsorship_cancel",
+            command: "sponsorship cancel",
+            description: "Preview stopping renewal for one program sponsorship. Confirm with --approved and a signed-in master admin. Participation and credits through the paid period remain available.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Master program ID.",
+                    required: true,
+                },
+                {
+                    name: "participation_id",
+                    kind: "string",
+                    description: "Exact creator participation ID.",
+                    required: true,
+                },
+                {
+                    name: "approved",
+                    kind: "boolean",
+                    description: "Approve the exact cancellation preview. Omit for a free preview.",
+                    required: false,
+                },
+            ],
+        },
+        {
+            action: "sponsorship_preview",
+            command: "sponsorship preview",
+            description: "Preview seat charges and monthly 10,000-credit creator grants as a signed-in master workspace admin. Org API keys cannot create this quote.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+                {
+                    name: "participation_ids",
+                    kind: "array",
+                    description: "Exact creator participation IDs to sponsor.",
+                    required: true,
+                },
+            ],
+        },
+        {
+            action: "sponsorship_confirm",
+            command: "sponsorship confirm",
+            description: "Confirm the exact sponsorship quote as the same signed-in master workspace admin. Each program pays separately, even for the same account.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+                {
+                    name: "participation_ids",
+                    kind: "array",
+                    description: "Exact creator participation IDs to sponsor.",
+                    required: true,
+                },
+                {
+                    name: "quote",
+                    kind: "string",
+                    description: "Exact sponsorship quote returned by preview.",
+                    required: true,
+                },
+                {
+                    name: "approved",
+                    kind: "boolean",
+                    description: "Explicit authorization of the exact preview or approval. Never inferred.",
+                    required: true,
+                },
+            ],
+        },
+        {
+            action: "amplification_reconcile",
+            command: "amplification reconcile",
+            description: "Preview recording a provider observation for an uncertain program action. Confirmation needs a signed-in operator and --approved; it never contacts the provider or authorizes a retry.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID in the master workspace.",
+                    required: true,
+                },
+                {
+                    name: "action_id",
+                    kind: "string",
+                    description: "Unresolved effect_unknown action ID.",
+                    required: true,
+                },
+                {
+                    name: "outcome",
+                    kind: "string",
+                    description: "Observed applied or not_applied outcome.",
+                    required: true,
+                },
+                {
+                    name: "evidence",
+                    kind: "object",
+                    description: "JSON object: provider_post_id, evidence_ref, observed_at ISO instant; applied needs provider_object_id and comments/reposts need exact observed_text. Optional note.",
+                    required: true,
+                },
+                {
+                    name: "approved",
+                    kind: "boolean",
+                    description: "Explicitly confirm this immutable observation. No retry is authorized.",
+                    required: false,
+                },
+            ],
+        },
+        {
+            action: "amplification_save",
+            command: "amplification save",
+            description: "Save exact opted-in sender scope and bounded post-specific amplification. Enabling needs explicit approval.",
+            fields: [
+                {
+                    name: "sender_voice_pages",
+                    kind: "object",
+                    description: "JSON map from each acting sender UUID to its selected active Knowledge voice page UUID. Required for comments or reposts; the exact mapping is approved with the policy.",
+                    required: false,
+                },
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+                {
+                    name: "participant_sender_ids",
+                    kind: "array",
+                    description: "Exact opted-in participant sender IDs.",
+                    required: true,
+                },
+                {
+                    name: "actions",
+                    kind: "array",
+                    description: "Allowed post-specific amplification actions.",
+                    required: true,
+                },
+                {
+                    name: "enabled",
+                    kind: "boolean",
+                    description: "Enable the bounded amplification policy.",
+                    required: true,
+                },
+                {
+                    name: "max_actions_per_post",
+                    kind: "number",
+                    description: "Hard limit for amplification actions on each enrolled published post.",
+                    required: true,
+                },
+                {
+                    name: "max_credits_per_cycle",
+                    kind: "number",
+                    description: "Hard credit ceiling for the amplification cycle.",
+                    required: true,
+                },
+                {
+                    name: "approved",
+                    kind: "boolean",
+                    description: "Explicit authorization of the exact preview or approval. Never inferred.",
+                    required: false,
+                },
+                {
+                    name: "delay_min_seconds",
+                    kind: "number",
+                    description: "Minimum amplification delay, 60–3600 seconds.",
+                    required: false,
+                },
+                {
+                    name: "delay_max_seconds",
+                    kind: "number",
+                    description: "Maximum amplification delay, 60–86400 seconds.",
+                    required: false,
+                },
+            ],
+        },
+    ];
+    for (const spec of writes) {
+        const [family, leaf] = spec.command.split(" ");
+        const command = group(family).command(leaf).description(spec.description);
+        for (const field of spec.fields) {
+            const flag = `--${field.name.replaceAll("_", "-")}${field.name === "approved" ? "" : ` <${field.kind === "array" || field.kind === "object" ? "json" : field.kind === "boolean" ? "true|false" : "value"}>`}`;
+            if (field.required)
+                command.requiredOption(flag, field.description);
+            else
+                command.option(flag, field.description);
+        }
+        if (spec.action === "invite_create")
+            command.option("--link-only", "Create a shareable link without sending email.");
+        command
+            .option("--json", "Print a JSON envelope.")
+            .action((options) => handle(`ugc ${spec.command}`, options, () => {
+            const body = {
+                action: spec.action,
+                ...(spec.fixed ?? {}),
+            };
+            for (const field of spec.fields) {
+                const key = field.name.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+                if (options[key] !== undefined)
+                    body[field.name] = parseField(options[key], field);
+            }
+            if (spec.action === "invite_create") {
+                body.send_email = options.linkOnly !== true;
+                if (options.linkOnly && (body.approved || body.preview_token))
+                    throw new Error("--link-only cannot be combined with --approved or --preview-token.");
+            }
+            return requestOxygen("/api/cli/ugc", {
+                method: "POST",
+                body,
+                ...(spec.action === "draft_create" &&
+                    typeof body.request_id === "string"
+                    ? { idempotencyKey: body.request_id }
+                    : {}),
+            });
+        }));
+    }
+}