@clickminded/coauthor-cli 0.0.31 → 0.0.33

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1,2 +1,13 @@
1
1
  #!/usr/bin/env node
2
- export declare function main(argv?: string[]): Promise<number>;
2
+ import { type JsonValue } from './client.js';
3
+ export type CliIo = {
4
+ stdout: (text: string) => void;
5
+ stderr: (text: string) => void;
6
+ };
7
+ export declare function main(argv?: string[], io?: CliIo): Promise<number>;
8
+ export declare function formatCliError(error: unknown, baseUrl: string, argv?: string[]): {
9
+ error: Error;
10
+ result?: JsonValue;
11
+ exitCode: number;
12
+ };
13
+ export declare function resolveProjectIdFromArgv(argv: string[]): string | undefined;
package/dist/index.js CHANGED
@@ -1,21 +1,25 @@
1
1
  #!/usr/bin/env node
2
2
  import { readFileSync, realpathSync } from 'node:fs';
3
3
  import { fileURLToPath } from 'node:url';
4
- import { AgentHttpError, AgentClient, normalizeBaseUrl } from './client.js';
4
+ import { AgentHttpError, AgentClient, AgentRequestError, normalizeBaseUrl } from './client.js';
5
5
  import { DEFAULT_BASE_URL, resolveRuntimeConfig } from './config.js';
6
6
  import { helpResult, runCommand } from './commands.js';
7
7
  import { renderError, renderResult } from './output.js';
