@oxygen-agent/cli 1.1003.12 → 1.1010.644

package/node_modules/@oxygen/cli-ugc/dist/commands.js

@@ -2,13 +2,14 @@ import { parseField } from "./field-parser.js";
 export function registerUgcCommands(program, { request: requestOxygen, 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. Start with memberships list in a creator workspace. See the oxygen-ugc skill; JSON reads return web_url for inspection.");
+        .description("Manage UGC programs and independent creator participations: voice, posts, approvals, sponsorship and bounded amplification. Requires UGC availability. Start with memberships list in a creator workspace. See the oxygen-ugc skill; JSON reads return web_url for inspection.");
     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.",
-        memberships: "Active programs this creator workspace has joined. Read these before choosing a program for a personal post.",
-        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.",
+        programs: "Programs you operate or joined; discover public programs from other brands and apply to them. Lifecycle: create, update, duplicate (settings), archive (stops future work, keeps shared history, reversible with restore) and delete (permanent; only while no creator has ever joined).",
+        creators: "Creator participations: invite, set one creator's own posting deal, revoke an invite, accept in the creator workspace, connect a sender, change approval authority, or revoke.",
+        memberships: "Active programs this creator workspace has joined, each with your deal (posting_target), this period's progress and your published posts. Your own numbers only. Read these before choosing a program for a personal post.",
+        applications: "Applications to public programs: the ones you sent as a creator, or the ones your program received as a brand.",
+        profile: "Your creator profile: the topics you post about, who follows you and your LinkedIn profile URL (used when you apply), readable by the brands whose programs you joined. Name, picture and headline come from your connected LinkedIn account.",
+        posts: "Enrolled program posts: enroll existing posts, draft from a topic, edit, schedule, record creator or brand approval, and schedule one-off comments on program posts.",
         analytics: "Stored daily program and creator performance.",
         knowledge: "Master Knowledge pages shared live with a program.",
         voice: "Creator voice profiles and imports.",
@@ -62,7 +63,7 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
     }));
     group("creators")
         .command("list")
-        .description("Read creators and invitations, including persisted email delivery status. Read-only.")
+        .description("Read creators (name, picture, LinkedIn URL and posting_target, their own deal; null follows the program standard) 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.")
@@ -74,26 +75,38 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
             query.set("participation_id", String(options.participationId));
         return requestOxygen(`/api/cli/ugc?${query}`);
     }));
-    group("memberships")
-        .command("list")
-        .description("Read active program memberships for the creator workspace. Free, stored and provider-free.")
+    group("creators")
+        .command("invitation")
+        .description("Read what an invitation link points at before accepting it: the program, the invited email (masked), the posting deal, and can_accept with the reason when this account or workspace cannot accept it. Free, read-only.")
+        .requiredOption("--token <token>", "The token from the invitation link (?invite=...).")
         .option("--json", "Print a JSON envelope.")
