@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/commands.js CHANGED
@@ -1,12 +1,12 @@
1
1
  import { setTimeout as sleep } from 'node:timers/promises';
2
2
  import { spawn } from 'node:child_process';
3
- import { createHash } from 'node:crypto';
3
+ import { createHash, randomUUID } from 'node:crypto';
4
4
  import { existsSync } from 'node:fs';
5
5
  import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
6
6
  import { homedir } from 'node:os';
7
7
  import { basename, dirname, join, resolve } from 'node:path';
8
8
  import { fileURLToPath } from 'node:url';
9
- import { AgentHttpError, normalizeBaseUrl } from './client.js';
9
+ import { AgentHttpError, AgentRequestError, normalizeBaseUrl } from './client.js';
10
10
  import { clearConfig, loadConfig, saveConfig } from './config.js';
11
11
  import { getBoolean, getString, parseJsonOption, readJsonOptionText } from './parser.js';
12
12
  export async function runCommand(input, context) {
@@ -74,8 +74,32 @@ async function runAuthCommand(action, input, context) {
74
74
  const token = getString(input.values, 'token');
75
75
  const baseUrl = getString(input.values, 'base-url') ?? context.baseUrl;
76
76
  if (token) {
77
- await saveConfig({ ...(await loadConfig(context.paths)), baseUrl, token }, context.paths);
78
- return { ok: true, message: `Logged in to ${baseUrl}`, data: { baseUrl, authenticated: true } };
77
+ // Check the token before saving it, so a typo or a revoked token fails
78
+ // here instead of on the next command.
79
+ if (!AGENT_TOKEN_PATTERN.test(token.trim())) {
80
+ throw new Error('Invalid token format: CoAuthor tokens look like coa_<16 hex characters>_<secret>. Copy the whole token, or run `coauthor auth login` without --token to sign in in the browser.');
81
+ }
82
+ let status;
83
+ try {
84
+ status = await context.client.withCredentials({ baseUrl, token: token.trim() }).request({ path: 'auth/status' });
85
+ }
86
+ catch (error) {
87
+ if (error instanceof AgentHttpError && error.status === 401) {
88
+ throw new Error(`The server rejected this token (${extractErrorMessage(error)}). Nothing was saved. Create a new token, or run \`coauthor auth login\` without --token.`);
89
+ }
90
+ throw error;
91
+ }
92
+ await saveConfig({ ...(await loadConfig(context.paths)), baseUrl, token: token.trim() }, context.paths);
93
+ return {
94
+ ok: true,
95
+ message: `Logged in to ${baseUrl}`,
96
+ data: {
97
+ baseUrl,
98
+ authenticated: true,
99
+ tokenPrefix: getResponseString(status, 'token_prefix') ?? null,
100
+ scopes: getResponseValue(status, 'scopes') ?? [],
101
+ },
102
+ };
79
103
  }
80
104
  const start = await context.client.request({
81
105
  method: 'POST',
@@ -98,8 +122,9 @@ async function runAuthCommand(action, input, context) {
98
122
  ].join('\n'));
99
123
  const deadline = Date.now() + expiresInSeconds * 1000;
100
124
  let tokenResponse = null;
125
+ let delayMs = intervalSeconds * 1000;
101
126
  while (Date.now() < deadline) {
102
- await sleep(intervalSeconds * 1000);
127
+ await sleep(Math.max(0, Math.min(delayMs, deadline - Date.now())));
103
128
  try {
104
129
  tokenResponse = await context.client.request({
105
130
  method: 'POST',
@@ -109,8 +134,16 @@ async function runAuthCommand(action, input, context) {
109
134
  break;
110
135
  }
111
136
  catch (error) {
112
- if (isAuthorizationPending(error))
137
+ if (isAuthorizationPending(error)) {
138
+ delayMs = intervalSeconds * 1000;
139
+ continue;
140
+ }
141
+ // A deploy or a network blip must not abort the sign-in: back off and
142
+ // keep polling until the code expires.
143
+ if (isTransientPollError(error)) {
144
+ delayMs = Math.min(Math.max(delayMs, intervalSeconds * 1000) * 2, 30_000);
113
145
  continue;
146
+ }
114
147
  throw error;
115
148
  }
116
149
  }
@@ -156,16 +189,32 @@ async function runAuthCommand(action, input, context) {
156
189
  data: { authenticated: false, remoteRevoked: null, localOnly },
157
190
  };
158
191
  }
159
- if (localOnly) {
192
+ // The token in use can come from --token or COAUTHOR_TOKEN rather than
193
+ // the saved config. Only remove the saved config when it holds that same
194
+ // token; a different saved login stays.
195
+ const storedToken = (await loadConfig(context.paths)).token;
196
+ const clearStoredIfSame = async () => {
197
+ if (storedToken !== context.token)
198
+ return false;
160
199
  await clearConfig(context.paths);
200
+ return true;
201
+ };
202
+ const keptNote = (removed) => removed || !storedToken
203
+ ? ''
204
+ : ' The token came from --token or COAUTHOR_TOKEN, so the different token saved in the local config was kept.';
205
+ if (localOnly) {
206
+ const removed = await clearStoredIfSame();
161
207
  return {
162
208
  ok: true,
163
- message: 'Local credentials removed without revoking the remote token.',
209
+ message: removed
210
+ ? 'Local credentials removed without revoking the remote token.'
211
+ : `Did not revoke the remote token. No saved login holds this token (it came from --token or COAUTHOR_TOKEN), so nothing local was removed${storedToken ? ' and the different saved login was kept' : ''}.`,
164
212
  data: {
165
213
  authenticated: false,
166
214
  remoteRevoked: false,
167
215
  localOnly: true,
168
216
  remoteTokenMayRemainActive: true,
217
+ ...(removed ? {} : { localConfigCleared: false }),
169
218
  },
170
219
  };
171
220
  }
@@ -177,25 +226,27 @@ async function runAuthCommand(action, input, context) {
177
226
  if (!inactiveCode) {
178
227
  throw new Error('Could not confirm remote token revocation. Local credentials were kept so you can retry `coauthor auth logout`. Use `coauthor auth logout --local-only` only to remove the local token without revoking it remotely.');
179
228
  }
180
- await clearConfig(context.paths);
229
+ const removed = await clearStoredIfSame();
181
230
  return {
182
231
  ok: true,
183
- message: inactiveCode === 'token_revoked'
184
- ? 'Logged out; the remote token was already revoked and local credentials were removed.'
185
- : 'Logged out; the remote token was already expired and local credentials were removed.',
232
+ message: (inactiveCode === 'token_revoked'
233
+ ? 'Logged out; the remote token was already revoked'
234
+ : 'Logged out; the remote token was already expired')
235
+ + (removed ? ' and local credentials were removed.' : '.') + keptNote(removed),
186
236
  data: {
187
237
  authenticated: false,
188
238
  remoteRevoked: true,
189
239
  localOnly: false,
190
240
  alreadyInactive: true,
241
+ ...(removed ? {} : { localConfigCleared: false }),
191
242
  },
192
243
  };
193
244
  }
194
- await clearConfig(context.paths);
245
+ const removed = await clearStoredIfSame();
195
246
  return {
196
247
  ok: true,
197
- message: 'Logged out; remote token revoked and local credentials removed.',
198
- data: { authenticated: false, remoteRevoked: true, localOnly: false },
248
+ message: `Logged out; remote token revoked${removed ? ' and local credentials removed.' : '.'}${keptNote(removed)}`,
249
+ data: { authenticated: false, remoteRevoked: true, localOnly: false, ...(removed ? {} : { localConfigCleared: false }) },
199
250
  };
200
251
  }
201
252
  throw new Error('Usage: coauthor auth <login|status|logout>');
@@ -225,11 +276,17 @@ async function runProjectCommand(action, input, client) {
225
276
  body.contract = parseJsonOption(input.values, 'contract');
226
277
  }
227
278
  const data = await client.request({ method: 'POST', path: 'projects', body });
228
- return { ok: true, message: 'Project created', data };
279
+ const projectId = extractNestedString(data, ['project', 'id']);
280
+ return { ok: true, message: projectId ? `Project created: ${projectId}` : 'Project created', data };
229
281
  }
230
282
  if (action === 'list') {
231
- const data = await client.request({ path: withQuery('projects', input.values, ['limit', 'cursor']) });
232
- return { ok: true, data };
283
+ const status = getString(input.values, 'status');
284
+ if (status !== undefined && !PROJECT_LIST_STATUSES.includes(status)) {
285
+ throw new Error(`Unknown --status "${status}". Use one of: ${PROJECT_LIST_STATUSES.join(', ')}.`);
286
+ }
287
+ const data = await client.request({ path: withQuery('projects', input.values, ['limit', 'cursor', 'status']) });
288
+ const nextCursor = getResponseString(data, 'next_cursor');
289
+ return { ok: true, message: nextCursor ? `More projects: coauthor project list --cursor ${nextCursor}` : undefined, data };
233
290
  }
234
291
  if (action === 'show') {
235
292
  const projectId = requireProjectId(input);
@@ -265,6 +322,21 @@ async function runProjectCommand(action, input, client) {
265
322
  }
266
323
  throw new Error('Usage: coauthor project <create|list|show|rename|delete|duplicate>');
267
324
  }
325
+ // The project's workflow state (project_state) or its publication status.
326
+ const PROJECT_LIST_STATUSES = [
327
+ 'topic_discussion',
328
+ 'topic_committed',
329
+ 'outline_discussion',
330
+ 'outline_locked',
331
+ 'research_planning',
332
+ 'research_running',
333
+ 'research_complete',
334
+ 'research_structured',
335
+ 'draft_generated',
336
+ 'editing',
337
+ 'submitted',
338
+ 'published',
339
+ ];
268
340
  async function runWorkspaceCommand(action, input, client) {
269
341
  if (action !== 'show')
270
342
  throw new Error('Usage: coauthor workspace show <projectId>');
@@ -391,7 +463,7 @@ async function runShareCommand(input, client) {
391
463
  async function runModelsCommand(action, input, client) {
392
464
  if (!action || action === 'list') {
393
465
  const data = await client.request({ path: 'models' });
394
- return { ok: true, message: formatModelsList(data), data };
466
+ return { ok: true, message: formatModelsList(data), messageIncludesData: true, data };
395
467
  }
396
468
  if (action === 'preferences') {
397
469
  const subaction = input.command[2] ?? 'show';
@@ -647,18 +719,43 @@ async function waitForRevision(client, projectId, revisionId) {
647
719
  return null;
648
720
  }
649
721
  const DRAFT_SAVE_SHAPE = 'Payload: {"document_id":"<from draft get>","expected_base_version":<version_number>,"expected_content_hash":"<content_hash, if draft get returned one>","content":{"type":"doc","content":[...]}}, where content is the edited `data.content` from `coauthor draft get <project-id> --format json --json`.';
722
+ // The actions each resource supports on the Agent API. Anything else used to
723
+ // reach the server and come back as "Agent API route not found".
724
+ const RESOURCE_ACTIONS = {
725
+ images: ['list', 'status', 'show', 'generate', 'edit', 'metadata'],
726
+ threads: ['list', 'show', 'status', 'generate', 'save', 'create'],
727
+ slideshows: ['list', 'show', 'status', 'generate', 'save'],
728
+ publish: ['thread'],
729
+ exports: ['list', 'blog', 'clickminded', 'wordpress'],
730
+ };
731
+ function resourceUsage(resource) {
732
+ const name = resourceCommandName(resource);
733
+ return `Usage: coauthor ${name} <${RESOURCE_ACTIONS[resource]?.join('|') ?? 'list'}> <project-id> [...]. Run \`coauthor ${name} --help\` for details.`;
734
+ }
650
735
  async function runResourceCommand(resource, action, input, client) {
651
736
  const projectId = getString(input.values, 'project') ?? input.positionals[0];
652
737
  const resourceId = getString(input.values, 'id') ?? input.positionals[1];
653
- const basePath = projectId
654
- ? `projects/${encodeURIComponent(projectId)}/${resource}`
655
- : resource;
656
- if (!action || action === 'list') {
657
- const data = await client.request({ path: withQuery(basePath, input.values, ['limit', 'cursor', 'status']) });
738
+ const name = resourceCommandName(resource);
739
+ const resolvedAction = action ?? (resource === 'publish' ? undefined : 'list');
740
+ if (!resolvedAction || !RESOURCE_ACTIONS[resource]?.includes(resolvedAction)) {
741
+ throw new Error(action ? `Unknown ${name} command: ${action}. ${resourceUsage(resource)}` : resourceUsage(resource));
742
+ }
743
+ if (!projectId)
744
+ throw new Error(`Missing project id. Usage: coauthor ${name} ${resolvedAction} <project-id> [...]`);
745
+ const basePath = `projects/${encodeURIComponent(projectId)}/${resource}`;
746
+ if (resolvedAction === 'list') {
747
+ // These lists return everything for the project; the server has no
748
+ // filters or pages for them, so don't pretend to send any.
749
+ for (const flag of ['status', 'cursor', 'limit']) {
750
+ if (getString(input.values, flag) !== undefined) {
751
+ throw new Error(`${name} list does not support --${flag}; it always returns every ${name === 'export' ? 'export' : 'item'} for the project.`);
752
+ }
753
+ }
754
+ const data = await client.request({ path: basePath });
658
755
  return { ok: true, data };
659
756
  }
660
- if (action === 'show' || action === 'status') {
661
- if (resource === 'images' && action === 'status') {
757
+ if (resolvedAction === 'show' || resolvedAction === 'status') {
758
+ if (resource === 'images' && resolvedAction === 'status') {
662
759
  const data = await client.request({ path: `${basePath}/status` });
663
760
  return { ok: true, data };
664
761
  }
@@ -667,45 +764,24 @@ async function runResourceCommand(resource, action, input, client) {
667
764
  return { ok: true, data };
668
765
  }
669
766
  if (!resourceId)
670
- throw new Error(`Usage: coauthor ${resourceCommandName(resource)} ${action} <projectId> <id>`);
767
+ throw new Error(`Usage: coauthor ${name} ${resolvedAction} <projectId> <id>`);
671
768
  const data = await client.request({ path: `${basePath}/${encodeURIComponent(resourceId)}` });
672
769
  return { ok: true, data };
673
770
  }
674
- if (resource === 'publish' && action === 'thread') {
675
- if (!projectId)
676
- throw new Error('Missing project id for publish thread');
771
+ if (resource === 'publish' && resolvedAction === 'thread') {
677
772
  if (!getBoolean(input.values, 'yes'))
678
773
  throw new Error('Live publish requires --yes');
679
- const data = await client.request({ method: 'POST', path: `${basePath}/thread`, body: parseJsonOption(input.values) });
680
- return { ok: true, data };
774
+ return liveOperationRequest(client, input, `${basePath}/thread`, parseJsonOption(input.values));
681
775
  }
682
- if (resource === 'exports' && (action === 'blog' || action === 'clickminded' || action === 'wordpress')) {
683
- if (!projectId)
684
- throw new Error(`Missing project id for export ${action}`);
776
+ if (resource === 'exports') {
685
777
  if (!getBoolean(input.values, 'yes'))
686
778
  throw new Error('Live export requires --yes');
687
- const body = withNamedOptions(parseJsonOption(input.values), input.values, [
688
- 'slug',
689
- 'status',
690
- 'permalink',
691
- 'connection-id',
692
- 'format',
693
- ]);
694
- if (typeof body.connectionId === 'string') {
695
- body.integration_id = body.connectionId;
696
- delete body.connectionId;
697
- }
698
- const data = await client.request({ method: 'POST', path: `${basePath}/${action}`, body });
699
- return { ok: true, data };
779
+ return liveOperationRequest(client, input, `${basePath}/${resolvedAction}`, exportRequestBody(resolvedAction, input));
700
780
  }
701
- if (resource === 'images' && action === 'generate' && getBoolean(input.values, 'all')) {
702
- if (!projectId)
703
- throw new Error('Usage: coauthor image generate <project-id> --all [--wait]');
781
+ if (resource === 'images' && resolvedAction === 'generate' && getBoolean(input.values, 'all')) {
704
782
  return generateAllImages(client, projectId, getBoolean(input.values, 'wait'));
705
783
  }
706
- if (resource === 'images' && action === 'metadata') {
707
- if (!projectId)
708
- throw new Error('Missing project id for image metadata');
784
+ if (resource === 'images' && resolvedAction === 'metadata') {
709
785
  if (!resourceId) {
710
786
  throw new Error('Usage: coauthor image metadata <projectId> <placeholderId> [--alt-text <text>] [--description <text>] [--file-slug <slug>]');
711
787
  }
@@ -728,28 +804,81 @@ async function runResourceCommand(resource, action, input, client) {
728
804
  });
729
805
  return { ok: true, data };
730
806
  }
731
- if (['create', 'generate', 'save', 'edit', 'publish', 'export', 'cancel', 'retry'].includes(action)) {
732
- if (!projectId)
733
- throw new Error(`Missing project id for ${resourceCommandName(resource)} ${action}`);
734
- const body = withNamedOptions(parseJsonOption(input.values), input.values, [
735
- 'prompt',
736
- 'format',
737
- 'target',
738
- 'thread',
739
- 'image',
740
- 'id',
741
- 'placeholder-id',
742
- 'execution-token',
743
- 'grounding-mode',
744
- 'image-generation-model',
745
- ...(resource === 'threads' && action === 'generate' ? ['writing-model'] : []),
746
- 'edit-prompt',
747
- ]);
748
- const path = action === 'create' && resource !== 'threads' ? basePath : `${basePath}/${action}`;
749
- const data = await client.request({ method: 'POST', path, body });
750
- return { ok: true, data };
807
+ if (getString(input.values, 'prompt') !== undefined) {
808
+ // No resource endpoint reads a free-form prompt (images are built from the
809
+ // placeholder's planned brief), so --prompt used to be silently dropped.
810
+ throw new Error(resource === 'images'
811
+ ? `image ${resolvedAction} does not take --prompt. Generate the image first, then direct changes with \`coauthor image edit <project-id> --placeholder-id <id> --edit-prompt "..."\`.`
812
+ : `${name} ${resolvedAction} does not take --prompt.`);
813
+ }
814
+ const body = withNamedOptions(parseJsonOption(input.values), input.values, [
815
+ 'format',
816
+ 'target',
817
+ 'thread',
818
+ 'image',
819
+ 'id',
820
+ 'placeholder-id',
821
+ 'execution-token',
822
+ 'grounding-mode',
823
+ 'image-generation-model',
824
+ ...(resource === 'threads' && resolvedAction === 'generate' ? ['writing-model'] : []),
825
+ 'edit-prompt',
826
+ ]);
827
+ const path = resolvedAction === 'create' && resource !== 'threads' ? basePath : `${basePath}/${resolvedAction}`;
828
+ const data = await client.request({ method: 'POST', path, body });
829
+ return { ok: true, data };
830
+ }
831
+ // Publish and export run as recorded operations keyed by the Idempotency-Key.
832
+ // Print the key so the caller can look the outcome up (`operation status`) or
833
+ // replay the same request safely with --idempotency-key.
834
+ async function liveOperationRequest(client, input, path, body) {
835
+ const idempotencyKey = getString(input.values, 'idempotency-key')?.trim() || randomUUID();
836
+ const data = await client.request({ method: 'POST', path, body, idempotencyKey });
837
+ const replayed = getResponseValue(data, 'replayed') === true;
838
+ return {
839
+ ok: true,
840
+ message: `${replayed ? 'Replayed recorded operation' : 'Done'}. Operation key: ${idempotencyKey} (coauthor operation status ${idempotencyKey} --json).`,
841
+ idempotency_key: idempotencyKey,
842
+ data,
843
+ };
844
+ }
845
+ const EXPORT_STATUSES = ['draft', 'published'];
846
+ function exportRequestBody(action, input) {
847
+ const body = parseJsonOption(input.values);
848
+ const status = getString(input.values, 'status');
849
+ if (status !== undefined && !EXPORT_STATUSES.includes(status)) {
850
+ throw new Error(`--status must be draft or published (got "${status}").`);
851
+ }
852
+ const slug = getString(input.values, 'slug');
853
+ const description = getString(input.values, 'description');
854
+ if (action === 'wordpress') {
855
+ if (status !== undefined)
856
+ throw new Error('export wordpress always creates a WordPress draft; it does not take --status.');
857
+ if (slug !== undefined)
858
+ body.slug = slug;
859
+ const connectionId = getString(input.values, 'connection-id');
860
+ if (connectionId !== undefined)
861
+ body.integration_id = connectionId;
862
+ return body;
751
863
  }
752
- throw new Error(`Unknown ${resourceCommandName(resource)} command: ${action}`);
864
+ if (action === 'clickminded') {
865
+ const permalink = getString(input.values, 'permalink') ?? slug;
866
+ if (permalink !== undefined)
867
+ body.permalink = permalink;
868
+ if (status !== undefined)
869
+ body.published = status === 'published';
870
+ if (description !== undefined)
871
+ body.seoDescription = description;
872
+ return body;
873
+ }
874
+ // blog
875
+ if (slug !== undefined)
876
+ body.slug = slug;
877
+ if (status !== undefined)
878
+ body.status = status;
879
+ if (description !== undefined)
880
+ body.description = description;
881
+ return body;
753
882
  }
754
883
  async function runOperationCommand(action, input, client) {
755
884
  const key = getString(input.values, 'id') ?? input.positionals[0];
@@ -799,6 +928,7 @@ async function runSkillsCommand(action, input) {
799
928
  return {
800
929
  ok: true,
801
930
  message: formatSkillInstallMessage(results, warnings, dryRun),
931
+ messageIncludesData: true,
802
932
  data: { results, ...(warnings.length > 0 ? { warnings } : {}) },
803
933
  };
804
934
  }
@@ -1079,18 +1209,37 @@ function isAuthorizationPending(error) {
1079
1209
  return false;
1080
1210
  return envelopeError.code === 'authorization_pending';
1081
1211
  }
1082
- function openBrowser(url) {
1212
+ const AGENT_TOKEN_PATTERN = /^coa_[0-9a-f]{16}_[A-Za-z0-9_-]+$/;
1213
+ function isTransientPollError(error) {
1214
+ if (error instanceof AgentRequestError)
1215
+ return true;
1216
+ if (error instanceof AgentHttpError)
1217
+ return error.status >= 500 || error.status === 429;
1218
+ return false;
1219
+ }
1220
+ // A missing opener (headless Linux without xdg-open) emits 'error' on the
1221
+ // child; without a listener that crashed the CLI. The URL is printed anyway.
1222
+ export function openBrowser(url, spawnImpl = spawn, warn = (line) => process.stderr.write(line)) {
1083
1223
  const command = process.platform === 'darwin'
1084
1224
  ? 'open'
1085
1225
  : process.platform === 'win32'
1086
1226
  ? 'cmd'
1087
1227
  : 'xdg-open';
1088
1228
  const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
1089
- const child = spawn(command, args, {
1090
- detached: true,
1091
- stdio: 'ignore',
1092
- });
1093
- child.unref();
1229
+ const fallback = (error) => {
1230
+ warn(`Could not open a browser (${error instanceof Error ? error.message : String(error)}). Open this URL yourself: ${url}\n`);
1231
+ };
1232
+ try {
1233
+ const child = spawnImpl(command, args, {
1234
+ detached: true,
1235
+ stdio: 'ignore',
1236
+ });
1237
+ child.on('error', fallback);
1238
+ child.unref();
1239
+ }
1240
+ catch (error) {
1241
+ fallback(error);
1242
+ }
1094
1243
  }
1095
1244
  async function waitForResearch(client, projectId, initialData, baseUrl) {
1096
1245
  const deadline = Date.now() + waitTimeoutMs(20 * 60_000);
@@ -1494,6 +1643,52 @@ async function runLogCommand(action, input, client) {
1494
1643
  }
1495
1644
  const REPURPOSE_FORMATS = ['x-thread', 'x-post', 'linkedin', 'facebook', 'email', 'slideshow', 'video'];
1496
1645
  const REPURPOSE_GENERATABLE = ['x-thread', 'x-post', 'linkedin', 'facebook', 'email'];
1646
+ const SLIDESHOW_FORMAT_ALIASES = ['slideshow', 'carousel'];
1647
+ // Labels match the web app's CTA picker.
1648
+ const SLIDESHOW_CTA_LABELS = {
1649
+ save: 'Save post',
1650
+ follow: 'Follow account',
1651
+ comment: 'Leave a comment',
1652
+ share: 'Share with others',
1653
+ read_more: 'Read the full article',
1654
+ };
1655
+ /**
1656
+ * `--cta save,follow,custom:Join the webinar` -> the web app's cta_variants
1657
+ * list (at most 4 endings, at most one custom).
1658
+ */
1659
+ export function parseSlideshowCtaOption(raw) {
1660
+ const entries = raw.split(',').map((entry) => entry.trim()).filter(Boolean);
1661
+ if (entries.length === 0)
1662
+ throw new Error('--cta needs at least one of: save, follow, comment, share, read_more, custom:<text>');
1663
+ const intents = [];
1664
+ const seen = new Set();
1665
+ let customCount = 0;
1666
+ for (const entry of entries) {
1667
+ const customMatch = /^custom\s*:\s*(.+)$/i.exec(entry);
1668
+ if (customMatch) {
1669
+ customCount += 1;
1670
+ if (customCount > 1)
1671
+ throw new Error('--cta allows at most one custom ending (custom:<text>).');
1672
+ const text = customMatch[1].trim().slice(0, 120);
1673
+ intents.push({ id: 'custom-0', type: 'custom', label: text, custom_text: text });
1674
+ continue;
1675
+ }
1676
+ const type = entry.toLowerCase().replace(/[\s-]+/g, '_');
1677
+ const label = SLIDESHOW_CTA_LABELS[type];
1678
+ if (!label)
1679
+ throw new Error(`Unknown --cta "${entry}". Use save, follow, comment, share, read_more, or custom:<text>.`);
1680
+ if (seen.has(type))
1681
+ continue;
1682
+ seen.add(type);
1683
+ intents.push({ id: type, type, label, custom_text: null });
1684
+ }
1685
+ if (intents.length > 4)
1686
+ throw new Error('--cta allows at most 4 endings.');
1687
+ return intents;
1688
+ }
1689
+ function isSlideshowFormat(format) {
1690
+ return Boolean(format && SLIDESHOW_FORMAT_ALIASES.includes(format.trim().toLowerCase()));
1691
+ }
1497
1692
  async function runRepurposeCommand(action, input, client) {
1498
1693
  const projectId = requireProjectId(input);
1499
1694
  const base = `projects/${encodeURIComponent(projectId)}/repurpose`;
@@ -1507,12 +1702,14 @@ async function runRepurposeCommand(action, input, client) {
1507
1702
  }
1508
1703
  if (action === 'generate') {
1509
1704
  if (!format)
1510
- throw new Error(`Usage: coauthor repurpose generate <project-id> --format <${[...REPURPOSE_GENERATABLE, 'video'].join('|')}|all> [--writing-model <id>] [--cta save,follow]`);
1705
+ throw new Error(`Usage: coauthor repurpose generate <project-id> --format <${[...REPURPOSE_GENERATABLE, 'slideshow', 'video'].join('|')}|all> [--writing-model <id>] [--cta save,follow]`);
1706
+ if (isSlideshowFormat(format))
1707
+ return generateSlideshow(projectId, base, input, client);
1511
1708
  const formats = format === 'all' ? REPURPOSE_GENERATABLE : [format];
1512
1709
  const writingModel = getString(input.values, 'writing-model');
1513
1710
  const cta = getString(input.values, 'cta');
1514
1711
  if (cta !== undefined && format !== 'video')
1515
- throw new Error('--cta only applies to --format video.');
1712
+ throw new Error('--cta only applies to --format video or slideshow.');
1516
1713
  const results = {};
1517
1714
  for (const entry of formats) {
1518
1715
  results[entry] = await client.request({
@@ -1547,18 +1744,21 @@ async function runRepurposeCommand(action, input, client) {
1547
1744
  };
1548
1745
  }
1549
1746
  if (action === 'status') {
1747
+ if (isSlideshowFormat(format))
1748
+ return slideshowStatus(projectId, base, getBoolean(input.values, 'wait'), client);
1550
1749
  if (format !== 'video')
1551
- throw new Error('Usage: coauthor repurpose status <project-id> --format video [--wait]');
1750
+ throw new Error('Usage: coauthor repurpose status <project-id> --format <slideshow|video> [--wait]');
1552
1751
  return videoStatus(client, base, getBoolean(input.values, 'wait'));
1553
1752
  }
1554
1753
  if (action === 'render') {
1555
1754
  if (format !== 'video')
1556
- throw new Error('Usage: coauthor repurpose render <project-id> --format video [--variant <id>] [--wait]');
1755
+ throw new Error('Usage: coauthor repurpose render <project-id> --format video [--variant <id>] [--wait] (slideshow PNGs are rendered by repurpose download)');
1557
1756
  return videoRender(client, projectId, base, getString(input.values, 'variant'), getBoolean(input.values, 'wait'));
1558
1757
  }
1559
- if (action === 'download')
1560
- return downloadRepurposed(projectId, format ?? 'all', getString(input.values, 'out'), client, getString(input.values, 'variant'));
1561
- throw new Error('Usage: coauthor repurpose <list|show|generate|save|download|status|render> <project-id> --format <format>');
1758
+ if (action === 'download') {
1759
+ return downloadRepurposed(projectId, isSlideshowFormat(format) ? 'slideshow' : format ?? 'all', getString(input.values, 'out'), client, getString(input.values, 'variant'));
1760
+ }
1761
+ throw new Error('Usage: coauthor repurpose <list|show|generate|save|status|render|download> <project-id> --format <format>');
1562
1762
  }
1563
1763
  /** "save,follow,custom:Reply with a question" -> ["save","follow","custom:Reply with a question"]. */
1564
1764
  function parseCtaList(value) {
@@ -1610,6 +1810,26 @@ async function videoStatus(client, base, wait) {
1610
1810
  data,
1611
1811
  };
1612
1812
  }
1813
+ async function generateSlideshow(projectId, base, input, client) {
1814
+ const cta = getString(input.values, 'cta');
1815
+ const writingModel = getString(input.values, 'writing-model');
1816
+ const body = {};
1817
+ if (cta !== undefined)
1818
+ body.cta_variants = parseSlideshowCtaOption(cta);
1819
+ if (writingModel)
1820
+ body.writingModel = writingModel;
1821
+ const data = await client.request({ method: 'POST', path: `${base}/slideshow/generate`, body });
1822
+ const total = extractNestedNumber(data, ['panels', 'total']);
1823
+ return {
1824
+ ok: true,
1825
+ message: [
1826
+ `Generated the slideshow text${total !== undefined ? ` and queued ${total} panel image${total === 1 ? '' : 's'}` : ''}.`,
1827
+ `Wait for the images with: coauthor repurpose status ${projectId} --format slideshow --wait`,
1828
+ `Then save the PNGs with: coauthor repurpose download ${projectId} --format slideshow`,
1829
+ ].join('\n'),
1830
+ data,
1831
+ };
1832
+ }
1613
1833
  async function videoRender(client, projectId, base, variant, wait) {
1614
1834
  const deadline = Date.now() + waitTimeoutMs(9 * 60_000);
1615
1835
  if (wait) {
@@ -1676,6 +1896,86 @@ async function downloadVideoRenders(client, shown, outDir, variant) {
1676
1896
  }
1677
1897
  return { files, pending };
1678
1898
  }
1899
+ function slideshowCounts(data) {
1900
+ const read = (key) => {
1901
+ const value = getResponseValue(data, key);
1902
+ return typeof value === 'number' ? value : 0;
1903
+ };
1904
+ return { total: read('total'), ready: read('ready'), generating: read('generating'), failed: read('failed') };
1905
+ }
1906
+ // Polls panel image status until nothing is generating, capped under the
1907
+ // 10-minute agent shell limit (resumable still_running on timeout).
1908
+ async function slideshowStatus(projectId, base, wait, client) {
1909
+ const statusPath = `${base}/slideshow/status`;
1910
+ let data = await client.request({ path: statusPath });
1911
+ if (wait) {
1912
+ const deadline = Date.now() + waitTimeoutMs(9 * 60_000);
1913
+ const pollMs = Math.max(waitPollMs(), 0);
1914
+ while (slideshowCounts(data).generating > 0 && Date.now() < deadline) {
1915
+ await sleep(Math.min(pollMs, 15_000));
1916
+ data = await client.request({ path: statusPath });
1917
+ }
1918
+ }
1919
+ const counts = slideshowCounts(data);
1920
+ const stillRunning = wait && counts.generating > 0;
1921
+ const nextStep = counts.generating > 0
1922
+ ? ` Check again with: coauthor repurpose status ${projectId} --format slideshow --wait`
1923
+ : counts.failed > 0
1924
+ ? ' Retry the failed panels in the web app (Promote > Slideshow) or with coauthor image generate, then download.'
1925
+ : ` Save the PNGs with: coauthor repurpose download ${projectId} --format slideshow`;
1926
+ return {
1927
+ ok: counts.failed === 0 && !stillRunning,
1928
+ status: stillRunning ? 'still_running' : undefined,
1929
+ exitCode: stillRunning ? 2 : undefined,
1930
+ resume_command: stillRunning ? `coauthor repurpose status ${projectId} --format slideshow --wait` : undefined,
1931
+ message: `Slideshow images: ${counts.ready}/${counts.total} ready, ${counts.failed} failed, ${counts.generating} still generating.${nextStep}`,
1932
+ data,
1933
+ };
1934
+ }
1935
+ /** Path-safe folder for a CTA variant id (same rule the worker uses for its R2 keys). */
1936
+ function slideshowVariantFolder(variant) {
1937
+ return variant.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '') || 'variant';
1938
+ }
1939
+ /**
1940
+ * Renders the slideshow on the server and saves the PNGs as
1941
+ * <outDir>/slideshow/<variant>/slide-NN.png. Returns the relative paths written.
1942
+ */
1943
+ async function downloadSlideshowPngs(projectId, outDir, client, variant) {
1944
+ const rendered = await client.request({
1945
+ method: 'POST',
1946
+ path: `projects/${encodeURIComponent(projectId)}/repurpose/slideshow/render`,
1947
+ body: variant ? { variant } : {},
1948
+ });
1949
+ const variants = getResponseValue(rendered, 'variants');
1950
+ const files = [];
1951
+ const byVariant = {};
1952
+ for (const entry of Array.isArray(variants) ? variants : []) {
1953
+ const name = getResponseString(entry, 'variant');
1954
+ const slides = getResponseValue(entry, 'slides');
1955
+ if (!name || !Array.isArray(slides))
1956
+ continue;
1957
+ const folder = join('slideshow', slideshowVariantFolder(name));
1958
+ await mkdir(join(outDir, folder), { recursive: true });
1959
+ const written = [];
1960
+ for (const slide of slides) {
1961
+ const url = getResponseString(slide, 'url');
1962
+ const index = getResponseValue(slide, 'index');
1963
+ if (!url || typeof index !== 'number')
1964
+ continue;
1965
+ const relative = join(folder, `slide-${String(index).padStart(2, '0')}.png`);
1966
+ await writeFile(join(outDir, relative), await client.download(url));
1967
+ written.push(relative);
1968
+ }
1969
+ files.push(...written);
1970
+ byVariant[name] = written;
1971
+ }
1972
+ return {
1973
+ files,
1974
+ render_hash: getResponseString(rendered, 'render_hash') ?? null,
1975
+ stale: Boolean(getResponseValue(rendered, 'stale')),
1976
+ variants: byVariant,
1977
+ };
1978
+ }
1679
1979
  async function downloadRepurposed(projectId, format, outOption, client, variant) {
1680
1980
  const outDir = resolve(outOption ?? `coauthor-${projectId.slice(0, 8)}`);
1681
1981
  await mkdir(outDir, { recursive: true });
@@ -1698,6 +1998,7 @@ async function downloadRepurposed(projectId, format, outOption, client, variant)
1698
1998
  const manifest = {};
1699
1999
  const missingLink = [];
1700
2000
  let noVideoFile = false;
2001
+ const notReady = [];
1701
2002
  for (const entry of formats) {
1702
2003
  const shown = await client.request({ path: `projects/${encodeURIComponent(projectId)}/repurpose/${encodeURIComponent(entry)}` });
1703
2004
  const artifact = getResponseValue(shown, 'artifact');
@@ -1720,6 +2021,25 @@ async function downloadRepurposed(projectId, format, outOption, client, variant)
1720
2021
  noVideoFile = true;
1721
2022
  continue;
1722
2023
  }
2024
+ if (entry === 'slideshow' && artifact) {
2025
+ const panelsReady = extractNestedBoolean(shown, ['panels', 'all_ready']);
2026
+ // --format all skips a slideshow whose images are unfinished; an explicit
2027
+ // --format slideshow asks the server, which explains what is missing.
2028
+ if (format === 'all' && panelsReady !== true) {
2029
+ notReady.push(entry);
2030
+ continue;
2031
+ }
2032
+ const slideshow = await downloadSlideshowPngs(projectId, outDir, client, variant);
2033
+ written.push(...slideshow.files);
2034
+ await write('slideshow.json', JSON.stringify(artifact, null, 2));
2035
+ manifest[entry] = {
2036
+ stale: slideshow.stale || Boolean(getResponseValue(artifact, 'stale_at')),
2037
+ updated_at: getResponseValue(artifact, 'updated_at') ?? null,
2038
+ render_hash: slideshow.render_hash,
2039
+ variants: slideshow.variants,
2040
+ };
2041
+ continue;
2042
+ }
1723
2043
  if (!artifact || !copy) {
1724
2044
  skipped.push(entry);
1725
2045
  continue;
@@ -1734,20 +2054,21 @@ async function downloadRepurposed(projectId, format, outOption, client, variant)
1734
2054
  updated_at: getResponseValue(artifact, 'updated_at') ?? null,
1735
2055
  };
1736
2056
  }
1737
- await write('manifest.json', JSON.stringify({ project_id: projectId, downloaded_at: new Date().toISOString(), formats: manifest, skipped, missing_article_link: missingLink }, null, 2));
2057
+ await write('manifest.json', JSON.stringify({ project_id: projectId, downloaded_at: new Date().toISOString(), formats: manifest, skipped, not_ready: notReady, missing_article_link: missingLink }, null, 2));
1738
2058
  const staleNote = Object.entries(manifest).filter(([, value]) => value.stale).map(([key]) => key);
1739
2059
  return {
1740
2060
  ok: true,
1741
2061
  message: [
1742
2062
  `Wrote ${written.length} files to ${outDir}`,
1743
- skipped.length > 0 ? `Not generated yet: ${skipped.join(', ')} (coauthor repurpose generate ${projectId} --format <format>; slideshows are made in the web app).` : '',
2063
+ skipped.length > 0 ? `Not generated yet: ${skipped.join(', ')} (coauthor repurpose generate ${projectId} --format <format>).` : '',
1744
2064
  noVideoFile ? `The video has no finished render yet: coauthor repurpose render ${projectId} --format video --wait, then download again.` : '',
2065
+ notReady.length > 0 ? `Skipped the slideshow: its images are not all ready. Run coauthor repurpose status ${projectId} --format slideshow --wait, then download again.` : '',
1745
2066
  staleNote.length > 0 ? `Stale (the draft changed since they were made): ${staleNote.join(', ')}. Regenerate them before posting.` : '',
1746
2067
  missingLink.length > 0
1747
2068
  ? `No article link yet: ${missingLink.join(', ')} still contain {{POST_URL}}. Set it with coauthor repurpose save ${projectId} --format <format> --data '{"destination_url":"https://..."}' and download again, or replace it when posting.`
1748
2069
  : '',
1749
2070
  ].filter(Boolean).join('\n'),
1750
- data: { out_dir: outDir, files: written, skipped },
2071
+ data: { out_dir: outDir, files: written, skipped, not_ready: notReady },
1751
2072
  };
1752
2073
  }
1753
2074
  function renderRepurposeMarkdown(format, copy) {
@@ -1949,6 +2270,14 @@ function extractNestedString(value, path) {
1949
2270
  const current = extractNestedValue(value, path);
1950
2271
  return typeof current === 'string' ? current : undefined;
1951
2272
  }
2273
+ function extractNestedNumber(value, path) {
2274
+ const current = extractNestedValue(value, path);
2275
+ return typeof current === 'number' && Number.isFinite(current) ? current : undefined;
2276
+ }
2277
+ function extractNestedBoolean(value, path) {
2278
+ const current = extractNestedValue(value, path);
2279
+ return typeof current === 'boolean' ? current : undefined;
2280
+ }
1952
2281
  function extractNestedValue(value, path) {
1953
2282
  let current = value;
1954
2283
  for (const key of path) {
@@ -2010,6 +2339,7 @@ export function helpResult(command = []) {
2010
2339
  'Usage: coauthor <command> [options]',
2011
2340
  '',
2012
2341
  'Global options: --json, --help, --version, --base-url <url>, --token <token>',
2342
+ 'Requests time out after 120s (reads) or 330s (writes); override with COAUTHOR_CLI_REQUEST_TIMEOUT_MS.',
2013
2343
  'JSON options (--data, --contract) also accept @file.json, or @- to read stdin.',
2014
2344
  '',
2015
2345
  'Commands:',
@@ -2020,7 +2350,7 @@ export function helpResult(command = []) {
2020
2350
  ' contract show|save|approve',
2021
2351
  ' outline show|generate|revise|save|approve',
2022
2352
  ' research-plan show|generate|revise|save|approve',
2023
- ' repurpose list|generate|show|save|download|status|render',
2353
+ ' repurpose list|generate|show|save|status|render|download',
2024
2354
  ' brief review|answer',
2025
2355
  ' profile list|show',
2026
2356
  ' source list|add|remove',
@@ -2035,8 +2365,8 @@ export function helpResult(command = []) {
2035
2365
  ' image list|status|show|generate|edit|metadata',
2036
2366
  ' thread list|show|create|generate|save',
2037
2367
  ' slideshow show|save',
2038
- ' publish thread',
2039
- ' export list|wordpress',
2368
+ ' publish thread (supports --idempotency-key)',
2369
+ ' export list|wordpress (supports --idempotency-key)',
2040
2370
  ' operation list|show|status',
2041
2371
  ' credits',
2042
2372
  ' share <project-id>',
@@ -2049,6 +2379,12 @@ export function helpResult(command = []) {
2049
2379
  function commandHelp(command) {
2050
2380
  const key = command.join(' ');
2051
2381
  const help = {
2382
+ 'auth login': [
2383
+ 'Usage: coauthor auth login [--with-publish] [--no-browser] [--token <coa_...>] [--base-url <url>] [--json]',
2384
+ '',
2385
+ 'Signs in through the browser (device code). Without a browser, the URL is printed to open elsewhere.',
2386
+ '--token saves an existing token after checking its format and verifying it with the server.',
2387
+ ].join('\n'),
2052
2388
  'auth logout': [
2053
2389
  'Usage: coauthor auth logout [--local-only] [--json]',
2054
2390
  '',
@@ -2106,7 +2442,8 @@ function commandHelp(command) {
2106
2442
  project: [
2107
2443
  'Usage: coauthor project <create|list|show|rename|delete|duplicate> [<project-id>] [--title "..."] [--yes] [--json]',
2108
2444
  '',
2109
- 'create: --title, --topic, --audience, --contract <json|@file>. list: --limit. show: one project.',
2445
+ 'create: --title, --topic, --audience, --contract <json|@file>. show: one project.',
2446
+ 'list: --limit <n> (1-100), --cursor <next_cursor from the previous page>, --status <state> (a project_state such as research_running or editing, or the publication status submitted|published).',
2110
2447
  'duplicate <project-id> [--title "..."]: copies the brief, outline, research, chats, draft, images and repurposed posts into a new project that keeps the same profile (default title is "<title> (Copy)"). Prints the new project id.',
2111
2448
  ].join('\n'),
2112
2449
  profile: [
@@ -2131,18 +2468,22 @@ function commandHelp(command) {
2131
2468
  repurpose: [
2132
2469
  'Usage: coauthor repurpose list <project-id> [--json]',
2133
2470
  ' coauthor repurpose generate <project-id> --format <x-thread|x-post|linkedin|facebook|email|all> [--writing-model <id>] [--json]',
2471
+ ' coauthor repurpose generate <project-id> --format slideshow [--cta save,follow,comment,share,read_more,custom:<text>] [--writing-model <id>] [--json]',
2134
2472
  ' coauthor repurpose show <project-id> --format <format> [--json]',
2473
+ ' coauthor repurpose status <project-id> --format slideshow [--wait] [--json]',
2135
2474
  ' coauthor repurpose save <project-id> --format <format> --data @edits.json [--json]',
2136
2475
  ' coauthor repurpose download <project-id> [--format <format|article|all>] [--out <dir>] [--variant <id>]',
2137
- ' coauthor repurpose generate <project-id> --format video [--cta save,follow] [--writing-model <id>] [--json]',
2138
- ' coauthor repurpose status <project-id> --format video [--wait] [--json]',
2476
+ ' coauthor repurpose generate <project-id> --format <slideshow|video> [--cta save,follow] [--writing-model <id>] [--json]',
2477
+ ' coauthor repurpose status <project-id> --format <slideshow|video> [--wait] [--json]',
2139
2478
  ' coauthor repurpose render <project-id> --format video [--variant <id>] [--wait] [--json]',
2140
2479
  '',
2141
- 'Turns the finished draft into social posts and an email newsletter. generate takes about 20-90 seconds per format and replaces the previous version.',
2480
+ 'Turns the finished draft into social posts, an email newsletter, and a carousel slideshow. generate takes about 20-90 seconds per format and replaces the previous version.',
2142
2481
  'show returns data.copy (copy-ready text with the destination link filled in). download writes article.md, <format>.md, <format>.json, and manifest.json.',
2143
2482
  'Video: generate writes a short vertical deck and starts its slide images (1-3 minutes); --cta picks the ending call to action (comma-separated: save, follow, comment, share, read_more, custom:<text>; default save).',
2144
2483
  'status shows panels done/failed/generating and each render; render makes the MP4 (about 3 minutes, one render at a time per account; --wait polls up to 9 minutes, exit code 2 if still running); download saves finished MP4s as <out>/video-<variant>.mp4.',
2145
- 'Slideshows are generated in the web app; download includes them only as JSON once they exist. Publish an X thread with coauthor publish thread.',
2484
+ 'Slideshow: generate writes the slides and queues one image per panel (--cta picks up to 4 ending slides, default save; all is text formats only). status --wait waits up to 9 minutes for the images.',
2485
+ 'download --format slideshow renders 1080x1350 PNGs on the server into <out>/slideshow/<cta>/slide-NN.png (--variant picks one CTA); --format all includes them once every image is ready.',
2486
+ 'Publish an X thread with coauthor publish thread.',
2146
2487
  ].join('\n'),
2147
2488
  brief: [
2148
2489
  'Usage: coauthor brief review <project-id> [--json]',
@@ -2194,7 +2535,7 @@ function commandHelp(command) {
2194
2535
  'Usage: coauthor image <list|status|show|generate|edit|metadata> <project-id> [...] [--json]',
2195
2536
  ' coauthor image generate <project-id> --all [--wait] [--json] (every planned image; --wait until they finish)',
2196
2537
  '',
2197
- 'list: planned placeholders (use each id). generate/edit: --placeholder-id <id> [--edit-prompt "..."]. status: generation progress.',
2538
+ 'list: planned placeholders. generate/edit: --placeholder-id <id or placeholder_id> [--edit-prompt "..."]. status: generation progress.',
2198
2539
  'metadata <project-id> <placeholder id>: --alt-text, --description, --file-slug.',
2199
2540
  ].join('\n'),
2200
2541
  thread: [
@@ -2204,15 +2545,17 @@ function commandHelp(command) {
2204
2545
  'save takes {"posts":[...], "destination_url"?, "selected_social_account_id"?}. Publish with: coauthor publish thread <project-id> --yes',
2205
2546
  ].join('\n'),
2206
2547
  publish: [
2207
- 'Usage: coauthor publish thread <project-id> --yes [--json]',
2548
+ 'Usage: coauthor publish thread <project-id> --yes [--idempotency-key <key>] [--json]',
2208
2549
  '',
2209
2550
  'Posts the X thread now. Needs a login with publish permission: coauthor auth login --with-publish',
2551
+ 'Prints the operation key (data.idempotency_key in --json). If the command is interrupted, check it with coauthor operation status <key>, or rerun with --idempotency-key <key> to replay instead of posting twice.',
2210
2552
  ].join('\n'),
2211
2553
  export: [
2212
2554
  'Usage: coauthor export list <project-id> [--json]',
2213
- ' coauthor export wordpress <project-id> --yes --slug <slug> [--connection-id <id>] [--json]',
2555
+ ' coauthor export wordpress <project-id> --yes --slug <slug> [--connection-id <id>] [--idempotency-key <key>] [--json]',
2214
2556
  '',
2215
2557
  'wordpress creates a draft post on the connected WordPress site and returns wordpress_edit_url.',
2558
+ 'The export prints its operation key; check it with coauthor operation status <key>, or rerun with --idempotency-key <key> to replay safely.',
2216
2559
  'Needs a login with publish permission (coauthor auth login --with-publish). With several sites connected, the error lists their ids for --connection-id.',
2217
2560
  ].join('\n'),
2218
2561
  share: [
@@ -2253,7 +2596,8 @@ function commandHelp(command) {
2253
2596
  'image generate': [
2254
2597
  'Usage: coauthor image generate <project-id> --placeholder-id <id> [--grounding-mode <mode>] [--image-generation-model <id>] [--json]',
2255
2598
  '',
2256
- 'Pass the placeholder `id` from coauthor image list. Draft generation creates placeholders.',
2599
+ 'Pass the placeholder `id` (UUID) or its `placeholder_id` from coauthor image list. Draft generation creates placeholders.',
2600
+ 'Images are drawn from the planned brief; to steer one, generate it and then use coauthor image edit --edit-prompt.',
2257
2601
  'Generation is asynchronous: poll coauthor image status <project-id> --json until it is done.',
2258
2602
  ].join('\n'),
2259
2603
  'image edit': [