@greatwait/cli 0.1.0-alpha.5 → 0.1.0-alpha.7

package/dist/catalog.js

@@ -80,37 +80,37 @@ export function declaredRequestHeaders(operation) {
 /* -------------------------------------------------------------------------- */
 const API_URL = {
     flag: "--api-url",
-    summary: "The service to talk to, when it is not the selected one.",
+    summary: "The GreatWait API to use, such as https://api.greatwait.dev. Defaults to the one you signed in to.",
     value: "<origin>",
 };
 const PAGE_OPTIONS = [
     {
         flag: "--limit",
-        summary: "How many rows to ask for in one page.",
+        summary: "How many to show on one page.",
         value: "<count>",
     },
     {
         flag: "--cursor",
-        summary: "Continue from the cursor a previous page returned.",
+        summary: "Carry on from here: the cursor the previous page printed.",
         value: "<cursor>",
     },
     {
         flag: "--all",
-        summary: "Read up to 50 pages from the start or --cursor; return a cursor if more remain.",
+        summary: "Read up to 50 pages. If there are more, it prints a cursor to carry on from.",
     },
 ];
 const CONFIRM = {
     flag: "--yes",
-    summary: "Confirm without being asked. Required when there is no terminal to ask on.",
+    summary: "Don't ask first. Needed in scripts, where nobody can answer.",
 };
 const IF_MATCH = {
     flag: "--if-match",
-    summary: "Refuse unless it is still at this version. Read it first to get the ETag.",
+    summary: "Only change it if nobody else has since you read it. The ETag comes from the read command.",
     value: "<etag>",
 };
 const IDEMPOTENCY = {
     flag: "--idempotency-key",
-    summary: "Make a repeat of this exact request a replay rather than a second.",
+    summary: "Any unique string. The command makes one up and prints it if you leave it out. Repeat it to retry safely: it runs once.",
     value: "<key>",
 };
 /* -------------------------------------------------------------------------- */
@@ -123,6 +123,137 @@ const IDEMPOTENCY = {
  * around, set up a destination, schedule something, watch it, then recover from
  * it. The groups are the headings.
  */
+const MEMBER = {
+    name: "<member>",
+    summary: "The member's id, starting mem_, from members list.",
+};
+const INVITATION = {
+    name: "<invitation>",
+    summary: "The invitation's id, starting inv_, from invitations list.",
+};
+const PROJECT = {
+    name: "<project>",
+    summary: "The project's id, starting proj_, from whoami or members list.",
+};
+const MEMBER_RETRY_KEY = {
+    flag: "--idempotency-key",
+    summary: "Any unique string. The command makes one up and prints it if you leave it out. Repeat it to retry safely: the change happens once.",
+    value: "<key>",
+};
+/**
+ * The organization's people (W1-09). Listed after the project commands in
+ * help and in the reference, because managing who can see a project comes
+ * after having one.
+ */
+export const MEMBER_COMMANDS = [
+    {
+        words: "members list",
+        group: "Members",
+        summary: "List the organization's members and the projects each can see.",
+        operations: ["members.list"],
+        positionals: [],
+        options: [API_URL],
+    },
+    {
+        words: "invitations list",
+        group: "Members",
+        summary: "List invitations, and whether each is pending, accepted, revoked or expired.",
+        operations: ["invitations.list"],
+        positionals: [],
+        options: [API_URL],
+    },
+    {
+        words: "invitations create",
+        group: "Members",
+        summary: "Invite someone to the organization by email.",
+        operations: ["invitations.create"],
+        positionals: [],
+        options: [
+            API_URL,
+            {
+                flag: "--email",
+                summary: "The address to send the invitation to.",
+                value: "<address>",
+            },
+            {
+                flag: "--role",
+                summary: "admin or member. Defaults to member. Admins can see every project and manage people.",
+                value: "<role>",
+            },
+            {
+                flag: "--projects",
+                summary: "The projects a member can see, as ids starting proj_, separated by commas. Not needed for admins, who see every project.",
+                value: "<ids>",
+            },
+            MEMBER_RETRY_KEY,
+            CONFIRM,
+        ],
+        confirms: true,
+    },
+    {
+        words: "invitations resend",
+        group: "Members",
+        summary: "Send a pending invitation's email again.",
+        operations: ["invitations.resend"],
+        positionals: [INVITATION],
+        options: [API_URL, MEMBER_RETRY_KEY, CONFIRM],
+        confirms: true,
+    },
+    {
+        words: "invitations revoke",
+        group: "Members",
+        summary: "Cancel a pending invitation, so its link stops working.",
+        operations: ["invitations.revoke"],
+        positionals: [INVITATION],
+        options: [API_URL, MEMBER_RETRY_KEY, CONFIRM],
+        confirms: true,
+    },
+    {
+        words: "members role",
+        group: "Members",
+        summary: "Make a member an admin, or an admin a member.",
+        operations: ["members.role"],
+        positionals: [MEMBER],
+        options: [
+            API_URL,
+            {
+                flag: "--role",
+                summary: "The new role: admin or member. Admins can see every project and manage people.",
+                value: "<role>",
+            },
+            MEMBER_RETRY_KEY,
+            CONFIRM,
+        ],
+        confirms: true,
+    },
+    {
+        words: "members remove",
+        group: "Members",
+        summary: "Remove someone from the organization.",
+        operations: ["members.remove"],
+        positionals: [MEMBER],
+        options: [API_URL, MEMBER_RETRY_KEY, CONFIRM],
+        confirms: true,
+    },
+    {
+        words: "members add-project",
+        group: "Members",
+        summary: "Let a member see a project.",
+        operations: ["projectmembers.add"],
+        positionals: [MEMBER, PROJECT],
+        options: [API_URL, MEMBER_RETRY_KEY, CONFIRM],
+        confirms: true,
+    },
+    {
+        words: "members remove-project",
+        group: "Members",
+        summary: "Stop a member seeing a project.",
+        operations: ["projectmembers.remove"],
+        positionals: [MEMBER, PROJECT],
+        options: [API_URL, MEMBER_RETRY_KEY, CONFIRM],
+        confirms: true,
+    },
+];
 export const COMMAND_CATALOG = [
     /* --- Session ---------------------------------------------------------- */
     {
@@ -132,11 +263,11 @@ export const COMMAND_CATALOG = [
             API_URL,
             {
                 flag: "--api-key",
-                summary: "Sign in with a scoped API credential instead of a browser. Takes no value: paste it when asked, or pipe it in.",
+                summary: "Sign in with an API key instead of a browser. Paste it when asked, or pipe it in. Create one on the dashboard's Access page.",
             },
             {
                 flag: "--no-browser",
-                summary: "Print the authorization address instead of opening it.",
+                summary: "Print the sign-in address instead of opening a browser, for a machine without one.",
             },
             {
                 // **A way to ask for less than the whole command line can do.** The
@@ -146,12 +277,12 @@ export const COMMAND_CATALOG = [
                 // there. Narrowing is safe in the direction that matters: a command
                 // outside the grant is refused by the service.
                 flag: "--scope",
-                summary: "Ask for these permissions instead of everything the commands can use, separated by spaces in one argument.",
+                summary: 'Ask for fewer permissions than every command needs, such as "schedules:read schedules:write". One argument, separated by spaces.',
                 value: "<scopes>",
             },
         ],
         positionals: [],
-        summary: "Sign in to a GreatWait service and remember the credential.",
+        summary: "Sign in, in a browser or with an API key, and stay signed in.",
         words: "login",
     },
     {
@@ -159,7 +290,7 @@ export const COMMAND_CATALOG = [
         operations: [],
         options: [API_URL],
         positionals: [],
-        summary: "Revoke the grant where possible and remove the local material.",
+        summary: "Sign out, and forget the credential stored on this machine.",
         words: "logout",
     },
     {
@@ -167,7 +298,7 @@ export const COMMAND_CATALOG = [
         operations: ["context.read"],
         options: [API_URL],
         positionals: [],
-        summary: "Report which service, project and environment this acts in.",
+        summary: "Show which service, project and environment commands act in.",
         words: "whoami",
     },
     {
@@ -175,7 +306,7 @@ export const COMMAND_CATALOG = [
         operations: ["meta.version", "context.read"],
         options: [API_URL],
         positionals: [],
-        summary: "Check the service, the stored configuration and the credential.",
+        summary: "Check that the service answers and the stored sign-in still works.",
         words: "doctor",
     },
     {
@@ -186,10 +317,10 @@ export const COMMAND_CATALOG = [
             {
                 name: "[list | use <origin>]",
                 optional: true,
-                summary: "Show the signed-in services, or select one.",
+                summary: "list shows the services you're signed in to. use picks one by its address.",
             },
         ],
-        summary: "Show or choose the service later commands go to.",
+        summary: "Show or choose which service commands go to.",
         words: "context",
     },
     {
@@ -197,7 +328,7 @@ export const COMMAND_CATALOG = [
         operations: [],
         options: [API_URL],
         positionals: [],
-        summary: "Print the published first-value sequence and its commands.",
+        summary: "Print the steps from signing in to a delivered call, with the command for each.",
         words: "journey",
     },
     /* --- Destinations ----------------------------------------------------- */
@@ -206,7 +337,7 @@ export const COMMAND_CATALOG = [
         operations: ["endpoints.list"],
         options: [API_URL, ...PAGE_OPTIONS],
         positionals: [],
-        summary: "List the destinations this project delivers to.",
+        summary: "List the addresses this project calls.",
         words: "destinations list",
     },
     {
@@ -214,24 +345,32 @@ export const COMMAND_CATALOG = [
         operations: ["endpoints.read"],
         options: [API_URL],
         positionals: [
-            { name: "<destination>", summary: "The destination to read." },
+            {
+                name: "<destination>",
+                summary: "The destination's id, starting ep_, from destinations list or create.",
+            },
         ],
-        summary: "Read one destination, its status and its signing keys.",
+        summary: "Show one destination: its address, status and signing keys.",
         words: "destinations read",
     },
     {
         group: "Destinations",
         operations: ["endpoints.create"],
         options: [
+            {
+                flag: "--headers",
+                summary: "Headers to send with every call, from @file.json or - for standard input. Keeps secret values out of your shell history.",
+                value: "<@file|->",
+            },
             API_URL,
             {
                 flag: "--url",
-                summary: "The https receiver GreatWait will deliver to.",
+                summary: "The https address to call.",
                 value: "<https url>",
             },
         ],
         positionals: [],
-        summary: "Create a destination and print its signing key once.",
+        summary: "Add an address to call, and print its signing secret. This is the only time it's printed.",
         words: "destinations create",
     },
     {
@@ -239,19 +378,27 @@ export const COMMAND_CATALOG = [
         group: "Destinations",
         operations: ["endpoints.update"],
         options: [
+            {
+                flag: "--headers",
+                summary: "Headers to send with every call, from @file.json or - for standard input. Keeps secret values out of your shell history.",
+                value: "<@file|->",
+            },
             API_URL,
             {
                 flag: "--url",
-                summary: "The new https receiver.",
+                summary: "The new https address to call.",
                 value: "<https url>",
             },
             IF_MATCH,
             CONFIRM,
         ],
         positionals: [
-            { name: "<destination>", summary: "The destination to change." },
+            {
+                name: "<destination>",
+                summary: "The destination's id, starting ep_, from destinations list or create.",
+            },
         ],
-        summary: "Point a destination at a different receiver.",
+        summary: "Change a destination's address or headers.",
         words: "destinations update",
     },
     {
@@ -266,9 +413,12 @@ export const COMMAND_CATALOG = [
         operations: ["endpoints.rotateSigningKey"],
         options: [API_URL, IF_MATCH, CONFIRM],
         positionals: [
-            { name: "<destination>", summary: "The destination to rotate." },
+            {
+                name: "<destination>",
+                summary: "The destination's id, starting ep_, from destinations list or create.",
+            },
         ],
-        summary: "Mint the next signing key, shown once, with a bounded overlap.",
+        summary: "Make a new signing secret and print it once. The old one keeps working for a while, so your receiver can switch over.",
         words: "destinations rotate-key",
     },
     {
@@ -280,9 +430,12 @@ export const COMMAND_CATALOG = [
         operations: ["endpoints.disable"],
         options: [API_URL, CONFIRM],
         positionals: [
-            { name: "<destination>", summary: "The destination to disable." },
+            {
+                name: "<destination>",
+                summary: "The destination's id, starting ep_, from destinations list or create.",
+            },
         ],
-        summary: "Stop delivering to a destination, keeping its history readable.",
+        summary: "Stop calling a destination. Its history stays readable.",
         words: "destinations disable",
     },
     {
@@ -293,9 +446,12 @@ export const COMMAND_CATALOG = [
         operations: ["endpoints.enable"],
         options: [API_URL],
         positionals: [
-            { name: "<destination>", summary: "The destination to turn back on." },
+            {
+                name: "<destination>",
+                summary: "The destination's id, starting ep_, from destinations list or create.",
+            },
         ],
-        summary: "Resume delivering to a destination that was disabled.",
+        summary: "Start calling a disabled destination again.",
         words: "destinations enable",
     },
     /* --- Schedules -------------------------------------------------------- */
@@ -306,21 +462,26 @@ export const COMMAND_CATALOG = [
             API_URL,
             {
                 flag: "--endpoint",
-                summary: "Only the schedules that deliver to this destination — everything pointed at it, in one listing.",
+                summary: "Only the schedules that call this destination. Its id starts ep_.",
                 value: "<destination>",
             },
             ...PAGE_OPTIONS,
         ],
         positionals: [],
-        summary: "List this project's schedules, or those delivering to one destination.",
+        summary: "List this project's schedules.",
         words: "schedules list",
     },
     {
         group: "Schedules",
         operations: ["schedules.read"],
         options: [API_URL],
-        positionals: [{ name: "<schedule>", summary: "The schedule to read." }],
-        summary: "Read a schedule, its recurrence, its version and its ETag.",
+        positionals: [
+            {
+                name: "<schedule>",
+                summary: "The schedule's id, starting sch_, from schedules create or schedules list.",
+            },
+        ],
+        summary: "Show a schedule: when it runs, its status, and the ETag for a safe change.",
         words: "schedules read",
     },
     {
@@ -330,53 +491,77 @@ export const COMMAND_CATALOG = [
             API_URL,
             {
                 flag: "--endpoint",
-                summary: "The destination to deliver to.",
+                summary: "The destination to call, by id, starting ep_. Or use --url instead.",
                 value: "<destination>",
             },
+            {
+                flag: "--url",
+                summary: "The https address to call. Uses this project's destination there, or adds one.",
+                value: "<https url>",
+            },
             {
                 flag: "--in",
-                summary: "Once, after a delay: 30s, 5m, 2h, 1d.",
+                summary: "Call once, after this long: 30s, 5m, 2h or 1d.",
                 value: "<duration>",
             },
             {
                 flag: "--at",
-                summary: "Once, at an instant in UTC.",
+                summary: "Call once, at this time, such as 2026-10-06T09:00:00Z.",
                 value: "<instant>",
             },
             {
                 flag: "--every",
-                summary: "Repeatedly, at this interval: 30s, 5m, 2h, 1d.",
+                summary: "Call repeatedly, this far apart: 30s, 5m, 2h or 1d.",
                 value: "<duration>",
             },
             {
                 flag: "--cron",
-                summary: "Repeatedly, on a cron expression.",
+                summary: 'Call repeatedly, on a cron expression such as "0 9 * * 1-5" (9:00, Monday to Friday).',
                 value: "<expression>",
             },
             {
                 flag: "--time-zone",
-                summary: "The zone a cron expression is read in, so daylight saving moves the local time rather than the clock time. IANA names, such as Europe/London.",
+                summary: "The time zone --cron runs in, such as Europe/London, so 9:00 stays 9:00 through daylight saving. Defaults to UTC.",
                 value: "<zone>",
             },
             {
                 flag: "--partition-key",
-                summary: "The fairness partition this belongs to.",
+                summary: "Your own label, such as a customer id. Each label is paced on its own, so one busy label can't hold up the rest. Can't be changed later.",
                 value: "<key>",
             },
+            {
+                flag: "--auto-pause-after-failures",
+                summary: 'Pause a recurring schedule after 1–100 consecutive failed runs, or "never". Defaults to 5 on create; omission on replace keeps the setting. Resume resets the count.',
+                value: "<count|never>",
+            },
             {
                 flag: "--latency-class",
-                summary: "How promptly it must fire: realtime or bulk.",
+                summary: "realtime or bulk. realtime goes first when both are due. By default a call due within two minutes is realtime, and a repeating one is bulk.",
                 value: "<class>",
             },
+            {
+                flag: "--http",
+                summary: "The call's method, body and headers, from @file.json or - for standard input. Keeps secret values out of your shell history.",
+                value: "<@file|->",
+            },
             {
                 flag: "--data",
-                summary: "The payload: JSON, @file.json, or - for standard input.",
+                summary: "JSON your receiver gets with the call. Inline, @file.json, or - for standard input.",
                 value: "<json>",
             },
             IDEMPOTENCY,
+            {
+                flag: "--wait",
+                summary: "Wait for the first call and print how it went: delivered, or why not.",
+            },
+            {
+                flag: "--timeout",
+                summary: "How long --wait waits, such as 30s or 5m. Defaults to 3m.",
+                value: "<duration>",
+            },
         ],
         positionals: [],
-        summary: "Schedule a delivery, once or repeatedly, and print the first occurrence.",
+        summary: "Schedule a call to an address, once or repeatedly. Prints the first call's id.",
         words: "schedules create",
     },
     {
@@ -387,70 +572,100 @@ export const COMMAND_CATALOG = [
             API_URL,
             {
                 flag: "--endpoint",
-                summary: "The destination to deliver to.",
+                summary: "The destination to call, by id, starting ep_. Or use --url instead.",
                 value: "<destination>",
             },
+            {
+                flag: "--url",
+                summary: "The https address to call. Uses this project's destination there, or adds one.",
+                value: "<https url>",
+            },
             {
                 flag: "--in",
-                summary: "Once, after a delay: 30s, 5m, 2h, 1d.",
+                summary: "Call once, after this long: 30s, 5m, 2h or 1d.",
                 value: "<duration>",
             },
             {
                 flag: "--at",
-                summary: "Once, at an instant in UTC.",
+                summary: "Call once, at this time, such as 2026-10-06T09:00:00Z.",
                 value: "<instant>",
             },
             {
                 flag: "--every",
-                summary: "Repeatedly, at this interval: 30s, 5m, 2h, 1d.",
+                summary: "Call repeatedly, this far apart: 30s, 5m, 2h or 1d.",
                 value: "<duration>",
             },
             {
                 flag: "--cron",
-                summary: "Repeatedly, on a cron expression.",
+                summary: 'Call repeatedly, on a cron expression such as "0 9 * * 1-5" (9:00, Monday to Friday).',
                 value: "<expression>",
             },
             {
                 flag: "--time-zone",
-                summary: "The zone a cron expression is read in, so daylight saving moves the local time rather than the clock time. IANA names, such as Europe/London.",
+                summary: "The time zone --cron runs in, such as Europe/London, so 9:00 stays 9:00 through daylight saving. Defaults to UTC.",
                 value: "<zone>",
             },
             {
                 flag: "--partition-key",
-                summary: "The fairness partition this belongs to.",
+                summary: "Your own label, such as a customer id. Each label is paced on its own, so one busy label can't hold up the rest. Can't be changed later.",
                 value: "<key>",
             },
+            {
+                flag: "--auto-pause-after-failures",
+                summary: 'Pause a recurring schedule after 1–100 consecutive failed runs, or "never". Defaults to 5 on create; omission on replace keeps the setting. Resume resets the count.',
+                value: "<count|never>",
+            },
             {
                 flag: "--latency-class",
-                summary: "How promptly it must fire: realtime or bulk.",
+                summary: "realtime or bulk. realtime goes first when both are due. By default a call due within two minutes is realtime, and a repeating one is bulk.",
                 value: "<class>",
             },
+            {
+                flag: "--http",
+                summary: "The call's method, body and headers, from @file.json or - for standard input. Keeps secret values out of your shell history.",
+                value: "<@file|->",
+            },
             {
                 flag: "--data",
-                summary: "The payload: JSON, @file.json, or - for standard input.",
+                summary: "JSON your receiver gets with the call. Inline, @file.json, or - for standard input.",
                 value: "<json>",
             },
             IF_MATCH,
             CONFIRM,
         ],
-        positionals: [{ name: "<schedule>", summary: "The schedule to replace." }],
-        summary: "Replace a schedule's definition, discarding what it said before.",
+        positionals: [
+            {
+                name: "<schedule>",
+                summary: "The schedule's id, starting sch_, from schedules create or schedules list.",
+            },
+        ],
+        summary: "Change when a schedule runs. Its destination, data and HTTP settings stay unless you give new ones.",
         words: "schedules replace",
     },
     {
         group: "Schedules",
         operations: ["schedules.pause"],
         options: [API_URL, IF_MATCH],
-        positionals: [{ name: "<schedule>", summary: "The schedule to pause." }],
-        summary: "Stop firing a schedule without discarding it.",
+        positionals: [
+            {
+                name: "<schedule>",
+                summary: "The schedule's id, starting sch_, from schedules create or schedules list.",
+            },
+        ],
+        summary: "Stop a schedule's calls until you resume it.",
         words: "schedules pause",
     },
     {
         group: "Schedules",
         operations: ["schedules.resume"],
         options: [API_URL, IF_MATCH],
-        positionals: [{ name: "<schedule>", summary: "The schedule to resume." }],
-        summary: "Start a paused schedule firing again.",
+        positionals: [
+            {
+                name: "<schedule>",
+                summary: "The schedule's id, starting sch_, from schedules create or schedules list.",
+            },
+        ],
+        summary: "Start a paused schedule's calls again.",
         words: "schedules resume",
     },
     {
@@ -458,16 +673,26 @@ export const COMMAND_CATALOG = [
         group: "Schedules",
         operations: ["schedules.cancel"],
         options: [API_URL, IF_MATCH, CONFIRM],
-        positionals: [{ name: "<schedule>", summary: "The schedule to cancel." }],
-        summary: "Cancel a schedule and everything it had still to deliver.",
+        positionals: [
+            {
+                name: "<schedule>",
+                summary: "The schedule's id, starting sch_, from schedules create or schedules list.",
+            },
+        ],
+        summary: "Cancel a schedule and every call it hadn't made yet.",
         words: "schedules cancel",
     },
     {
         group: "Schedules",
         operations: ["schedules.archive"],
         options: [API_URL, IF_MATCH],
-        positionals: [{ name: "<schedule>", summary: "The schedule to archive." }],
-        summary: "Move a settled schedule out of the working list.",
+        positionals: [
+            {
+                name: "<schedule>",
+                summary: "The schedule's id, starting sch_, from schedules create or schedules list.",
+            },
+        ],
+        summary: "File a finished or cancelled schedule out of schedules list. It stays readable by id.",
         words: "schedules archive",
     },
     /* --- Data exports ---------------------------------------------------- */
@@ -476,23 +701,33 @@ export const COMMAND_CATALOG = [
         operations: ["exports.create"],
         options: [API_URL],
         positionals: [],
-        summary: "Start a bounded export for this project and environment.",
+        summary: "Start exporting this project's records, as NDJSON files.",
         words: "exports create",
     },
     {
         group: "Data exports",
         operations: ["exports.read"],
         options: [API_URL],
-        positionals: [{ name: "<export>", summary: "The export job to read." }],
-        summary: "Read an export job's progress and cutoff.",
+        positionals: [
+            {
+                name: "<export>",
+                summary: "The export's id, starting exp_, from exports create.",
+            },
+        ],
+        summary: "Show how far an export has got, and the time its data runs up to.",
         words: "exports read",
     },
     {
         group: "Data exports",
         operations: ["exports.part"],
         options: [API_URL, PAGE_OPTIONS[0]],
-        positionals: [{ name: "<export>", summary: "The export job to download." }],
-        summary: "Print one bounded NDJSON export part for safe redirection to a file.",
+        positionals: [
+            {
+                name: "<export>",
+                summary: "The export's id, starting exp_, from exports create.",
+            },
+        ],
+        summary: "Print one part of a finished export. Redirect it to a file: > export.ndjson.",
         words: "exports part",
     },
     {
@@ -500,8 +735,13 @@ export const COMMAND_CATALOG = [
         group: "Data exports",
         operations: ["exports.cancel"],
         options: [API_URL, CONFIRM],
-        positionals: [{ name: "<export>", summary: "The export job to cancel." }],
-        summary: "Permanently cancel an export job.",
+        positionals: [
+            {
+                name: "<export>",
+                summary: "The export's id, starting exp_, from exports create.",
+            },
+        ],
+        summary: "Cancel an export. Its parts can't be downloaded afterwards.",
         words: "exports cancel",
     },
     /* --- Occurrences and attempts ----------------------------------------- */
@@ -513,11 +753,16 @@ export const COMMAND_CATALOG = [
             ...PAGE_OPTIONS,
             {
                 flag: "--newest",
-                summary: "Newest first, which is what a person looking at a schedule wants. A cursor belongs to the order it was issued under.",
+                summary: "Newest first. Use the same order when you carry on with --cursor.",
+            },
+        ],
+        positionals: [
+            {
+                name: "<schedule>",
+                summary: "The schedule's id, starting sch_, from schedules create or schedules list.",
             },
         ],
-        positionals: [{ name: "<schedule>", summary: "The schedule to list." }],
-        summary: "List the retained occurrences of a schedule.",
+        summary: "List a schedule's calls, one for each time it ran or will run.",
         words: "occurrences list",
     },
     {
@@ -525,10 +770,16 @@ export const COMMAND_CATALOG = [
         operations: ["occurrences.read"],
         options: [API_URL],
         positionals: [
-            { name: "<schedule>", summary: "The schedule it belongs to." },
-            { name: "<occurrence>", summary: "The occurrence to read." },
+            {
+                name: "<schedule>",
+                summary: "The schedule's id, starting sch_, from schedules create or schedules list.",
+            },
+            {
+                name: "<occurrence>",
+                summary: "The call's id, starting occ_, from schedules create or occurrences list.",
+            },
         ],
-        summary: "Read one occurrence and the state it is in.",
+        summary: "Show one call and where it's got to.",
         words: "occurrences read",
     },
     {
@@ -538,15 +789,21 @@ export const COMMAND_CATALOG = [
             API_URL,
             {
                 flag: "--timeout",
-                summary: "Give up after this long instead of the published deadline.",
+                summary: "How long to wait, such as 30s or 5m. Defaults to 3m.",
                 value: "<duration>",
             },
         ],
         positionals: [
-            { name: "<schedule>", summary: "The schedule it belongs to." },
-            { name: "<occurrence>", summary: "The occurrence to wait for." },
+            {
+                name: "<schedule>",
+                summary: "The schedule's id, starting sch_, from schedules create or schedules list.",
+            },
+            {
+                name: "<occurrence>",
+                summary: "The call's id, starting occ_, from schedules create or occurrences list.",
+            },
         ],
-        summary: "Watch an occurrence until it settles, or until the deadline.",
+        summary: "Wait for a call to finish, then print how it went. Gives up after 3m unless --timeout says otherwise.",
         words: "occurrences wait",
     },
     {
@@ -555,10 +812,16 @@ export const COMMAND_CATALOG = [
         operations: ["occurrences.redeliver"],
         options: [API_URL, IDEMPOTENCY, CONFIRM],
         positionals: [
-            { name: "<schedule>", summary: "The schedule it belongs to." },
-            { name: "<occurrence>", summary: "The occurrence to send again." },
+            {
+                name: "<schedule>",
+                summary: "The schedule's id, starting sch_, from schedules create or schedules list.",
+            },
+            {
+                name: "<occurrence>",
+                summary: "The call's id, starting occ_, from schedules create or occurrences list.",
+            },
         ],
-        summary: "Deliver an occurrence again to the destination it belongs to.",
+        summary: "Make a call again, to the same destination.",
         words: "occurrences redeliver",
     },
     {
@@ -566,22 +829,44 @@ export const COMMAND_CATALOG = [
         operations: ["attempts.list"],
         options: [API_URL, ...PAGE_OPTIONS],
         positionals: [
-            { name: "<schedule>", summary: "The schedule it belongs to." },
-            { name: "<occurrence>", summary: "The occurrence to list attempts for." },
+            {
+                name: "<schedule>",
+                summary: "The schedule's id, starting sch_, from schedules create or schedules list.",
+            },
+            {
+                name: "<occurrence>",
+                summary: "The call's id, starting occ_, from schedules create or occurrences list.",
+            },
         ],
-        summary: "List every delivery attempt, with its diagnosis.",
+        summary: "List each try at a call, what your receiver answered, and why a failed one failed.",
         words: "attempts list",
     },
     {
         group: "Occurrences and attempts",
         operations: ["attempts.read"],
-        options: [API_URL],
+        options: [
+            API_URL,
+            {
+                flag: "--response-file",
+                value: "path",
+                summary: "Save the captured response body in a new private file.",
+            },
+        ],
         positionals: [
-            { name: "<schedule>", summary: "The schedule it belongs to." },
-            { name: "<occurrence>", summary: "The occurrence it belongs to." },
-            { name: "<attempt>", summary: "The attempt to read." },
+            {
+                name: "<schedule>",
+                summary: "The schedule's id, starting sch_, from schedules create or schedules list.",
+            },
+            {
+                name: "<occurrence>",
+                summary: "The call's id, starting occ_, from schedules create or occurrences list.",
+            },
+            {
+                name: "<attempt>",
+                summary: "The attempt's id, starting att_, from attempts list.",
+            },
         ],
-        summary: "Read one attempt in full, including what the receiver answered.",
+        summary: "Show one try at a call, including what your receiver answered.",
         words: "attempts read",
     },
     /* --- Planning --------------------------------------------------------- */
@@ -592,27 +877,27 @@ export const COMMAND_CATALOG = [
             API_URL,
             {
                 flag: "--from",
-                summary: "The start of the window, in UTC.",
+                summary: "Where the window starts, such as 2026-10-06T09:00:00Z.",
                 value: "<instant>",
             },
             {
                 flag: "--to",
-                summary: "The end of the window, in UTC.",
+                summary: "Where the window ends, such as 2026-10-06T10:00:00Z.",
                 value: "<instant>",
             },
             {
                 flag: "--bucket",
-                summary: "Bucket width in seconds.",
+                summary: "How many seconds each count covers.",
                 value: "<seconds>",
             },
             {
                 flag: "--breakdown",
-                summary: "Group the counts by this dimension.",
+                summary: "partitionKey to split the counts by label, or none.",
                 value: "<dimension>",
             },
         ],
         positionals: [],
-        summary: "Show what is due in a window, and how fresh the answer is.",
+        summary: "Show how many calls are due in a window of time.",
         words: "forecast",
     },
     {
@@ -620,7 +905,7 @@ export const COMMAND_CATALOG = [
         operations: ["limits.read"],
         options: [API_URL],
         positionals: [],
-        summary: "Show the verified organization's effective allowances and policy revisions.",
+        summary: "Show the limits that apply to your organization.",
         words: "limits show",
     },
     {
@@ -628,11 +913,19 @@ export const COMMAND_CATALOG = [
         operations: ["usage.read"],
         options: [
             API_URL,
-            { flag: "--from", summary: "The first day, in UTC.", value: "<instant>" },
-            { flag: "--to", summary: "The last day, in UTC.", value: "<instant>" },
+            {
+                flag: "--from",
+                summary: "The first day, such as 2026-10-01. Days are UTC.",
+                value: "<instant>",
+            },
+            {
+                flag: "--to",
+                summary: "The last day, such as 2026-10-06. Days are UTC.",
+                value: "<instant>",
+            },
         ],
         positionals: [],
-        summary: "Show terminal occurrence volume by day.",
+        summary: "Show how many calls finished each day. For what you're billed, use billing ledger.",
         words: "usage",
     },
     {
@@ -640,7 +933,7 @@ export const COMMAND_CATALOG = [
         operations: ["billing.summary"],
         options: [API_URL],
         positionals: [],
-        summary: "Show exact execution credit and effective billing state.",
+        summary: "Show your execution credit and billing status.",
         words: "billing",
     },
     {
@@ -648,7 +941,7 @@ export const COMMAND_CATALOG = [
         operations: ["billing.funding"],
         options: [API_URL],
         positionals: [],
-        summary: "Show execution funding, automatic payment authority and payment outcomes.",
+        summary: "Show how execution credit is funded: automatic top-up, your monthly ceiling, and recent payments.",
         words: "billing funding",
     },
     {
@@ -656,7 +949,7 @@ export const COMMAND_CATALOG = [
         operations: ["billing.notices"],
         options: [API_URL, ...PAGE_OPTIONS],
         positionals: [],
-        summary: "List persistent organization billing notices and delivery state.",
+        summary: "List billing notices, such as low credit, and whether each was emailed.",
         words: "billing notices",
     },
     {
@@ -664,7 +957,7 @@ export const COMMAND_CATALOG = [
         operations: ["billing.notificationsettings"],
         options: [API_URL],
         positionals: [],
-        summary: "Show billing notification policy and its revision.",
+        summary: "Show which billing emails you get, and when.",
         words: "billing notification-settings",
     },
     {
@@ -675,24 +968,24 @@ export const COMMAND_CATALOG = [
             API_URL,
             {
                 flag: "--low-credit",
-                summary: "Send the low-credit notice below this exact USD amount, or auto for a fifth of the latest grant; omit to keep it.",
+                summary: "Warn when credit falls below this many dollars, or auto for a fifth of your last top-up. Leave it out to keep the current setting.",
                 value: "<dollars|auto>",
             },
             {
                 flag: "--noncritical-email",
-                summary: "Enable or disable email for noncritical notices.",
+                summary: "on or off: email for notices that need no action.",
                 value: "<on|off>",
             },
             {
                 flag: "--expected-revision",
-                summary: "Refuse if notification settings have changed.",
+                summary: "Only change it if nobody else has since you read it. The revision comes from billing notification-settings.",
                 value: "<revision>",
             },
             IDEMPOTENCY,
             CONFIRM,
         ],
         positionals: [],
-        summary: "Update optional billing notifications with approval.",
+        summary: "Change which billing emails you get.",
         words: "billing update-notifications",
     },
     {
@@ -702,12 +995,12 @@ export const COMMAND_CATALOG = [
             API_URL,
             {
                 flag: "--credit",
-                summary: "Execution credit to buy in USD, at least 10.",
+                summary: "How many dollars of credit to buy. At least 10.",
                 value: "<dollars>",
             },
         ],
         positionals: [],
-        summary: "Preview manual execution funding before tax is calculated at checkout.",
+        summary: "Price a credit purchase before you buy. Tax is added at checkout.",
         words: "billing quote-funding",
     },
     {
@@ -718,14 +1011,14 @@ export const COMMAND_CATALOG = [
             API_URL,
             {
                 flag: "--quote",
-                summary: "The exact object returned by quote-funding (the data field in JSON output).",
+                summary: "The quote from billing quote-funding --json: its data field, inline, @file.json, or - for standard input.",
                 value: "<json|@file|->",
             },
             IDEMPOTENCY,
             CONFIRM,
         ],
         positionals: [],
-        summary: "Confirm a manual execution-credit purchase with a stable retry key.",
+        summary: "Buy the credit a quote priced, and print the link to pay.",
         words: "billing purchase",
     },
     {
@@ -736,19 +1029,19 @@ export const COMMAND_CATALOG = [
             API_URL,
             {
                 flag: "--ceiling",
-                summary: "Set the UTC-month automatic payment ceiling in USD, or turn it off.",
+                summary: "The most automatic payments may charge in a calendar month, in dollars, or off.",
                 value: "<dollars|off>",
             },
             {
                 flag: "--expected-revision",
-                summary: "Refuse if automatic payment authority has changed.",
+                summary: "Only change it if nobody else has since you read it. The revision comes from billing funding.",
                 value: "<revision>",
             },
             IDEMPOTENCY,
             CONFIRM,
         ],
         positionals: [],
-        summary: "Set exact automatic payment authority with approval.",
+        summary: "Set the most automatic payments may charge each month.",
         words: "billing ceiling",
     },
     {
@@ -758,32 +1051,32 @@ export const COMMAND_CATALOG = [
             API_URL,
             {
                 flag: "--action",
-                summary: "Preview enabling, editing, disabling or resuming the rule.",
+                summary: "What to preview: enable, edit, disable or resume.",
                 value: "<enable|edit|disable|resume>",
             },
             {
                 flag: "--credit",
-                summary: "Fixed execution credit purchased by enable or edit, in USD.",
+                summary: "How many dollars of credit each top-up buys.",
                 value: "<dollars>",
             },
             {
                 flag: "--trigger-below",
-                summary: "Trigger when usable execution credit is below this USD amount.",
+                summary: "Top up when credit falls below this many dollars.",
                 value: "<dollars>",
             },
             {
                 flag: "--ceiling",
-                summary: "Gross automatic-payment ceiling per UTC month, in USD.",
+                summary: "The most top-ups may charge in a calendar month, in dollars.",
                 value: "<dollars>",
             },
             {
                 flag: "--expected-revision",
-                summary: "Refuse if automatic payment authority has changed.",
+                summary: "Only change it if nobody else has since you read it. The revision comes from billing funding.",
                 value: "<revision>",
             },
         ],
         positionals: [],
-        summary: "Preview one exact automatic top-up rule without enabling it.",
+        summary: "Preview an automatic top-up change. Nothing changes until billing apply-topup.",
         words: "billing preview-topup",
     },
     {
@@ -794,14 +1087,14 @@ export const COMMAND_CATALOG = [
             API_URL,
             {
                 flag: "--preview",
-                summary: "The exact object returned by preview-topup (the data field in JSON output).",
+                summary: "The preview from billing preview-topup --json: its data field, inline, @file.json, or - for standard input.",
                 value: "<json|@file|->",
             },
             IDEMPOTENCY,
             CONFIRM,
         ],
         positionals: [],
-        summary: "Confirm an automatic top-up preview with a stable retry key.",
+        summary: "Turn on, change or stop automatic top-up, as a preview described.",
         words: "billing apply-topup",
     },
     {
@@ -812,24 +1105,24 @@ export const COMMAND_CATALOG = [
             API_URL,
             {
                 flag: "--payment-operation",
-                summary: "The paid funding operation to review.",
+                summary: "The payment to refund from, from billing payment-history.",
                 value: "<operation>",
             },
             {
                 flag: "--amount",
-                summary: "Unused purchased credit requested in USD.",
+                summary: "How many dollars of unused credit to refund.",
                 value: "<dollars>",
             },
             {
                 flag: "--reason",
-                summary: "Why the credit is reserved for refund.",
+                summary: "Why you're asking for the refund.",
                 value: "<text>",
             },
             IDEMPOTENCY,
             CONFIRM,
         ],
         positionals: [],
-        summary: "Reserve unused purchased credit against a payment for refund.",
+        summary: "Ask for unused credit back. The credit is held until the refund is decided.",
         words: "billing refund-request",
     },
     {
@@ -840,34 +1133,34 @@ export const COMMAND_CATALOG = [
             API_URL,
             {
                 flag: "--refund-request",
-                summary: "The pending refund reservation to complete or decline.",
+                summary: "The refund request to decide, from billing refund-request.",
                 value: "<request>",
             },
             {
                 flag: "--decision",
-                summary: "Complete with an existing Stripe refund, or release the reservation.",
+                summary: "completed, for a refund already made in Stripe, or declined, which releases the held credit.",
                 value: "<completed|declined>",
             },
             {
                 flag: "--provider-refund",
-                summary: "Existing Stripe refund ID required for completion.",
+                summary: "The Stripe refund's id, starting re_. Needed for completed.",
                 value: "<re_...>",
             },
             {
                 flag: "--gross",
-                summary: "Existing provider refund gross amount in USD.",
+                summary: "The Stripe refund's total, in dollars.",
                 value: "<dollars>",
             },
             {
                 flag: "--tax",
-                summary: "Tax included in the existing provider refund in USD.",
+                summary: "The tax within that total, in dollars.",
                 value: "<dollars>",
             },
             IDEMPOTENCY,
             CONFIRM,
         ],
         positionals: [],
-        summary: "Record a completed or declined external refund review.",
+        summary: "Record whether a refund request was paid in Stripe or declined.",
         words: "billing resolve-refund",
     },
     {
@@ -878,24 +1171,24 @@ export const COMMAND_CATALOG = [
             API_URL,
             {
                 flag: "--advisory-budget",
-                summary: "Set the monthly advisory amount in USD, or turn it off.",
+                summary: "A monthly amount, in dollars, that warns you when spending passes it, or off.",
                 value: "<dollars|off>",
             },
             {
                 flag: "--hard-cap",
-                summary: "Set the monthly hard cap in USD, or turn it off.",
+                summary: "A monthly amount, in dollars, that stops calls when spending reaches it, or off.",
                 value: "<dollars|off>",
             },
             {
                 flag: "--expected-revision",
-                summary: "Refuse if the budget policy has changed since this revision.",
+                summary: "Only change it if nobody else has since you read it. The revision comes from billing.",
                 value: "<revision>",
             },
             IDEMPOTENCY,
             CONFIRM,
         ],
         positionals: [],
-        summary: "Set exact monthly execution budgets with approval.",
+        summary: "Set a monthly budget that warns you, a cap that stops calls, or both.",
         words: "billing budgets",
     },
     {
@@ -903,7 +1196,7 @@ export const COMMAND_CATALOG = [
         operations: ["billing.projects"],
         options: [API_URL],
         positionals: [],
-        summary: "Show named project access, payment recovery and monthly fees.",
+        summary: "Show each project's monthly fee and whether it's paid up.",
         words: "billing projects",
     },
     {
@@ -913,22 +1206,22 @@ export const COMMAND_CATALOG = [
             API_URL,
             {
                 flag: "--action",
-                summary: "Preview an addition, cancellation or included transfer.",
+                summary: "add a paid project, cancel one, or transfer-included to move your included project.",
                 value: "<add|cancel|transfer-included>",
             },
             {
                 flag: "--target-project",
-                summary: "The named project whose billing changes.",
+                summary: "The project's id, starting proj_, from billing projects.",
                 value: "<project>",
             },
             {
                 flag: "--from-project",
-                summary: "The former included project for a transfer.",
+                summary: "For transfer-included, the project that's included now.",
                 value: "<project>",
             },
         ],
         positionals: [],
-        summary: "Preview a named project billing change without authorizing payment.",
+        summary: "Price a change to which projects you pay for. Nothing changes until billing change-project.",
         words: "billing quote-project",
     },
     {
@@ -939,14 +1232,14 @@ export const COMMAND_CATALOG = [
             API_URL,
             {
                 flag: "--quote",
-                summary: "The exact quote object returned by quote-project (the data field in JSON output).",
+                summary: "The quote from billing quote-project --json: its data field, inline, @file.json, or - for standard input.",
                 value: "<json|@file|->",
             },
             IDEMPOTENCY,
             CONFIRM,
         ],
         positionals: [],
-        summary: "Confirm an exact project billing quote with a stable retry key.",
+        summary: "Make the project change a quote priced.",
         words: "billing change-project",
     },
     {
@@ -955,7 +1248,7 @@ export const COMMAND_CATALOG = [
         operations: ["billing.portal"],
         options: [API_URL, CONFIRM],
         positionals: [],
-        summary: "Create a hosted payment-method and invoice recovery link.",
+        summary: "Print a link to Stripe's billing portal, to update your card or pay an invoice.",
         words: "billing portal",
     },
     {
@@ -963,7 +1256,7 @@ export const COMMAND_CATALOG = [
         operations: ["billing.paymentmethod"],
         options: [API_URL],
         positionals: [],
-        summary: "Show the saved payment method (a card, Link or another) that automatic top-ups and project subscriptions charge.",
+        summary: "Show the card or other payment method that top-ups and project fees are charged to.",
         words: "billing payment-method",
     },
     {
@@ -971,7 +1264,7 @@ export const COMMAND_CATALOG = [
         operations: ["billing.invoices"],
         options: [API_URL],
         positionals: [],
-        summary: "List project subscription charges, most recent first, with their receipts.",
+        summary: "List recent project fee charges, newest first, with links to their receipts.",
         words: "billing invoices",
     },
     {
@@ -979,7 +1272,7 @@ export const COMMAND_CATALOG = [
         operations: ["billing.paymenthistory"],
         options: [API_URL, ...PAGE_OPTIONS],
         positionals: [],
-        summary: "Read execution-credit payments with continuation to older history.",
+        summary: "List credit purchases and top-ups, newest first.",
         words: "billing payment-history",
     },
     {
@@ -987,7 +1280,7 @@ export const COMMAND_CATALOG = [
         operations: ["billing.invoicehistory"],
         options: [API_URL, ...PAGE_OPTIONS],
         positionals: [],
-        summary: "Read project subscription charges with continuation to older history.",
+        summary: "List every project fee charge, newest first, page by page.",
         words: "billing invoice-history",
     },
     {
@@ -996,7 +1289,7 @@ export const COMMAND_CATALOG = [
         operations: ["billing.paymentmethodsetup"],
         options: [API_URL, CONFIRM],
         positionals: [],
-        summary: "Create a hosted link for adding or replacing the saved payment method.",
+        summary: "Print a link to add a card, or replace the one you have.",
         words: "billing add-card",
     },
     {
@@ -1005,7 +1298,7 @@ export const COMMAND_CATALOG = [
         operations: ["billing.paymentmethodremove"],
         options: [API_URL, CONFIRM],
         positionals: [],
-        summary: "Remove the saved payment method: project subscriptions stop renewing at the end of the paid period, and automatic top-up turns off.",
+        summary: "Remove your saved card. Project fees stop renewing when the paid period ends, and automatic top-up turns off.",
         words: "billing remove-card",
     },
     {
@@ -1013,7 +1306,7 @@ export const COMMAND_CATALOG = [
         operations: ["billing.ledger"],
         options: [API_URL, ...PAGE_OPTIONS],
         positionals: [],
-        summary: "List immutable execution-credit ledger entries.",
+        summary: "List every change to your execution credit: top-ups, charges and refunds.",
         words: "billing ledger",
     },
     {
@@ -1021,7 +1314,7 @@ export const COMMAND_CATALOG = [
         operations: ["timing.summary"],
         options: [API_URL],
         positionals: [],
-        summary: "Show the rolling 24-hour delivery timing cohort.",
+        summary: "Show how close to on time this project's calls were, over the last 24 hours.",
         words: "timing",
     },
     /* --- Credentials ------------------------------------------------------ */
@@ -1030,7 +1323,7 @@ export const COMMAND_CATALOG = [
         operations: ["credentials.list"],
         options: [API_URL, ...PAGE_OPTIONS],
         positionals: [],
-        summary: "List this project's API credentials, by prefix, never in full.",
+        summary: "List this project's API keys. Only the start of each is shown.",
         words: "credentials list",
     },
     {
@@ -1039,9 +1332,12 @@ export const COMMAND_CATALOG = [
         operations: ["credentials.rotate"],
         options: [API_URL, CONFIRM],
         positionals: [
-            { name: "<credential>", summary: "The credential to rotate." },
+            {
+                name: "<credential>",
+                summary: "The key's id, starting ak_, from credentials list.",
+            },
         ],
-        summary: "Mint the replacement for a credential, shown once.",
+        summary: "Make a replacement API key and print it. This is the only time it's printed.",
         words: "credentials rotate",
     },
     {
@@ -1050,11 +1346,16 @@ export const COMMAND_CATALOG = [
         operations: ["credentials.revoke"],
         options: [API_URL, CONFIRM],
         positionals: [
-            { name: "<credential>", summary: "The credential to revoke." },
+            {
+                name: "<credential>",
+                summary: "The key's id, starting ak_, from credentials list.",
+            },
         ],
-        summary: "Stop a credential working, everywhere, immediately.",
+        summary: "Stop an API key working, everywhere, straight away.",
         words: "credentials revoke",
     },
+    /* --- Members ---------------------------------------------------------- */
+    ...MEMBER_COMMANDS,
     /* --- Test sinks ------------------------------------------------------- */
     {
         group: "Test sinks",
@@ -1063,17 +1364,17 @@ export const COMMAND_CATALOG = [
             API_URL,
             {
                 flag: "--endpoint",
-                summary: "The destination whose deliveries this sink stands in for.",
+                summary: "The destination this sink answers for, by id, starting ep_.",
                 value: "<destination>",
             },
             {
                 flag: "--program",
-                summary: "How it should answer from the start: JSON, @file.json, or - for standard input.",
+                summary: 'How it answers calls, such as {"behavior": "server_error"}. Inline, @file.json, or - for standard input.',
                 value: "<json>",
             },
         ],
         positionals: [],
-        summary: "Create a receiver GreatWait hosts, for a test environment only.",
+        summary: "Make a receiver GreatWait runs for you, to test against. Test environments only.",
         words: "sinks create",
     },
     {
@@ -1081,15 +1382,20 @@ export const COMMAND_CATALOG = [
         operations: ["testsinks.list"],
         options: [API_URL, ...PAGE_OPTIONS],
         positionals: [],
-        summary: "List the test sinks in this project.",
+        summary: "List this project's test sinks.",
         words: "sinks list",
     },
     {
         group: "Test sinks",
         operations: ["testsinks.read"],
         options: [API_URL],
-        positionals: [{ name: "<sink>", summary: "The sink to read." }],
-        summary: "Read a test sink and the program it is running.",
+        positionals: [
+            {
+                name: "<sink>",
+                summary: "The sink's id, starting tsk_, from sinks create or sinks list.",
+            },
+        ],
+        summary: "Show a test sink and how it answers calls.",
         words: "sinks read",
     },
     {
@@ -1099,12 +1405,17 @@ export const COMMAND_CATALOG = [
             API_URL,
             {
                 flag: "--program",
-                summary: "The behaviour program: JSON, @file.json, or - for standard input.",
+                summary: 'How it answers calls, such as {"behavior": "server_error"}. Inline, @file.json, or - for standard input.',
                 value: "<json>",
             },
         ],
-        positionals: [{ name: "<sink>", summary: "The sink to program." }],
-        summary: "Tell a test sink how to answer, so a failure can be reproduced.",
+        positionals: [
+            {
+                name: "<sink>",
+                summary: "The sink's id, starting tsk_, from sinks create or sinks list.",
+            },
+        ],
+        summary: "Change how a test sink answers, to reproduce a failure.",
         words: "sinks configure",
     },
     {
@@ -1112,16 +1423,26 @@ export const COMMAND_CATALOG = [
         group: "Test sinks",
         operations: ["testsinks.delete"],
         options: [API_URL, CONFIRM],
-        positionals: [{ name: "<sink>", summary: "The sink to delete." }],
-        summary: "Delete a test sink and the deliveries recorded against it.",
+        positionals: [
+            {
+                name: "<sink>",
+                summary: "The sink's id, starting tsk_, from sinks create or sinks list.",
+            },
+        ],
+        summary: "Delete a test sink and every call it recorded.",
         words: "sinks delete",
     },
     {
         group: "Test sinks",
         operations: ["sinkdeliveries.list"],
         options: [API_URL, ...PAGE_OPTIONS],
-        positionals: [{ name: "<sink>", summary: "The sink to list." }],
-        summary: "List what a test sink received.",
+        positionals: [
+            {
+                name: "<sink>",
+                summary: "The sink's id, starting tsk_, from sinks create or sinks list.",
+            },
+        ],
+        summary: "List the calls a test sink received.",
         words: "sinks deliveries",
     },
     {
@@ -1129,10 +1450,16 @@ export const COMMAND_CATALOG = [
         operations: ["sinkdeliveries.read"],
         options: [API_URL],
         positionals: [
-            { name: "<sink>", summary: "The sink it arrived at." },
-            { name: "<delivery>", summary: "The recorded delivery to read." },
+            {
+                name: "<sink>",
+                summary: "The sink's id, starting tsk_, from sinks create or sinks list.",
+            },
+            {
+                name: "<delivery>",
+                summary: "The recorded call's id, starting tsd_, from sinks deliveries.",
+            },
         ],
-        summary: "Read one recorded delivery, including the bytes that arrived.",
+        summary: "Show one call a test sink received, byte for byte.",
         words: "sinks delivery",
     },
 ];
@@ -1183,6 +1510,11 @@ export const OPERATION_OMISSIONS = [
         ground: "declared",
         operation: "endpoints.acknowledgeSigningKeyRotation",
     },
+    {
+        because: "`greatwait destinations create` already creates a destination and prints its signing key once, which a person at a terminal can keep. The secretless find-or-create exists for agents, whose tool results land in ordinary history (W9-44); a person scheduling to an address uses the dashboard or `destinations create`.",
+        ground: "declared",
+        operation: "endpoints.ensure",
+    },
     {
         because: "Minting a credential needs a signed-in person. A command line holding one credential could otherwise mint another, which is the escalation the control plane refuses by declaring a session principal.",
         ground: "principal-unreachable",