-        .action((options) => handle("ugc memberships list", options, () => requestOxygen("/api/cli/ugc?view=memberships")));
-    group("briefs")
+        .action((options) => handle("ugc creators invitation", options, () => requestOxygen(`/api/cli/ugc?${new URLSearchParams({ view: "invitation", token: String(options.token) })}`)));
+    group("programs")
+        .command("discover")
+        .description("Public programs from every brand on Oxygen that you can apply to, with each brand's deal and brief excerpt, and whether you already joined or applied. Free, read-only.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("ugc programs discover", options, () => requestOxygen("/api/cli/ugc?view=discover")));
+    group("applications")
         .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.")
+        .description("Applications to public programs. Without --program-id: the ones this creator workspace sent, with status. With --program-id: the ones your program received (brand), pending first. Read-only.")
+        .option("--program-id <id>", "Your program's ID, to see who applied to it.")
         .option("--json", "Print a JSON envelope.")
-        .action((options) => handle("ugc briefs list", options, () => {
-        const query = new URLSearchParams({ view: "briefs" });
+        .action((options) => handle("ugc applications list", options, () => {
+        const query = new URLSearchParams({ view: "applications" });
         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("profile")
+        .command("get")
+        .description("Read your creator profile (topics, audience and LinkedIn profile URL). Free, read-only.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("ugc profile get", options, () => requestOxygen("/api/cli/ugc?view=creator_profile")));
+    group("memberships")
+        .command("list")
+        .description("Read active program memberships for the creator workspace. Free, stored and provider-free.")
+        .option("--json", "Print a JSON envelope.")
+        .action((options) => handle("ugc memberships list", options, () => requestOxygen("/api/cli/ugc?view=memberships")));
     group("posts")
         .command("list")
         .description("Read UGC posts in the active workspace. Read-only.")
@@ -122,7 +135,7 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
     }));
     group("analytics")
         .command("get")
-        .description("Read UGC analytics in the active workspace. Read-only.")
+        .description("Read UGC analytics in the active workspace. Read-only. The brand workspace sees every creator; a creator workspace only ever gets its own row, with or without --participation-id.")
         .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.")
@@ -276,19 +289,25 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
         {
             action: "program_create",
             command: "programs create",
-            description: "Create a master UGC program. Free: 0 credits, no provider call.",
+            description: "Create a master UGC program from its product link. The name defaults to the site's name and its icon is fetched from the site. Free: 0 credits, no provider call.",
             fields: [
                 {
-                    name: "name",
+                    name: "product_url",
                     kind: "string",
-                    description: "Program name.",
+                    description: "Product domain or link, e.g. acme.com.",
                     required: true,
                 },
                 {
-                    name: "product_url",
+                    name: "name",
                     kind: "string",
-                    description: "Product website URL.",
-                    required: true,
+                    description: "Program name; defaults to the product site's name, else its domain.",
+                    required: false,
+                },
+                {
+                    name: "brief",
+                    kind: "string",
+                    description: "Short creator brief (up to 1,200 characters): what the product is, who it is for, key facts and the call to action. Drafts are grounded in it.",
+                    required: false,
                 },
                 {
                     name: "description",
@@ -308,6 +327,18 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
                     description: "Require a separate brand approval before publishing.",
                     required: false,
                 },
+                {
+                    name: "posting_target",
+                    kind: "posting_target",
+                    description: "Posts each creator should publish by default: <n>/month, <n>/week or <n>/total (n 1–100), or none to clear. One creator's own deal: creators set-target.",
+                    required: false,
+                },
+                {
+                    name: "visibility",
+                    kind: "string",
+                    description: "private (default: invitation only) or public (listed in every creator's Discover, where creators apply and you approve).",
+                    required: false,
+                },
             ],
         },
         {
@@ -330,7 +361,13 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
                 {
                     name: "product_url",
                     kind: "string",
-                    description: "Product website URL.",
+                    description: "Product domain or link; a new one refreshes the icon.",
+                    required: false,
+                },
+                {
+                    name: "brief",
+                    kind: "string",
+                    description: "Short creator brief (up to 1,200 characters); an empty string clears it.",
                     required: false,
                 },
                 {
@@ -351,6 +388,18 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
                     description: "Require a separate brand approval before publishing.",
                     required: false,
                 },
+                {
+                    name: "posting_target",
+                    kind: "posting_target",
+                    description: "Posts each creator should publish by default: <n>/month, <n>/week or <n>/total (n 1–100), or none to clear. One creator's own deal: creators set-target.",
+                    required: false,
+                },
+                {
+                    name: "visibility",
+                    kind: "string",
+                    description: "private (default: invitation only) or public (listed in every creator's Discover, where creators apply and you approve).",
+                    required: false,
+                },
                 {
                     name: "peer_engagement_enabled",
                     kind: "boolean",
@@ -396,7 +445,7 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
         {
             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.",
+            description: "Copy a program's settings, shared knowledge, brand review and posting target into a new active program. Free: 0 credits. Never copies creators, invitations, posts or sponsorship.",
             fields: [
                 {
                     name: "program_id",
@@ -410,18 +459,12 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
                     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`.",
+            description: "Permanently delete a program and its 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",
@@ -440,7 +483,7 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
         {
             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.",
+            description: "Preview an invitation email (0 credits) for one creator (--email) or up to 50 at once (--emails); send with --approved --preview-token from that preview and the same recipients. Use --link-only to create links without email.",
             fields: [
                 {
                     name: "program_id",
@@ -452,7 +495,31 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
                     name: "email",
                     kind: "string",
                     description: "Exact creator email to receive the invitation.",
-                    required: true,
+                    required: false,
+                },
+                {
+                    name: "emails",
+                    kind: "email_list",
+                    description: "Several creator emails, comma-separated or a JSON array (1–50, duplicates removed).",
+                    required: false,
+                },
+                {
+                    name: "posting_target",
+                    kind: "posting_target",
+                    description: "These creators' own deal when it differs from the program standard, e.g. 1/month; omit to follow the program. Change it later with creators set-target.",
+                    required: false,
+                },
+                {
+                    name: "email_subject",
+                    kind: "string",
+                    description: "Your own email subject (up to 200 characters); omit for the default.",
+                    required: false,
+                },
+                {
+                    name: "email_message",
+                    kind: "string",
+                    description: "Your own message (up to 3,000 characters); the Accept button and join link are always added below it. Omit for the default.",
+                    required: false,
                 },
                 {
                     name: "approved",
@@ -468,6 +535,92 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
                 },
             ],
         },
+        {
+            action: "application_create",
+            command: "programs apply",
+            description: "Apply to a public program from programs discover, with a short note to the brand. The brand approves or declines; approval makes you a creator in the program and emails you. Free: 0 credits.",
+            fields: [
+                { name: "program_id", kind: "string", description: "Public program ID from programs discover.", required: true },
+                { name: "message", kind: "string", description: "Your note to the brand (up to 600 characters).", required: true },
+                { name: "linkedin_url", kind: "string", description: "Your LinkedIn profile URL; passing it also saves it to your profile. Omit to use the one on your profile (ugc profile get); if neither exists, ask the person rather than guess.", required: false },
+            ],
+        },
+        {
+            action: "application_decide",
+            command: "creators approve",
+            description: "Approve a pending application to your program (from applications list --program-id). The applicant becomes a creator at once and is emailed. Free: 0 credits.",
+            fixed: { decision: "approve" },
+            fields: [
+                { name: "program_id", kind: "string", description: "Program ID.", required: true },
+                { name: "application_id", kind: "string", description: "Pending application ID.", required: true },
+            ],
+        },
+        {
+            action: "application_decide",
+            command: "creators decline",
+            description: "Decline a pending application to your program. No email is sent. Free: 0 credits.",
+            fixed: { decision: "decline" },
+            fields: [
+                { name: "program_id", kind: "string", description: "Program ID.", required: true },
+                { name: "application_id", kind: "string", description: "Pending application ID.", required: true },
+            ],
+        },
+        {
+            action: "creator_profile_update",
+            command: "profile update",
+            description: "Save your creator profile, which brands whose programs you joined can read. --topics replaces the list; --audience \"\" clears it. Free: 0 credits.",
+            fields: [
+                {
+                    name: "topics",
+                    kind: "text_list",
+                    description: "Topics you post about, comma-separated (up to 10, each up to 40 characters), e.g. \"B2B sales, outbound\".",
+                    required: false,
+                },
+                {
+                    name: "audience",
+                    kind: "string",
+                    description: "Who follows you, one line (up to 200 characters).",
+                    required: false,
+                },
+                {
+                    name: "linkedin_url",
+                    kind: "string",
+                    description: "Your LinkedIn profile URL, used when you apply to public programs; \"\" clears it.",
+                    required: false,
+                },
+            ],
+        },
+        {
+            action: "creator_target_update",
+            command: "creators set-target",
+            description: "Set one creator's own posting deal, e.g. 1/month while the program asks for 2/month, on a joined creator (--participation-id) or a pending invitation (--invitation-id). none returns them to the program standard. Organizer only. Free: 0 credits.",
+            fields: [
+                {
+                    name: "program_id",
+                    kind: "string",
+                    description: "Program ID.",
+                    required: true,
+                },
+                {
+                    name: "participation_id",
+                    kind: "string",
+                    description: "A joined creator's participation ID from creators list.",
+                    required: false,
+                },
+                {
+                    name: "invitation_id",
+                    kind: "string",
+                    description: "A pending invitation ID from creators list.",
+                    required: false,
+                },
+                {
+                    name: "posting_target",
+                    kind: "posting_target",
+                    description: "The creator's deal: <n>/month, <n>/week or <n>/total (n 1–100), or none for the program standard.",
+                    required: true,
+                },
+            ],
+        },
         {
             action: "invite_send",
             command: "creators send-invite",
@@ -485,6 +638,18 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
                     description: "Exact pending invitation ID from creators list.",
                     required: true,
                 },
+                {
+                    name: "email_subject",
+                    kind: "string",
+                    description: "Your own email subject (up to 200 characters); omit for the default.",
+                    required: false,
+                },
+                {
+                    name: "email_message",
+                    kind: "string",
+                    description: "Your own message (up to 3,000 characters); the Accept button and join link are always added below it. Omit for the default.",
+                    required: false,
+                },
                 {
                     name: "approved",
                     kind: "boolean",
@@ -521,7 +686,7 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
         {
             action: "invite_accept",
             command: "creators accept",
-            description: "Accept an exact invitation in the creator workspace and choose who may approve.",
+            description: "Accept an exact invitation in the creator workspace. Check it first with creators invitation --token; a refusal names its reason (wrong account, the program's own workspace, withdrawn or expired).",
             fields: [
                 {
                     name: "token",
@@ -532,8 +697,8 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
                 {
                     name: "approval_mode",
                     kind: "string",
-                    description: "creator: creator approves; delegated: master operators may approve and schedule.",
-                    required: true,
+                    description: "creator (default): you approve each post; delegated: master operators may approve and schedule.",
+                    required: false,
                 },
                 {
                     name: "linkedin_url",
@@ -574,86 +739,6 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
                 },
             ],
         },
-        {
-            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",
@@ -707,12 +792,21 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
         {
             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.",
+            description: "Draft a post from your topic in your voice, grounded in the program's shared pages. A bare call is a free preview; the creator repeats it with --request-id --approved --max-credits to run it.",
+            help: [
+                "",
+                "Two steps:",
+                "  1. Free preview (0 credits): run without --approved. It returns request_id and estimated_credits.",
+                "  2. Paid draft: from the creator's own workspace, repeat with --request-id <id> --approved --max-credits <ceiling>.",
+                "An organizer with delegated approval may preview but can never spend the creator's credits.",
+                "After a timeout, keep the same request_id and check `ugc posts draft-status`.",
+                "If the result has needs_answers with questions, add those details to --topic and preview again.",
+            ].join("\n"),
             fields: [
                 {
                     name: "request_id",
                     kind: "string",
-                    description: "Request ID from preview. Reuse it after a timeout; a new ID is a new paid draft.",
+                    description: "request_id returned by the free preview. Reuse it after a timeout; a new ID is a new paid draft.",
                     required: false,
                 },
                 {
@@ -722,15 +816,9 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
                     required: true,
                 },
                 {
-                    name: "brief_id",
+                    name: "topic",
                     kind: "string",
-                    description: "Brief ID.",
-                    required: true,
-                },
-                {
-                    name: "answers",
-                    kind: "array",
-                    description: "Answers in brief question order.",
+                    description: "What you want to post about, including any personal experience to share (up to 4000 characters).",
                     required: true,
                 },
                 {
@@ -742,7 +830,7 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
                 {
                     name: "max_credits",
                     kind: "number",
-                    description: "Explicit credit ceiling from preview.",
+                    description: "Credit ceiling for the paid run, at least the preview's estimate.",
                     required: false,
                 },
             ],
@@ -773,7 +861,7 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
                 {
                     name: "title",
                     kind: "string",
-                    description: "Brief or post title.",
+                    description: "Post title.",
                     required: false,
                 },
                 {
@@ -788,6 +876,12 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
                     description: "Future ISO-8601 publishing time with timezone.",
                     required: false,
                 },
+                {
+                    name: "approve",
+                    kind: "boolean",
+                    description: "Your own post: true approves exactly what this saves, so it schedules without a separate posts approve. Signed-in creator only; brand review still applies.",
+                    required: false,
+                },
             ],
         },
         {
@@ -1001,6 +1095,43 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
                 },
             ],
         },
+        {
+            action: "comment_schedule",
+            command: "posts comment schedule",
+            description: "Schedule one exact comment on a creator's program post from one of this workspace's LinkedIn accounts; on a post not live yet it waits. Organizer workspace only. A bare call is a free preview; repeat with --approved to schedule it. 0 credits.",
+            help: [
+                "",
+                "Two steps:",
+                "  1. Preview (free, nothing saved): run without --approved. It shows the post, the account, the exact text and when it runs.",
+                "  2. Schedule: repeat the same command with --approved from a signed-in session. The comment posts publicly on LinkedIn at --at,",
+                "     inside the account's active hours and daily comment limit; it can be cancelled until it runs.",
+                "",
+                "The post need not be live. Live means published through OXYGEN, with a LinkedIn post OXYGEN has confirmed.",
+                "On a draft, in-review or scheduled post, or one shown as published without a confirmed LinkedIn post, the",
+                "comment waits (waiting_for_post: true) and posts once the post is live, not before --at. If the post is still",
+                "not live 14 days after --at, the comment fails and is never posted. A removed post cannot take a comment.",
+                "Find post IDs with `oxygen ugc posts list --program-id <id>` and LinkedIn accounts with `oxygen senders list --json`.",
+                "Check the result with `oxygen ugc posts list --program-id <id> --post-id <id>` (scheduled_comments).",
+            ].join("\n"),
+            fields: [
+                { name: "program_id", kind: "string", description: "Program ID.", required: true },
+                { name: "post_id", kind: "string", description: "Program post ID (post_id from posts list); it need not be live yet.", required: true },
+                { name: "sender_account_id", kind: "string", description: "LinkedIn account connected in this workspace that posts the comment.", required: true },
+                { name: "text", kind: "string", description: "Exact comment text, 1–1250 characters.", required: true },
+                { name: "scheduled_for", flag: "at", kind: "string", description: "When to post: an ISO datetime with offset, or now.", required: true },
+                { name: "approved", kind: "boolean", description: "Schedule the exact previewed comment. Never inferred.", required: false },
+                { name: "max_credits", kind: "number", description: "Optional credit ceiling; the comment itself costs 0 credits.", required: false },
+            ],
+        },
+        {
+            action: "comment_cancel",
+            command: "posts comment cancel",
+            description: "Cancel a scheduled comment before it runs, including one still waiting for its post. Organizer workspace only; a comment that is already posting or posted cannot be cancelled.",
+            fields: [
+                { name: "program_id", kind: "string", description: "Program ID.", required: true },
+                { name: "comment_id", kind: "string", description: "Scheduled comment ID from the post's scheduled_comments.", required: true },
+            ],
+        },
         {
             action: "amplification_reconcile",
             command: "amplification reconcile",
@@ -1076,7 +1207,7 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
                 {
                     name: "max_actions_per_post",
                     kind: "number",
-                    description: "Hard limit for amplification actions on each enrolled published post.",
+                    description: "Hard limit for amplification actions on each enrolled published post, at most 12.",
                     required: true,
                 },
                 {
@@ -1091,6 +1222,13 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
                     description: "Explicit authorization of the exact preview or approval. Never inferred.",
                     required: false,
                 },
+                {
+                    name: "risk_acknowledged",
+                    flag: "acknowledge_risk",
+                    kind: "boolean",
+                    description: "Acknowledge that LinkedIn may warn, restrict or close accounts used for automated engagement. Required to enable.",
+                    required: false,
+                },
                 {
                     name: "delay_min_seconds",
                     kind: "number",
@@ -1116,9 +1254,10 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
                 { name: "actions", kind: "array", description: "Allowed peer actions: reaction, comment or repost.", required: true },
                 { name: "enabled", kind: "boolean", description: "Enable or disable this creator-owned policy.", required: true },
                 { name: "expected_policy_version", kind: "number", description: "Current policy version from peer-amplification get; omit or use 0 on first save.", required: false },
-                { name: "max_actions_per_post", kind: "number", description: "Hard action cap per peer post.", required: true },
+                { name: "max_actions_per_post", kind: "number", description: "Hard action cap per peer post, at most 12.", required: true },
                 { name: "max_credits_per_cycle", kind: "number", description: "Hard creator-wallet credit cap per cycle.", required: true },
                 { name: "approved", kind: "boolean", description: "Confirm this exact creator-owned scope; omit for preview.", required: false },
+                { name: "risk_acknowledged", flag: "acknowledge_risk", kind: "boolean", description: "Acknowledge that LinkedIn may warn, restrict or close accounts used for automated engagement. Required to enable.", required: false },
                 { name: "delay_min_seconds", kind: "number", description: "Minimum delay, 60–3600 seconds.", required: false },
                 { name: "delay_max_seconds", kind: "number", description: "Maximum delay, 60–86400 seconds.", required: false },
             ],
@@ -1136,18 +1275,33 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
             ],
         },
     ];
+    const subcommandDescriptions = {
+        "posts comment": "One-off comments on a program post, live or not yet live: preview, schedule with approval, cancel.",
+    };
     for (const spec of writes) {
-        const [family, leaf] = spec.command.split(" ");
-        const command = group(family).command(leaf).description(spec.description);
+        const [family, ...path] = spec.command.split(" ");
+        let parent = group(family);
+        for (const [index, name] of path.slice(0, -1).entries()) {
+            const existing = parent.commands.find((child) => child.name() === name);
+            parent =
+                existing ??
+                    parent
+                        .command(name)
+                        .description(subcommandDescriptions[[family, ...path.slice(0, index + 1)].join(" ")] ??
+                        name);
+        }
+        const command = parent.command(path.at(-1)).description(spec.description);
+        if (spec.help)
+            command.addHelpText("after", spec.help);
         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"}>`}`;
+            const flag = `--${(field.flag ?? field.name).replaceAll("_", "-")}${field.name === "approved" || field.name === "risk_acknowledged" ? "" : ` <${field.kind === "array" || field.kind === "object" ? "json" : field.kind === "boolean" ? "true|false" : field.kind === "posting_target" ? "n/month|n/week|n/total|none" : field.kind === "email_list" ? "emails" : field.kind === "text_list" ? "a, b" : "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("--link-only", "Create the invitation now and return its shareable link: no preview or approval token, no email, 0 credits.");
         command
             .option("--json", "Print a JSON envelope.")
             .action((options) => handle(`ugc ${spec.command}`, options, () => {
@@ -1156,11 +1310,13 @@ export function registerUgcCommands(program, { request: requestOxygen, handle })
                 ...(spec.fixed ?? {}),
             };
             for (const field of spec.fields) {
-                const key = field.name.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase());
+                const key = (field.flag ?? 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") {
+                if ((body.email === undefined) === (body.emails === undefined))
+                    throw new Error("Pass exactly one of --email or --emails.");
                 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.");