8
- import { parseCliArgs } from './parser.js';
9
- export async function main(argv = process.argv.slice(2)) {
8
+ import { getString, optionTakesValue, parseCliArgs } from './parser.js';
9
+ const processIo = {
10
+ stdout: (text) => { process.stdout.write(text); },
11
+ stderr: (text) => { process.stderr.write(text); },
12
+ };
13
+ export async function main(argv = process.argv.slice(2), io = processIo) {
10
14
  let resolvedBaseUrl = resolveBaseUrlFromArgv(argv);
11
15
  try {
12
16
  const parsed = parseCliArgs(argv);
13
17
  if (parsed.globals.version || (parsed.command.length === 1 && parsed.command[0] === 'version')) {
14
- process.stdout.write(parsed.globals.json ? `${JSON.stringify({ ok: true, version: cliVersion() })}\n` : `${cliVersion()}\n`);
18
+ io.stdout(parsed.globals.json ? `${JSON.stringify({ ok: true, version: cliVersion() })}\n` : `${cliVersion()}\n`);
15
19
  return 0;
16
20
  }
17
21
  if (parsed.globals.help) {
18
- process.stdout.write(renderResult(helpResult(parsed.command), parsed.globals.json));
22
+ io.stdout(renderResult(helpResult(parsed.command), parsed.globals.json));
19
23
  return 0;
20
24
  }
21
25
  const runtimeConfig = await resolveRuntimeConfig({
@@ -29,51 +33,99 @@ export async function main(argv = process.argv.slice(2)) {
29
33
  baseUrl: runtimeConfig.baseUrl,
30
34
  token: runtimeConfig.token,
31
35
  });
32
- process.stdout.write(renderResult(result, parsed.globals.json));
36
+ // Failures and pauses (ok: false) go to stderr whether they came from a
37
+ // thrown HTTP error or a --wait loop, so callers read one stream for them.
38
+ const output = renderResult(result, parsed.globals.json);
39
+ if (result.ok)
40
+ io.stdout(output);
41
+ else
42
+ io.stderr(output);
33
43
  return result.exitCode ?? (result.ok ? 0 : 1);
34
44
  }
35
45
  catch (error) {
36
46
  const wantsJson = argv.includes('--json');
37
47
  const formatted = formatCliError(error, resolvedBaseUrl, argv);
38
- process.stderr.write(renderError(formatted.result ?? formatted.error, wantsJson));
48
+ io.stderr(wantsJson
49
+ ? renderError(formatted.result ?? formatted.error, true)
50
+ : renderError(formatted.error, false));
39
51
  return formatted.exitCode;
40
52
  }
41
53
  }
42
- function formatCliError(error, baseUrl, argv = []) {
54
+ export function formatCliError(error, baseUrl, argv = []) {
43
55
  if (error instanceof AgentHttpError) {
56
+ // Keep the server's error code and details (e.g. the current draft version
57
+ // on a 409) on every --json error so agents can recover without guessing.
58
+ const envelope = extractEnvelopeError(error.responseBody);
59
+ const errorFields = {
60
+ ...(envelope?.code ? { code: envelope.code } : {}),
61
+ http_status: error.status,
62
+ ...(envelope?.details !== undefined ? { details: envelope.details } : {}),
63
+ ...(error.idempotencyKey ? { idempotency_key: error.idempotencyKey } : {}),
64
+ };
65
+ const operationHint = operationLookupHint(envelope?.details, error.idempotencyKey);
44
66
  const entitlement = formatEntitlementResult(error.responseBody);
45
67
  if (entitlement)
46
- return { error: new Error(entitlement.message), result: entitlement, exitCode: 2 };
68
+ return { error: new Error(entitlement.message), result: { ...entitlement, ...errorFields }, exitCode: 2 };
47
69
  const requiresKey = formatRequiresKeyResult(error.responseBody, baseUrl);
48
70
  if (requiresKey)
49
- return { error: new Error(requiresKey.message), result: requiresKey, exitCode: 2 };
71
+ return { error: new Error(requiresKey.message), result: { ...requiresKey, ...errorFields }, exitCode: 2 };
50
72
  const serverMessage = extractErrorMessage(error.responseBody) ?? error.message;
51
73
  const message = error.status === 401
52
74
  ? `${serverMessage}\nSign in with \`coauthor auth login\` (or set COAUTHOR_TOKEN).`
53
75
  : serverMessage;
54
76
  const researchBlock = formatResearchDraftBlock(message, argv);
55
77
  if (researchBlock)
56
- return { error: new Error(researchBlock.message), result: researchBlock, exitCode: 2 };
57
- // Keep the server's error code and details (e.g. the current draft version
58
- // on a 409) so agents can recover without guessing.
59
- const envelope = extractEnvelopeError(error.responseBody);
78
+ return { error: new Error(researchBlock.message), result: { ...researchBlock, code: researchBlock.status, ...errorFields }, exitCode: 2 };
60
79
  const current = currentDraftDetails(envelope?.details);
61
- const humanMessage = current
62
- ? `${message}\nCurrent draft: version ${current.version_number ?? 'unknown'}${current.content_hash ? `, content_hash ${current.content_hash}` : ''}. Re-read it with \`${current.reread_command ?? 'coauthor draft get <project-id> --format json --json'}\` and save again.`
63
- : message;
80
+ const humanMessage = [
81
+ current
82
+ ? `${message}\nCurrent draft: version ${current.version_number ?? 'unknown'}${current.content_hash ? `, content_hash ${current.content_hash}` : ''}. Re-read it with \`${current.reread_command ?? 'coauthor draft get <project-id> --format json --json'}\` and save again.`
83
+ : message,
84
+ operationHint,
85
+ ].filter(Boolean).join('\n');
64
86
  return {
65
87
  error: new Error(humanMessage),
66
88
  result: {
67
89
  ok: false,
68
90
  error: humanMessage,
69
- ...(envelope?.code ? { code: envelope.code } : {}),
70
- http_status: error.status,
71
- ...(envelope?.details !== undefined ? { details: envelope.details } : {}),
91
+ code: envelope?.code ?? `http_${error.status}`,
92
+ ...errorFields,
72
93
  },
73
94
  exitCode: 1,
74
95
  };
75
96
  }
76
- return { error: error instanceof Error ? error : new Error(String(error)), exitCode: 1 };
97
+ if (error instanceof AgentRequestError) {
98
+ return {
99
+ error,
100
+ result: {
101
+ ok: false,
102
+ error: error.message,
103
+ code: error.code,
104
+ http_status: null,
105
+ ...(error.idempotencyKey ? { idempotency_key: error.idempotencyKey } : {}),
106
+ },
107
+ exitCode: 1,
108
+ };
109
+ }
110
+ const normalized = error instanceof Error ? error : new Error(String(error));
111
+ return {
112
+ error: normalized,
113
+ result: { ok: false, error: normalized.message, code: isUsageMessage(normalized.message) ? 'usage_error' : 'cli_error', http_status: null },
114
+ exitCode: 1,
115
+ };
116
+ }
117
+ function isUsageMessage(message) {
118
+ return /^(Usage:|Unknown option|Unknown command|Missing |Unknown \w+ command)/.test(message) || /Run `coauthor [^`]*--help`/.test(message);
119
+ }
120
+ // Live actions (publish, export) are recorded as operations under the
121
+ // Idempotency-Key the CLI sent. Point at it so a caller can check the outcome
122
+ // instead of retrying blind.
123
+ function operationLookupHint(details, idempotencyKey) {
124
+ if (!idempotencyKey)
125
+ return null;
126
+ if (!details || typeof details !== 'object' || Array.isArray(details) || !('operation' in details))
127
+ return null;
128
+ return `Operation key: ${idempotencyKey} (check it with \`coauthor operation status ${idempotencyKey} --json\`; retry with --idempotency-key ${idempotencyKey} to replay safely).`;
77
129
  }
78
130
  function formatEntitlementResult(body) {
79
131
  const envelopeError = extractEnvelopeError(body);
@@ -144,44 +196,30 @@ function formatResearchDraftBlock(message, argv) {
144
196
  exitCode: 2,
145
197
  };
146
198
  }
147
- function resolveProjectIdFromArgv(argv) {
148
- const projectFlagIndex = argv.indexOf('--project');
149
- if (projectFlagIndex >= 0 && argv[projectFlagIndex + 1])
150
- return argv[projectFlagIndex + 1];
151
- const commandWords = new Set([
152
- 'auth',
153
- 'login',
154
- 'status',
155
- 'logout',
156
- 'project',
157
- 'create',
158
- 'list',
159
- 'show',
160
- 'workspace',
161
- 'chat',
162
- 'contract',
163
- 'outline',
164
- 'research-plan',
165
- 'research',
166
- 'run',
167
- 'draft',
168
- 'generate',
169
- 'get',
170
- 'save',
171
- 'workflow',
172
- 'advance',
173
- 'rewind',
174
- 'approve',
175
- 'resume',
176
- 'image',
177
- 'thread',
178
- 'publish',
179
- 'export',
180
- 'operation',
181
- 'credits',
182
- 'skills',
183
- ]);
184
- return argv.find((arg) => !arg.startsWith('-') && !commandWords.has(arg));
199
+ export function resolveProjectIdFromArgv(argv) {
200
+ try {
201
+ const parsed = parseCliArgs(argv);
202
+ return getString(parsed.values, 'project') ?? parsed.positionals[0];
203
+ }
204
+ catch {
205
+ // Unparseable argv: walk it, skipping the values of flags that take one.
206
+ }
207
+ const words = [];
208
+ for (let index = 0; index < argv.length; index += 1) {
209
+ const arg = argv[index] ?? '';
210
+ if (arg === '--project' && argv[index + 1])
211
+ return argv[index + 1];
212
+ if (arg.startsWith('--project='))
213
+ return arg.slice('--project='.length);
214
+ if (arg.startsWith('-')) {
215
+ if (optionTakesValue(arg))
216
+ index += 1;
217
+ continue;
218
+ }
219
+ words.push(arg);
220
+ }
221
+ const commandWords = new Set(['auth', 'login', 'status', 'logout', 'project', 'create', 'list', 'show', 'workspace', 'chat', 'contract', 'outline', 'research-plan', 'research', 'run', 'draft', 'generate', 'get', 'save', 'workflow', 'advance', 'rewind', 'approve', 'resume', 'image', 'thread', 'publish', 'export', 'operation', 'credits', 'skills']);
222
+ return words.find((word) => !commandWords.has(word));
185
223
  }
186
224
  function extractErrorMessage(body) {
187
225
  if (!body || typeof body !== 'object' || Array.isArray(body) || !('error' in body))
package/dist/output.d.ts CHANGED
@@ -7,6 +7,14 @@ export type CommandResult = {
7
7
  exitCode?: number;
8
8
  settings_url?: string;
9
9
  resume_command?: string;
10
+ /** The Idempotency-Key sent with the command's live request; look it up with `coauthor operation status <key>`. */
11
+ idempotency_key?: string;
12
+ /** Set when `message` already shows everything in `data`, so plain output doesn't print it twice. Never rendered. */
13
+ messageIncludesData?: boolean;
10
14
  };
11
15
  export declare function renderResult(result: CommandResult, json: boolean): string;
12
16
  export declare function renderError(error: unknown, json: boolean): string;
17
+ export declare function withErrorFields<T extends Record<string, unknown>>(value: T): T & {
18
+ code: unknown;
19
+ http_status: unknown;
20
+ };
package/dist/output.js CHANGED
@@ -1,22 +1,40 @@
1
1
  export function renderResult(result, json) {
2
+ const { messageIncludesData, ...printable } = result;
2
3
  if (json)
3
- return `${JSON.stringify(result, null, 2)}\n`;
4
+ return `${JSON.stringify(result.ok ? printable : withErrorFields(printable), null, 2)}\n`;
5
+ // Plain output used to stop at the message, hiding ids and clarification
6
+ // questions. Print the message, then the data behind it.
7
+ const parts = [];
4
8
  if (result.message)
5
- return `${result.message}\n`;
6
- if (result.data === undefined)
7
- return '';
8
- return `${JSON.stringify(result.data, null, 2)}\n`;
9
+ parts.push(result.message);
10
+ if (result.data !== undefined && result.data !== null && !(result.message && messageIncludesData)) {
11
+ parts.push(JSON.stringify(result.data, null, 2));
12
+ }
13
+ return parts.length > 0 ? `${parts.join('\n')}\n` : '';
9
14
  }
10
15
  export function renderError(error, json) {
11
16
  if (json && error && typeof error === 'object' && !Array.isArray(error) && 'ok' in error) {
12
- return `${JSON.stringify(error, null, 2)}\n`;
17
+ return `${JSON.stringify(withErrorFields(error), null, 2)}\n`;
13
18
  }
19
+ const record = error && typeof error === 'object' && !Array.isArray(error) ? error : null;
14
20
  const message = error instanceof Error
15
21
  ? error.message
16
- : error && typeof error === 'object' && !Array.isArray(error) && typeof error.message === 'string'
17
- ? error.message
18
- : String(error);
22
+ : typeof record?.message === 'string'
23
+ ? record.message
24
+ : typeof record?.error === 'string'
25
+ ? record.error
26
+ : String(error);
19
27
  if (json)
20
- return `${JSON.stringify({ ok: false, error: message }, null, 2)}\n`;
28
+ return `${JSON.stringify({ ok: false, error: message, code: 'cli_error', http_status: null }, null, 2)}\n`;
21
29
  return `Error: ${message}\n`;
22
30
  }
31
+ // Every --json failure carries `code` and `http_status` (null when no HTTP
32
+ // response caused it: a pause seen while polling, a usage error, a timeout).
33
+ export function withErrorFields(value) {
34
+ const status = typeof value.status === 'string' ? value.status : undefined;
35
+ return {
36
+ ...value,
37
+ code: value.code ?? status ?? 'failed',
38
+ http_status: value.http_status ?? null,
39
+ };
40
+ }
package/dist/parser.d.ts CHANGED
@@ -25,6 +25,8 @@ export declare const commandInputSchema: z.ZodObject<{
25
25
  }, z.core.$strip>;
26
26
  values: z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodBoolean, z.ZodArray<z.ZodString>]>>>;
27
27
  }, z.core.$strip>;
28
+ /** True when `--name` (or its short alias) consumes the next argv entry as its value. */
29
+ export declare function optionTakesValue(flag: string): boolean;
28
30
  export declare function parseCliArgs(argv: string[]): ParsedCommand;
29
31
  export declare function getString(values: ParsedCommand['values'], name: string): string | undefined;
30
32
  export declare function requireString(values: ParsedCommand['values'], name: string): string;
package/dist/parser.js CHANGED
@@ -76,7 +76,19 @@ const OPTIONS = {
76
76
  apply: { type: 'boolean', default: false },
77
77
  accept: { type: 'string' },
78
78
  reject: { type: 'string' },
79
+ 'idempotency-key': { type: 'string' },
79
80
  };
81
+ /** True when `--name` (or its short alias) consumes the next argv entry as its value. */
82
+ export function optionTakesValue(flag) {
83
+ const name = flag.replace(/^--?/, '').split('=')[0] ?? '';
84
+ if (flag.includes('='))
85
+ return false;
86
+ const entries = Object.entries(OPTIONS);
87
+ const option = flag.startsWith('--')
88
+ ? entries.find(([key]) => key === name)?.[1]
89
+ : entries.find(([, value]) => value.short === name)?.[1];
90
+ return option?.type === 'string';
91
+ }
80
92
  export function parseCliArgs(argv) {
81
93
  let parsed;
82
94
  try {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.31",
3
+ "version": "0.0.33",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -66,4 +66,4 @@ Everything else, including auth problems: `references/troubleshooting.md`. Credi
66
66
 
67
67
  ## Not in the CLI yet
68
68
 
69
- Creating or editing writer profiles, PDFs over about 3.3 MB, adding more images than CoAuthor planned, and slideshows. Point the user to the CoAuthor web app at https://tools.clickminded.com/coauthor for these instead of improvising.
69
+ Creating or editing writer profiles, PDFs over about 3.3 MB, and adding more images than CoAuthor planned. Point the user to the CoAuthor web app at https://tools.clickminded.com/coauthor for these instead of improvising.
@@ -6,7 +6,7 @@ Draft generation plans image placeholders, including a featured image (`is_featu
6
6
 
7
7
  1. `coauthor image list <id> --json` returns `data.placeholders`. Each has an `id` (UUID), a `purpose`, an `image_type`, and the planned brief.
8
8
  2. Generate them all and wait: `coauthor image generate <id> --all --wait --json`. It skips images that are already done, and reports `done`, `failed`, and `still_running` (check again with `coauthor image status <id> --json`). Each image takes about 20 seconds.
9
- 3. To generate one: `coauthor image generate <id> --placeholder-id <id UUID> --json` (the `id` UUID; the descriptive `placeholder_id` string is not accepted; optional `--grounding-mode <mode>`, `--image-generation-model <id>`), then poll `coauthor image status <id> --json`.
9
+ 3. To generate one: `coauthor image generate <id> --placeholder-id <id UUID> --json` (the `id` UUID or the descriptive `placeholder_id`; optional `--grounding-mode <mode>`, `--image-generation-model <id>`), then poll `coauthor image status <id> --json`.
10
10
  4. Check every finished image (the URLs are in `image status` and in `draft get --format markdown`):
11
11
  - Charts and tables must match the article's numbers, and must not state figures the article deliberately leaves open.
12
12
  - Screens of real products (for example a Google or Meta interface) must not be presented as genuine.
@@ -25,4 +25,4 @@ Images cost credits each time they are generated or edited, so check the brief a
25
25
 
26
26
  ## Other formats
27
27
 
28
- X posts, LinkedIn, Facebook, and email newsletter versions: see `references/repurposing.md`. Carousel slideshows and short videos are generated in the CoAuthor web app (open the project, then Promote).
28
+ X posts, LinkedIn, Facebook, and email newsletter versions: see `references/repurposing.md`. Carousel slideshows and short vertical videos: same file, under Slideshow and Video.
@@ -34,4 +34,4 @@ See `references/images-and-social.md`. Publishing a thread posts immediately and
34
34
 
35
35
  ## If a live action's result is unclear
36
36
 
37
- After a network error or an unclear result on an export or publish, do not run it again straight away. Check `coauthor operation list --json` for the operation and its status first, then decide.
37
+ After a network error or an unclear result on an export or publish, do not run it again straight away. Every export and publish prints its `idempotency_key`; check `coauthor operation status <idempotency_key> --json` (or `coauthor operation list --json`) first. To retry safely, pass the same key back with `--idempotency-key <key>`, so CoAuthor won't run it twice.
@@ -1,4 +1,4 @@
1
- # Repurposing: social posts and an email newsletter
1
+ # Repurposing: social posts, an email newsletter, slideshows, and video
2
2
 
3
3
  Once the draft is final, CoAuthor turns it into distribution copy in the project's voice.
4
4
 
@@ -10,7 +10,7 @@ Once the draft is final, CoAuthor turns it into distribution copy in the project
10
10
  | Facebook post | `facebook` | Variations with alternate hooks |
11
11
  | Email newsletter | `email` | Variations with subject line, preheader, and body |
12
12
 
13
- Slideshows (carousels) are generated in the CoAuthor web app (open the project, then Promote); `repurpose download` includes them as JSON once they exist. Short vertical videos can be made from the CLI (see below).
13
+ Carousel slideshows and short vertical videos have their own steps, because their illustrated panels are generated as images first (see Slideshow and Video below).
14
14
 
15
15
  ## Generate
16
16
 
@@ -44,6 +44,16 @@ coauthor repurpose save <id> --format x-thread --data '{"posts":[...]}' --json
44
44
 
45
45
  Add `"destination_url": "https://..."` to point the posts at the published article. Keep the `{{POST_URL}}` placeholder in stored text; it is replaced with the destination URL on copy.
46
46
 
47
+ ## Slideshow
48
+
49
+ A carousel of 1080x1350 slides (for LinkedIn or Instagram) with illustrated panels and a closing call-to-action slide.
50
+
51
+ 1. `coauthor repurpose generate <id> --format slideshow [--cta save,follow] --json` writes the slides and queues one image per panel. Up to 4 endings: `save`, `follow`, `comment`, `share`, `read_more`, plus one `custom:<text>`; the default is `save`. Panel images cost image credits, which is why slideshows are not part of `--format all`.
52
+ 2. `coauthor repurpose status <id> --format slideshow --wait --json` waits until no panel is still generating. If some failed, retry them with `coauthor image generate` or in the web app.
53
+ 3. `coauthor repurpose download <id> --format slideshow [--variant <cta>] --out <dir>` renders the PNGs on the server and saves them as `slideshow/<cta>/slide-NN.png`, one folder per ending. `panels_not_ready` (409) means images are still generating or failed. Rendering again with no changes returns the same files.
54
+
55
+ The server draws the slides with the Inter font, so line breaks can differ slightly from the web app's own PNG download.
56
+
47
57
  ## Video
48
58
 
49
59
  A short vertical video (1080x1920) of the article's key points, with illustrated panels and a closing call to action.
@@ -30,6 +30,8 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
30
30
  | `workflow_token_mismatch`, `conflict` | The project moved on since you read it (for example someone used the web app). | Re-read the state with `coauthor workflow status <id> --json` and continue from there. |
31
31
  | `insufficient_scope` | The token can't publish. | `coauthor auth login --with-publish`. |
32
32
  | `wordpress_connection_required` | Several WordPress sites are connected. | Ask which one from `details.connections`, add `--connection-id`. |
33
+ | `usage_error` | The command or its flags are wrong; nothing was sent. | Check `coauthor help <command>` and fix the command. |
34
+ | `request_timeout`, `network_error` | No answer from CoAuthor in time, or the connection failed. | For reads, retry. For exports and publishes, check `coauthor operation status <idempotency_key>` before retrying. |
33
35
 
34
36
  ## Sign-in
35
37
 
@@ -68,7 +68,7 @@ Everything else, including auth problems: `references/troubleshooting.md`. Credi
68
68
 
69
69
  ## Not in the CLI yet
70
70
 
71
- Creating or editing writer profiles, PDFs over about 3.3 MB, adding more images than CoAuthor planned, and slideshows. Point the user to the CoAuthor web app at https://tools.clickminded.com/coauthor for these instead of improvising.
71
+ Creating or editing writer profiles, PDFs over about 3.3 MB, and adding more images than CoAuthor planned. Point the user to the CoAuthor web app at https://tools.clickminded.com/coauthor for these instead of improvising.
72
72
 
73
73
  # Reference sections
74
74
 
@@ -335,7 +335,7 @@ Draft generation plans image placeholders, including a featured image (`is_featu
335
335
 
336
336
  1. `coauthor image list <id> --json` returns `data.placeholders`. Each has an `id` (UUID), a `purpose`, an `image_type`, and the planned brief.
337
337
  2. Generate them all and wait: `coauthor image generate <id> --all --wait --json`. It skips images that are already done, and reports `done`, `failed`, and `still_running` (check again with `coauthor image status <id> --json`). Each image takes about 20 seconds.
338
- 3. To generate one: `coauthor image generate <id> --placeholder-id <id UUID> --json` (the `id` UUID; the descriptive `placeholder_id` string is not accepted; optional `--grounding-mode <mode>`, `--image-generation-model <id>`), then poll `coauthor image status <id> --json`.
338
+ 3. To generate one: `coauthor image generate <id> --placeholder-id <id UUID> --json` (the `id` UUID or the descriptive `placeholder_id`; optional `--grounding-mode <mode>`, `--image-generation-model <id>`), then poll `coauthor image status <id> --json`.
339
339
  4. Check every finished image (the URLs are in `image status` and in `draft get --format markdown`):
340
340
  - Charts and tables must match the article's numbers, and must not state figures the article deliberately leaves open.
341
341
  - Screens of real products (for example a Google or Meta interface) must not be presented as genuine.
@@ -354,7 +354,7 @@ Images cost credits each time they are generated or edited, so check the brief a
354
354
 
355
355
  ### Other formats
356
356
 
357
- X posts, LinkedIn, Facebook, and email newsletter versions: see `references/repurposing.md`. Carousel slideshows and short videos are generated in the CoAuthor web app (open the project, then Promote).
357
+ X posts, LinkedIn, Facebook, and email newsletter versions: see `references/repurposing.md`. Carousel slideshows and short vertical videos: same file, under Slideshow and Video.
358
358
 
359
359
  ## references/publishing-and-export.md
360
360
 
@@ -394,11 +394,11 @@ See `references/images-and-social.md`. Publishing a thread posts immediately and
394
394
 
395
395
  ### If a live action's result is unclear
396
396
 
397
- After a network error or an unclear result on an export or publish, do not run it again straight away. Check `coauthor operation list --json` for the operation and its status first, then decide.
397
+ After a network error or an unclear result on an export or publish, do not run it again straight away. Every export and publish prints its `idempotency_key`; check `coauthor operation status <idempotency_key> --json` (or `coauthor operation list --json`) first. To retry safely, pass the same key back with `--idempotency-key <key>`, so CoAuthor won't run it twice.
398
398
 
399
399
  ## references/repurposing.md
400
400
 
401
- ## Repurposing: social posts and an email newsletter
401
+ ## Repurposing: social posts, an email newsletter, slideshows, and video
402
402
 
403
403
  Once the draft is final, CoAuthor turns it into distribution copy in the project's voice.
404
404
 
@@ -410,7 +410,7 @@ Once the draft is final, CoAuthor turns it into distribution copy in the project
410
410
  | Facebook post | `facebook` | Variations with alternate hooks |
411
411
  | Email newsletter | `email` | Variations with subject line, preheader, and body |
412
412
 
413
- Slideshows (carousels) are generated in the CoAuthor web app (open the project, then Promote); `repurpose download` includes them as JSON once they exist. Short vertical videos can be made from the CLI (see below).
413
+ Carousel slideshows and short vertical videos have their own steps, because their illustrated panels are generated as images first (see Slideshow and Video below).
414
414
 
415
415
  ### Generate
416
416
 
@@ -444,6 +444,16 @@ coauthor repurpose save <id> --format x-thread --data '{"posts":[...]}' --json
444
444
 
445
445
  Add `"destination_url": "https://..."` to point the posts at the published article. Keep the `{{POST_URL}}` placeholder in stored text; it is replaced with the destination URL on copy.
446
446
 
447
+ ### Slideshow
448
+
449
+ A carousel of 1080x1350 slides (for LinkedIn or Instagram) with illustrated panels and a closing call-to-action slide.
450
+
451
+ 1. `coauthor repurpose generate <id> --format slideshow [--cta save,follow] --json` writes the slides and queues one image per panel. Up to 4 endings: `save`, `follow`, `comment`, `share`, `read_more`, plus one `custom:<text>`; the default is `save`. Panel images cost image credits, which is why slideshows are not part of `--format all`.
452
+ 2. `coauthor repurpose status <id> --format slideshow --wait --json` waits until no panel is still generating. If some failed, retry them with `coauthor image generate` or in the web app.
453
+ 3. `coauthor repurpose download <id> --format slideshow [--variant <cta>] --out <dir>` renders the PNGs on the server and saves them as `slideshow/<cta>/slide-NN.png`, one folder per ending. `panels_not_ready` (409) means images are still generating or failed. Rendering again with no changes returns the same files.
454
+
455
+ The server draws the slides with the Inter font, so line breaks can differ slightly from the web app's own PNG download.
456
+
447
457
  ### Video
448
458
 
449
459
  A short vertical video (1080x1920) of the article's key points, with illustrated panels and a closing call to action.
@@ -498,6 +508,8 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
498
508
  | `workflow_token_mismatch`, `conflict` | The project moved on since you read it (for example someone used the web app). | Re-read the state with `coauthor workflow status <id> --json` and continue from there. |
499
509
  | `insufficient_scope` | The token can't publish. | `coauthor auth login --with-publish`. |
500
510
  | `wordpress_connection_required` | Several WordPress sites are connected. | Ask which one from `details.connections`, add `--connection-id`. |
511
+ | `usage_error` | The command or its flags are wrong; nothing was sent. | Check `coauthor help <command>` and fix the command. |
512
+ | `request_timeout`, `network_error` | No answer from CoAuthor in time, or the connection failed. | For reads, retry. For exports and publishes, check `coauthor operation status <idempotency_key>` before retrying. |
501
513
 
502
514
  ### Sign-in
503
515