@clickminded/coauthor-cli 0.0.36 → 0.0.38

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/README.md CHANGED
@@ -70,7 +70,8 @@ Images, social, and export:
70
70
  ```sh
71
71
  coauthor image list <id> --json
72
72
  coauthor image generate <id> --placeholder-id <id or placeholder_id> [--prompt "what it should show"] --json
73
- coauthor image status <id> --json
73
+ coauthor image status <id> [--artifact article|slideshow|video] --json
74
+ coauthor image replace <id> --placeholder-id <panel id> --file <path> --json # slideshow/video panels only
74
75
  coauthor repurpose generate <id> --format all --json # X thread and post, LinkedIn, Facebook, email newsletter
75
76
  coauthor repurpose download <id> --out ./social # copy-ready files plus the article
76
77
  coauthor share <id> --json # public read-only link
@@ -10,6 +10,7 @@ export type CommandContext = {
10
10
  token: string;
11
11
  };
12
12
  export declare function runCommand(input: ParsedCommand, context: CommandContext): Promise<CommandResult>;
13
+ export declare function describeImageOperation(operation: JsonValue | undefined): string | null;
13
14
  export declare function openBrowser(url: string, spawnImpl?: typeof spawn, warn?: (line: string) => void): void;
14
15
  /**
15
16
  * `--cta save,follow,custom:Join the webinar` -> the web app's cta_variants
package/dist/commands.js CHANGED
@@ -722,7 +722,7 @@ const DRAFT_SAVE_SHAPE = 'Payload: {"document_id":"<from draft get>","expected_b
722
722
  // The actions each resource supports on the Agent API. Anything else used to
723
723
  // reach the server and come back as "Agent API route not found".
724
724
  const RESOURCE_ACTIONS = {
725
- images: ['list', 'status', 'show', 'generate', 'edit', 'metadata'],
725
+ images: ['list', 'status', 'show', 'generate', 'edit', 'metadata', 'replace'],
726
726
  threads: ['list', 'show', 'status', 'generate', 'save', 'create'],
727
727
  slideshows: ['list', 'show', 'status', 'generate', 'save'],
728
728
  publish: ['thread'],
@@ -743,6 +743,7 @@ async function runResourceCommand(resource, action, input, client) {
743
743
  if (!projectId)
744
744
  throw new Error(`Missing project id. Usage: coauthor ${name} ${resolvedAction} <project-id> [...]`);
745
745
  const basePath = `projects/${encodeURIComponent(projectId)}/${resource}`;
746
+ const artifactQuery = imageArtifactQuery(resource, resolvedAction, input);
746
747
  if (resolvedAction === 'list') {
747
748
  // These lists return everything for the project; the server has no
748
749
  // filters or pages for them, so don't pretend to send any.
@@ -751,12 +752,12 @@ async function runResourceCommand(resource, action, input, client) {
751
752
  throw new Error(`${name} list does not support --${flag}; it always returns every ${name === 'export' ? 'export' : 'item'} for the project.`);
752
753
  }
753
754
  }
754
- const data = await client.request({ path: basePath });
755
+ const data = await client.request({ path: `${basePath}${artifactQuery}` });
755
756
  return { ok: true, data };
756
757
  }
757
758
  if (resolvedAction === 'show' || resolvedAction === 'status') {
758
759
  if (resource === 'images' && resolvedAction === 'status') {
759
- const data = await client.request({ path: `${basePath}/status` });
760
+ const data = await client.request({ path: `${basePath}/status${artifactQuery}` });
760
761
  return { ok: true, data };
761
762
  }
762
763
  if (resource === 'threads' || resource === 'slideshows') {
@@ -782,7 +783,13 @@ async function runResourceCommand(resource, action, input, client) {
782
783
  if (getString(input.values, 'prompt') !== undefined) {
783
784
  throw new Error('--prompt steers one image: use it with --placeholder-id <id>, not --all.');
784
785
  }
785
- return generateAllImages(client, projectId, getBoolean(input.values, 'wait'));
786
+ if (getString(input.values, 'idempotency-key') !== undefined) {
787
+ throw new Error('--idempotency-key names one image job: use it with --placeholder-id <id>, not --all (each image gets its own key in data.operations).');
788
+ }
789
+ return generateAllImages(client, projectId, getBoolean(input.values, 'wait'), artifactQuery);
790
+ }
791
+ if (resource === 'images' && resolvedAction === 'replace') {
792
+ return replaceImage(client, input, basePath, projectId, resourceId);
786
793
  }
787
794
  if (resource === 'images' && resolvedAction === 'metadata') {
788
795
  if (!resourceId) {
@@ -830,9 +837,115 @@ async function runResourceCommand(resource, action, input, client) {
830
837
  'edit-prompt',
831
838
  ]);
832
839
  const path = resolvedAction === 'create' && resource !== 'threads' ? basePath : `${basePath}/${resolvedAction}`;
840
+ if (resource === 'images' && (resolvedAction === 'generate' || resolvedAction === 'edit')) {
841
+ return imageOperationRequest(client, input, projectId, path, body, resolvedAction);
842
+ }
833
843
  const data = await client.request({ method: 'POST', path, body });
834
844
  return { ok: true, data };
835
845
  }
846
+ // Image generate/edit is recorded as an image.generate/image.edit operation
847
+ // under its Idempotency-Key: print the key so the caller can follow the job
848
+ // to the finished image (`operation status`) or retry it safely.
849
+ async function imageOperationRequest(client, input, projectId, path, body, action) {
850
+ const idempotencyKey = getString(input.values, 'idempotency-key')?.trim() || randomUUID();
851
+ const data = await client.request({ method: 'POST', path, body, idempotencyKey });
852
+ const operation = getResponseValue(data, 'operation');
853
+ // A server without image operations returns only the job.
854
+ if (!operation || typeof operation !== 'object' || Array.isArray(operation))
855
+ return { ok: true, data };
856
+ const lookup = `Operation key: ${idempotencyKey} (coauthor operation status ${idempotencyKey} --json).`;
857
+ if (getResponseValue(data, 'replayed') === true) {
858
+ const status = typeof operation.status === 'string' ? operation.status : 'unknown';
859
+ return {
860
+ ok: true,
861
+ message: `Replayed recorded image ${action} operation (${status}); no new job was queued. ${lookup}`,
862
+ idempotency_key: idempotencyKey,
863
+ data,
864
+ };
865
+ }
866
+ return {
867
+ ok: true,
868
+ message: `Image ${action === 'edit' ? 'edit' : 'generation'} queued. ${lookup} Or poll coauthor image status ${projectId} --json.`,
869
+ idempotency_key: idempotencyKey,
870
+ data,
871
+ };
872
+ }
873
+ const IMAGE_ARTIFACTS = ['article', 'slideshow', 'video'];
874
+ // `--artifact article|slideshow|video` narrows image list/status (and
875
+ // generate --all) to one artifact's placeholders. Without it, every image.
876
+ function imageArtifactQuery(resource, action, input) {
877
+ const artifact = getString(input.values, 'artifact');
878
+ if (artifact === undefined)
879
+ return '';
880
+ const supported = resource === 'images'
881
+ && (action === 'list' || action === 'status' || (action === 'generate' && getBoolean(input.values, 'all')));
882
+ if (!supported) {
883
+ throw new Error('--artifact works with image list, image status, and image generate --all.');
884
+ }
885
+ const value = artifact.trim().toLowerCase();
886
+ if (!IMAGE_ARTIFACTS.includes(value)) {
887
+ throw new Error(`--artifact must be article, slideshow, or video (got "${artifact}").`);
888
+ }
889
+ return `?artifact=${value}`;
890
+ }
891
+ const REPLACE_IMAGE_MAX_BYTES = 12 * 1024 * 1024;
892
+ const REPLACE_IMAGE_TYPES = {
893
+ png: 'image/png',
894
+ jpg: 'image/jpeg',
895
+ jpeg: 'image/jpeg',
896
+ webp: 'image/webp',
897
+ gif: 'image/gif',
898
+ avif: 'image/avif',
899
+ };
900
+ const REPLACE_USAGE = 'Usage: coauthor image replace <project-id> --placeholder-id <id> (--file <path> | --url <url>) [--json]';
901
+ // Replaces a slideshow or video panel's image with your own. The panel is
902
+ // then marked uploaded: image edit still works, image generate is refused.
903
+ async function replaceImage(client, input, basePath, projectId, positionalId) {
904
+ const placeholderRef = getString(input.values, 'placeholder-id') ?? positionalId;
905
+ if (!placeholderRef)
906
+ throw new Error(`Missing --placeholder-id. ${REPLACE_USAGE}`);
907
+ const file = getString(input.values, 'file');
908
+ const url = getString(input.values, 'url');
909
+ if (file !== undefined && url !== undefined)
910
+ throw new Error(`Pass --file or --url, not both. ${REPLACE_USAGE}`);
911
+ if (!file && !url)
912
+ throw new Error(`Pass the new image with --file <path> or --url <url>. ${REPLACE_USAGE}`);
913
+ let body;
914
+ if (url) {
915
+ if (!/^https?:\/\//i.test(url.trim()))
916
+ throw new Error('--url must be an http or https URL.');
917
+ body = { url: url.trim() };
918
+ }
919
+ else {
920
+ const path = resolve(file);
921
+ const extension = path.split('.').pop()?.toLowerCase() ?? '';
922
+ const contentType = REPLACE_IMAGE_TYPES[extension];
923
+ if (!contentType)
924
+ throw new Error('--file must be a PNG, JPEG, WebP, GIF, or AVIF image (.png, .jpg, .jpeg, .webp, .gif, .avif).');
925
+ let bytes;
926
+ try {
927
+ bytes = await readFile(path);
928
+ }
929
+ catch {
930
+ throw new Error(`Could not read --file ${file}.`);
931
+ }
932
+ if (bytes.length === 0)
933
+ throw new Error(`--file ${file} is empty.`);
934
+ if (bytes.length > REPLACE_IMAGE_MAX_BYTES)
935
+ throw new Error(`--file ${file} is too large (max 12 MB).`);
936
+ body = { data: bytes.toString('base64'), content_type: contentType, filename: basename(path) };
937
+ }
938
+ const data = await client.request({
939
+ method: 'POST',
940
+ path: `${basePath}/${encodeURIComponent(placeholderRef)}/replace`,
941
+ body,
942
+ });
943
+ return {
944
+ ok: true,
945
+ message: `Replaced the image for ${placeholderRef}. It is marked uploaded: coauthor image edit still works; image generate is refused for it. Check it with: coauthor image show ${projectId} ${placeholderRef} --json`,
946
+ data,
947
+ };
948
+ }
836
949
  // Publish and export run as recorded operations keyed by the Idempotency-Key.
837
950
  // Print the key so the caller can look the outcome up (`operation status`) or
838
951
  // replay the same request safely with --idempotency-key.
@@ -888,15 +1001,37 @@ function exportRequestBody(action, input) {
888
1001
  async function runOperationCommand(action, input, client) {
889
1002
  const key = getString(input.values, 'id') ?? input.positionals[0];
890
1003
  if (!action || action === 'list') {
891
- return { ok: true, data: await client.request({ path: 'operations' }) };
1004
+ const projectId = getString(input.values, 'project');
1005
+ const path = projectId ? `operations?project_id=${encodeURIComponent(projectId)}` : 'operations';
1006
+ return { ok: true, data: await client.request({ path }) };
892
1007
  }
893
1008
  if (action === 'show' || action === 'status') {
894
1009
  if (!key)
895
1010
  throw new Error('Usage: coauthor operation status <operationKey>');
896
- return { ok: true, data: await client.request({ path: `operations/${encodeURIComponent(key)}` }) };
1011
+ const data = await client.request({ path: `operations/${encodeURIComponent(key)}` });
1012
+ const message = describeImageOperation(getResponseValue(data, 'operation'));
1013
+ return message ? { ok: true, message, data } : { ok: true, data };
897
1014
  }
898
1015
  throw new Error('Usage: coauthor operation <list|show|status>');
899
1016
  }
1017
+ // One line for an image.generate/image.edit operation, e.g.
1018
+ // "image.generate succeeded: https://...". Other operations print as before.
1019
+ export function describeImageOperation(operation) {
1020
+ if (!operation || typeof operation !== 'object' || Array.isArray(operation))
1021
+ return null;
1022
+ const action = typeof operation.action === 'string' ? operation.action : '';
1023
+ if (action !== 'image.generate' && action !== 'image.edit')
1024
+ return null;
1025
+ const status = typeof operation.status === 'string' ? operation.status : 'unknown';
1026
+ const result = operation.result && typeof operation.result === 'object' && !Array.isArray(operation.result) ? operation.result : {};
1027
+ const error = typeof operation.error_message === 'string' ? operation.error_message : null;
1028
+ if (status === 'succeeded') {
1029
+ return typeof result.final_image_url === 'string' ? `${action} succeeded: ${result.final_image_url}` : `${action} succeeded.`;
1030
+ }
1031
+ if (status === 'running' || status === 'pending')
1032
+ return `${action} running: the image is still generating. Check again shortly.`;
1033
+ return error ? `${action} ${status}: ${error}` : `${action} ${status}.`;
1034
+ }
900
1035
  const SKILL_NAMES = ['claude', 'codex', 'agents', 'cursor'];
901
1036
  const AGENT_LABELS = {
902
1037
  claude: 'Claude Code',
@@ -2120,16 +2255,20 @@ function imageStatusRows(data) {
2120
2255
  // Generates every planned image that isn't already done or generating, then
2121
2256
  // optionally waits (under the 10-minute agent shell limit) until none are
2122
2257
  // still generating.
2123
- async function generateAllImages(client, projectId, wait) {
2124
- const statusPath = `projects/${encodeURIComponent(projectId)}/images/status`;
2258
+ async function generateAllImages(client, projectId, wait, artifactQuery = '') {
2259
+ const statusPath = `projects/${encodeURIComponent(projectId)}/images/status${artifactQuery}`;
2125
2260
  const before = imageStatusRows(await client.request({ path: statusPath }));
2126
2261
  const toGenerate = before.filter((row) => row.status !== 'done' && row.status !== 'generating');
2127
2262
  const started = [];
2263
+ const operations = [];
2128
2264
  const failedToStart = [];
2129
2265
  for (const row of toGenerate) {
2266
+ // Each image is its own recorded operation (coauthor operation status <key>).
2267
+ const idempotencyKey = randomUUID();
2130
2268
  try {
2131
- await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/images/generate`, body: { placeholderId: row.id } });
2269
+ await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/images/generate`, body: { placeholderId: row.id }, idempotencyKey });
2132
2270
  started.push(row.id);
2271
+ operations.push({ placeholder_id: row.id, idempotency_key: idempotencyKey });
2133
2272
  }
2134
2273
  catch (error) {
2135
2274
  failedToStart.push({ id: row.id, error: error instanceof Error ? error.message : String(error) });
@@ -2154,6 +2293,7 @@ async function generateAllImages(client, projectId, wait) {
2154
2293
  failed: wait ? count('failed') : null,
2155
2294
  generating,
2156
2295
  failed_to_start: failedToStart,
2296
+ operations,
2157
2297
  };
2158
2298
  return {
2159
2299
  ok: failedToStart.length === 0 && (!wait || count('failed') === 0),
@@ -2367,12 +2507,12 @@ export function helpResult(command = []) {
2367
2507
  ' draft get supports --format json|markdown|html|text',
2368
2508
  ' workflow show|status|advance|run|rewind|approve|resume',
2369
2509
  ' workflow run/advance supports --briefing-mode auto|strict|off and --require-brief-review',
2370
- ' image list|status|show|generate|edit|metadata',
2510
+ ' image list|status|show|generate|edit|metadata|replace',
2371
2511
  ' thread list|show|create|generate|save',
2372
2512
  ' slideshow show|save',
2373
2513
  ' publish thread (supports --idempotency-key)',
2374
2514
  ' export list|wordpress (supports --idempotency-key)',
2375
- ' operation list|show|status',
2515
+ ' operation list|show|status (publish, export and image generate/edit)',
2376
2516
  ' credits',
2377
2517
  ' share <project-id>',
2378
2518
  ' models list|preferences show|preferences set',
@@ -2537,11 +2677,13 @@ function commandHelp(command) {
2537
2677
  "Talk to CoAuthor about the project. The reply text is in data.text. Re-read the artifact afterwards: CoAuthor's summary can differ from what was saved.",
2538
2678
  ].join('\n'),
2539
2679
  image: [
2540
- 'Usage: coauthor image <list|status|show|generate|edit|metadata> <project-id> [...] [--json]',
2541
- ' coauthor image generate <project-id> --all [--wait] [--json] (every planned image; --wait until they finish)',
2680
+ 'Usage: coauthor image <list|status|show|generate|edit|metadata|replace> <project-id> [...] [--json]',
2681
+ ' coauthor image generate <project-id> --all [--artifact <kind>] [--wait] [--json] (every planned image; --wait until they finish)',
2542
2682
  '',
2543
2683
  'list: planned placeholders. generate/edit: --placeholder-id <id or placeholder_id> [--edit-prompt "..."]. status: generation progress.',
2684
+ 'list/status: --artifact article|slideshow|video shows one artifact\'s images (each carries artifact, slot and source).',
2544
2685
  'metadata <project-id> <placeholder id>: --alt-text, --description, --file-slug.',
2686
+ 'replace <project-id> --placeholder-id <id> (--file <path> | --url <url>): use your own image for a slideshow or video panel.',
2545
2687
  ].join('\n'),
2546
2688
  thread: [
2547
2689
  'Usage: coauthor thread <show|generate|save> <project-id> [--data <json|@file>] [--writing-model <id>] [--json]',
@@ -2599,18 +2741,36 @@ function commandHelp(command) {
2599
2741
  'show: status and the proposed groups. apply: keep every group, or only --accept / all but --reject. discard: drop the revision (cancels it if still running).',
2600
2742
  ].join('\n'),
2601
2743
  'image generate': [
2602
- 'Usage: coauthor image generate <project-id> --placeholder-id <id> [--prompt "..."] [--grounding-mode <mode>] [--image-generation-model <id>] [--json]',
2744
+ 'Usage: coauthor image generate <project-id> --placeholder-id <id> [--prompt "..."] [--grounding-mode <mode>] [--image-generation-model <id>] [--idempotency-key <key>] [--json]',
2603
2745
  '',
2604
2746
  'Pass the placeholder `id` (UUID) or its `placeholder_id` from coauthor image list. Draft generation creates placeholders.',
2605
2747
  'Images are drawn from the planned brief. --prompt replaces what the image shows (the planned scene, its required elements and, on photo + doodle images, the planned doodles)',
2606
2748
  'and is saved, so later regenerations keep it;',
2607
2749
  'the profile\'s visual style still applies. Comparison and technical-diagram images have no scene to replace: generate them, then use image edit --edit-prompt.',
2608
2750
  'Generation is asynchronous: poll coauthor image status <project-id> --json until it is done.',
2751
+ 'Prints an operation key (data.idempotency_key in --json): coauthor operation status <key> reports the finished image url or the error.',
2752
+ '--idempotency-key <key> replays an earlier request with that key instead of queueing a second job. With --all, each image gets its own key (data.operations).',
2753
+ ].join('\n'),
2754
+ 'image replace': [
2755
+ REPLACE_USAGE,
2756
+ '',
2757
+ 'Replaces a slideshow or video panel\'s image with your own (PNG, JPEG, WebP, GIF or AVIF, up to 12 MB).',
2758
+ 'Find panels with coauthor image list <project-id> --artifact slideshow (or video); pass the placeholder id or placeholder_id.',
2759
+ 'The panel is then marked uploaded (source: "uploaded"): image edit still works, image generate is refused (uploaded_image),',
2760
+ 'and restyling panels skips it. Article and featured images cannot be replaced here.',
2609
2761
  ].join('\n'),
2610
2762
  'image edit': [
2611
- 'Usage: coauthor image edit <project-id> --placeholder-id <id> --edit-prompt "..." [--json]',
2763
+ 'Usage: coauthor image edit <project-id> --placeholder-id <id> --edit-prompt "..." [--idempotency-key <key>] [--json]',
2612
2764
  '',
2613
2765
  'Edits the current image for a placeholder. Poll coauthor image status <project-id> --json for the result.',
2766
+ 'Prints an operation key: coauthor operation status <key> reports the edited image url or the error; --idempotency-key <key> replays instead of editing twice.',
2767
+ ].join('\n'),
2768
+ operation: [
2769
+ 'Usage: coauthor operation list [--project <project-id>] [--json]',
2770
+ ' coauthor operation status <key> [--json] (show is the same)',
2771
+ '',
2772
+ 'Recorded publish, export and image generate/edit requests, looked up by the operation key the command printed.',
2773
+ 'Image operations report succeeded (with data.operation.result.final_image_url), running, failed (with error_message), or unknown (superseded or cleared before it finished).',
2614
2774
  ].join('\n'),
2615
2775
  'contract save': [
2616
2776
  'Usage: coauthor contract save <project-id> --data @contract.json [--json]',
package/dist/parser.js CHANGED
@@ -77,6 +77,9 @@ const OPTIONS = {
77
77
  accept: { type: 'string' },
78
78
  reject: { type: 'string' },
79
79
  'idempotency-key': { type: 'string' },
80
+ file: { type: 'string' },
81
+ url: { type: 'string' },
82
+ artifact: { type: 'string' },
80
83
  };
81
84
  /** True when `--name` (or its short alias) consumes the next argv entry as its value. */
82
85
  export function optionTakesValue(flag) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.36",
3
+ "version": "0.0.38",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -8,11 +8,14 @@ Draft generation plans image placeholders, including a featured image (`is_featu
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
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
  - To steer what it shows, add `--prompt "..."`: it replaces the planned image (scene, required elements and, on photo + doodle images, the planned doodles; describe the subject and composition, and the writer profile's visual style is still applied, so don't name an art style). It is saved, so later regenerations keep it. Use it when the planned brief is off-topic or wrong, not for small tweaks to a finished image (that's `image edit`). Comparison and technical-diagram images refuse it (`structured_brief`); generate those, then edit.
11
+ - Each generate or edit prints an operation key (`idempotency_key`). `coauthor operation status <key> --json` reports `running`, `succeeded` (with the image URL), `failed` (with the error), or `unknown`. After a timeout or network error, check that key, or rerun with `--idempotency-key <key>`: a replay returns the recorded job instead of generating (and charging for) the image twice.
11
12
  4. Check every finished image (the URLs are in `image status` and in `draft get --format markdown`):
12
13
  - Charts and tables must match the article's numbers, and must not state figures the article deliberately leaves open.
13
14
  - Screens of real products (for example a Google or Meta interface) must not be presented as genuine.
14
15
  - Prices, dates, and text inside the image must match the article.
15
16
  5. Fix an image with an instruction: `coauthor image edit <id> --placeholder-id <id UUID> --edit-prompt "Remove the price tag; keep everything else." --json`, then poll `image status` again. To drop an image entirely, remove its `imagePlaceholder` node with a direct draft edit (`references/editing-drafts.md`).
17
+ - Replace a slideshow or video panel with the user's own image: `coauthor image replace <id> --placeholder-id <id> --file <path>` (or `--url <url>`; PNG, JPEG, WebP, GIF, or AVIF, up to about 3 MB as a file, larger by URL). The panel is then marked `source: "uploaded"`: `image edit` still works, `image generate` is refused (`uploaded_image`). Article images can't be replaced from the CLI.
18
+ - `image list` and `image status` include slideshow and video panels; each row has `artifact` (`article`, `slideshow`, `video`) and `slot`. Filter with `--artifact article|slideshow|video` (also on `image generate --all`).
16
19
  6. Rewrite the SEO metadata for every generated image: `coauthor image metadata <id> <placeholder id UUID> --alt-text "..." --file-slug "..." --description "..." --json`. This is required, not polish: the stored alt text was written from the plan before the image existed and often describes things that aren't in the picture. Alt text must describe what is actually visible.
17
20
 
18
21
  Images cost credits each time they are generated or edited, so check the brief and placeholder purpose before regenerating.
@@ -52,6 +52,8 @@ A carousel of 1080x1350 slides (for LinkedIn or Instagram) with illustrated pane
52
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
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
54
 
55
+ Each slide's illustrated panel can be fixed one at a time, the same as article images (see `references/images-and-social.md`): `coauthor image list <id> --artifact slideshow --json` lists the panels with their `slot` (slide number, core or CTA ending), then `image generate --placeholder-id <id> [--prompt "..."]`, `image edit --placeholder-id <id> --edit-prompt "..."`, or `image replace --placeholder-id <id> --file <path>|--url <url>` to use the user's own image. Download again afterwards to get the new PNGs.
56
+
55
57
  The server draws the slides with the Inter font, so line breaks can differ slightly from the web app's own PNG download.
56
58
 
57
59
  ## Video
@@ -63,6 +65,8 @@ A short vertical video (1080x1920) of the article's key points, with illustrated
63
65
  3. `coauthor repurpose render <id> --format video [--variant <id>] --wait --json` renders the MP4. It takes about 3 minutes for a typical video and runs on a shared queue, so only one render per account at a time: `render_in_progress` (429) means wait for the current one. `panels_not_ready` (409) means the panel images aren't finished yet.
64
66
  4. `coauthor repurpose download <id> --format video --out <dir>` saves `video-<variant>.mp4`.
65
67
 
68
+ To fix one panel before rendering: `coauthor image list <id> --artifact video --json`, then `image generate`, `image edit`, or `image replace` on its `--placeholder-id`, and render again.
69
+
66
70
  ## Deliver
67
71
 
68
72
  `coauthor repurpose download <id> --out <dir>` writes:
@@ -31,8 +31,10 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
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
33
  | `structured_brief` | `image generate --prompt` on a comparison or technical-diagram image, which is built from structured fields. | Generate without `--prompt`, then `image edit --edit-prompt "..."`. |
34
+ | `uploaded_image` | `image generate` on an image the user replaced with their own file. | Use `image edit --edit-prompt "..."`, or `image replace` again. |
35
+ | `not_a_panel` | `image replace` on an article image. | Only slideshow and video panels can be replaced from the CLI. |
34
36
  | `usage_error` | The command or its flags are wrong; nothing was sent. | Check `coauthor help <command>` and fix the command. |
35
- | `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. |
37
+ | `request_timeout`, `network_error` | No answer from CoAuthor in time, or the connection failed. | For reads, retry. For exports, publishes, and image generate/edit, check `coauthor operation status <idempotency_key>` before retrying. |
36
38
 
37
39
  ## Sign-in
38
40
 
@@ -337,11 +337,14 @@ Draft generation plans image placeholders, including a featured image (`is_featu
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
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
  - To steer what it shows, add `--prompt "..."`: it replaces the planned image (scene, required elements and, on photo + doodle images, the planned doodles; describe the subject and composition, and the writer profile's visual style is still applied, so don't name an art style). It is saved, so later regenerations keep it. Use it when the planned brief is off-topic or wrong, not for small tweaks to a finished image (that's `image edit`). Comparison and technical-diagram images refuse it (`structured_brief`); generate those, then edit.
340
+ - Each generate or edit prints an operation key (`idempotency_key`). `coauthor operation status <key> --json` reports `running`, `succeeded` (with the image URL), `failed` (with the error), or `unknown`. After a timeout or network error, check that key, or rerun with `--idempotency-key <key>`: a replay returns the recorded job instead of generating (and charging for) the image twice.
340
341
  4. Check every finished image (the URLs are in `image status` and in `draft get --format markdown`):
341
342
  - Charts and tables must match the article's numbers, and must not state figures the article deliberately leaves open.
342
343
  - Screens of real products (for example a Google or Meta interface) must not be presented as genuine.
343
344
  - Prices, dates, and text inside the image must match the article.
344
345
  5. Fix an image with an instruction: `coauthor image edit <id> --placeholder-id <id UUID> --edit-prompt "Remove the price tag; keep everything else." --json`, then poll `image status` again. To drop an image entirely, remove its `imagePlaceholder` node with a direct draft edit (`references/editing-drafts.md`).
346
+ - Replace a slideshow or video panel with the user's own image: `coauthor image replace <id> --placeholder-id <id> --file <path>` (or `--url <url>`; PNG, JPEG, WebP, GIF, or AVIF, up to about 3 MB as a file, larger by URL). The panel is then marked `source: "uploaded"`: `image edit` still works, `image generate` is refused (`uploaded_image`). Article images can't be replaced from the CLI.
347
+ - `image list` and `image status` include slideshow and video panels; each row has `artifact` (`article`, `slideshow`, `video`) and `slot`. Filter with `--artifact article|slideshow|video` (also on `image generate --all`).
345
348
  6. Rewrite the SEO metadata for every generated image: `coauthor image metadata <id> <placeholder id UUID> --alt-text "..." --file-slug "..." --description "..." --json`. This is required, not polish: the stored alt text was written from the plan before the image existed and often describes things that aren't in the picture. Alt text must describe what is actually visible.
346
349
 
347
350
  Images cost credits each time they are generated or edited, so check the brief and placeholder purpose before regenerating.
@@ -453,6 +456,8 @@ A carousel of 1080x1350 slides (for LinkedIn or Instagram) with illustrated pane
453
456
  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.
454
457
  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.
455
458
 
459
+ Each slide's illustrated panel can be fixed one at a time, the same as article images (see `references/images-and-social.md`): `coauthor image list <id> --artifact slideshow --json` lists the panels with their `slot` (slide number, core or CTA ending), then `image generate --placeholder-id <id> [--prompt "..."]`, `image edit --placeholder-id <id> --edit-prompt "..."`, or `image replace --placeholder-id <id> --file <path>|--url <url>` to use the user's own image. Download again afterwards to get the new PNGs.
460
+
456
461
  The server draws the slides with the Inter font, so line breaks can differ slightly from the web app's own PNG download.
457
462
 
458
463
  ### Video
@@ -464,6 +469,8 @@ A short vertical video (1080x1920) of the article's key points, with illustrated
464
469
  3. `coauthor repurpose render <id> --format video [--variant <id>] --wait --json` renders the MP4. It takes about 3 minutes for a typical video and runs on a shared queue, so only one render per account at a time: `render_in_progress` (429) means wait for the current one. `panels_not_ready` (409) means the panel images aren't finished yet.
465
470
  4. `coauthor repurpose download <id> --format video --out <dir>` saves `video-<variant>.mp4`.
466
471
 
472
+ To fix one panel before rendering: `coauthor image list <id> --artifact video --json`, then `image generate`, `image edit`, or `image replace` on its `--placeholder-id`, and render again.
473
+
467
474
  ### Deliver
468
475
 
469
476
  `coauthor repurpose download <id> --out <dir>` writes:
@@ -510,8 +517,10 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
510
517
  | `insufficient_scope` | The token can't publish. | `coauthor auth login --with-publish`. |
511
518
  | `wordpress_connection_required` | Several WordPress sites are connected. | Ask which one from `details.connections`, add `--connection-id`. |
512
519
  | `structured_brief` | `image generate --prompt` on a comparison or technical-diagram image, which is built from structured fields. | Generate without `--prompt`, then `image edit --edit-prompt "..."`. |
520
+ | `uploaded_image` | `image generate` on an image the user replaced with their own file. | Use `image edit --edit-prompt "..."`, or `image replace` again. |
521
+ | `not_a_panel` | `image replace` on an article image. | Only slideshow and video panels can be replaced from the CLI. |
513
522
  | `usage_error` | The command or its flags are wrong; nothing was sent. | Check `coauthor help <command>` and fix the command. |
514
- | `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. |
523
+ | `request_timeout`, `network_error` | No answer from CoAuthor in time, or the connection failed. | For reads, retry. For exports, publishes, and image generate/edit, check `coauthor operation status <idempotency_key>` before retrying. |
515
524
 
516
525
  ### Sign-in
517
526