@clickminded/coauthor-cli 0.0.19 → 0.0.21

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
@@ -134,7 +134,9 @@ Images and social content:
134
134
 
135
135
  ```sh
136
136
  coauthor image list <project-id> --json
137
- coauthor image generate <project-id> --placeholder-id <placeholder-id> --prompt "Image direction" --json
137
+ coauthor image generate <project-id> --placeholder-id <placeholder-id> --json
138
+ coauthor image status <project-id> --json
139
+ coauthor image edit <project-id> --placeholder-id <placeholder-id> --edit-prompt "Make the sky overcast" --json
138
140
  coauthor thread generate <project-id> --writing-model gpt-5.6-terra --json
139
141
  ```
140
142
 
@@ -166,7 +168,7 @@ Then run live actions only when you mean to publish or export:
166
168
  ```sh
167
169
  coauthor publish thread <project-id> --yes --json
168
170
  coauthor export blog <project-id> --yes --slug "post-slug" --json
169
- coauthor export clickminded <project-id> --yes --json
171
+ coauthor export clickminded <project-id> --yes --permalink <permalink> --json
170
172
  coauthor export wordpress <project-id> --yes --slug "post-slug" --json
171
173
  coauthor operation status <operation-key> --json
172
174
  ```
package/dist/commands.js CHANGED
@@ -7,7 +7,7 @@ import { dirname, join, resolve } from 'node:path';
7
7
  import { fileURLToPath } from 'node:url';
8
8
  import { AgentHttpError, normalizeBaseUrl } from './client.js';
9
9
  import { clearConfig, loadConfig, saveConfig } from './config.js';
10
- import { getBoolean, getString, parseJsonOption } from './parser.js';
10
+ import { getBoolean, getString, parseJsonOption, readJsonOptionText } from './parser.js';
11
11
  export async function runCommand(input, context) {
12
12
  const [scope, action] = input.command;
13
13
  if (!scope)
@@ -270,7 +270,13 @@ async function runWorkflowCommand(action, input, context) {
270
270
  return { ok: true, data };
271
271
  }
272
272
  if (action === 'resume') {
273
- const target = normalizeWorkflowWaitTarget(getString(input.values, 'target') ?? getString(input.values, 'stage')) ?? 'draft';
273
+ const requestedTarget = getString(input.values, 'target') ?? getString(input.values, 'stage');
274
+ const target = normalizeWorkflowWaitTarget(requestedTarget);
275
+ // An unsupported target used to fall back to 'draft' and run the whole
276
+ // pipeline (research + draft credits) when the caller meant an earlier stage.
277
+ if (!target) {
278
+ throw new Error(`workflow resume supports --target research or draft (got "${requestedTarget}"). To advance to an earlier stage, use \`coauthor workflow run ${projectId} --target <contract|outline|research-plan>\`.`);
279
+ }
274
280
  if (target === 'research' && (getString(input.values, 'planning-model') || getString(input.values, 'writing-model'))) {
275
281
  throw new Error('workflow resume --target research does not support --planning-model or --writing-model.');
276
282
  }
@@ -405,6 +411,12 @@ async function runArtifactCommand(artifact, action, input, client) {
405
411
  const data = await client.request({ path: basePath });
406
412
  return { ok: true, data };
407
413
  }
414
+ if (artifact === 'contract' && action === 'generate') {
415
+ throw new Error('contract generate is not supported. The brief comes from `coauthor project create`; refine it with `coauthor chat <project-id> --stage contract --message "..."` or replace it with `coauthor contract save <project-id> --data @contract.json`.');
416
+ }
417
+ if (action === 'save' && readJsonOptionText(input.values) === undefined) {
418
+ throw new Error(`Usage: coauthor ${artifact} save <projectId> --data '<json>' (or --data @file.json). ${artifactSaveShape(artifact)}`);
419
+ }
408
420
  if (action === 'generate' || action === 'save' || action === 'approve') {
409
421
  const body = action === 'approve'
410
422
  ? await buildArtifactApproveBody(artifact, input, client, basePath)
@@ -416,7 +428,14 @@ async function runArtifactCommand(artifact, action, input, client) {
416
428
  const data = await client.request({ method: 'POST', path, body });
417
429
  return { ok: true, data };
418
430
  }
419
- throw new Error(`Usage: coauthor ${artifact} <show|generate|save|approve> <projectId>`);
431
+ throw new Error(`Usage: coauthor ${artifact} <${artifact === 'contract' ? 'show|save|approve' : 'show|generate|save|approve'}> <projectId>`);
432
+ }
433
+ function artifactSaveShape(artifact) {
434
+ if (artifact === 'contract')
435
+ return 'Send the contract fields, e.g. {"contract":{"topic":"...","target_audience":"..."}}.';
436
+ if (artifact === 'outline')
437
+ return 'Send the complete outline in order, e.g. {"sections":[...]} from `coauthor outline show`; sections you omit are removed.';
438
+ return 'Send the complete plan, e.g. {"research_tasks":[...]} from `coauthor research-plan show`.';
420
439
  }
421
440
  async function runResearchCommand(action, input, context) {
422
441
  const { client } = context;
@@ -458,12 +477,108 @@ async function runDraftCommand(action, input, context) {
458
477
  const data = await client.request({ path: format ? `${basePath}/get?format=${encodeURIComponent(format)}` : `${basePath}/get` });
459
478
  return { ok: true, data };
460
479
  }
480
+ if (action === 'revise')
481
+ return runDraftReviseCommand(projectId, input, context);
482
+ if (action === 'revision')
483
+ return runDraftRevisionCommand(input.command[2], projectId, input, context);
461
484
  if (action === 'save') {
462
- const data = await client.request({ method: 'POST', path: `${basePath}/save`, body: parseJsonOption(input.values) });
485
+ if (readJsonOptionText(input.values) === undefined) {
486
+ throw new Error(`Usage: coauthor draft save <projectId> --data @payload.json. ${DRAFT_SAVE_SHAPE}`);
487
+ }
488
+ const body = parseJsonOption(input.values);
489
+ const content = body.content;
490
+ if (!content || typeof content !== 'object' || Array.isArray(content) || content.type !== 'doc') {
491
+ throw new Error(`draft save content must be a ProseMirror document, not markdown or text. ${DRAFT_SAVE_SHAPE}`);
492
+ }
493
+ const baseVersion = body.expected_base_version ?? body.expectedBaseVersion ?? body.expected_version ?? body.expectedVersion;
494
+ if (typeof baseVersion !== 'number') {
495
+ throw new Error(`draft save needs expected_base_version: the version_number you edited. ${DRAFT_SAVE_SHAPE}`);
496
+ }
497
+ if (getBoolean(input.values, 'force'))
498
+ body.allow_recent_user_edit = true;
499
+ const data = await client.request({ method: 'POST', path: `${basePath}/save`, body });
463
500
  return { ok: true, data };
464
501
  }
465
- throw new Error('Usage: coauthor draft <generate|status|get|save> <projectId>');
502
+ throw new Error('Usage: coauthor draft <generate|status|get|save|revise|revision> <projectId>');
503
+ }
504
+ // Revise by instruction: CoAuthor's editor proposes the change, and the
505
+ // calling agent reviews the groups and applies or discards them.
506
+ async function runDraftReviseCommand(projectId, input, context) {
507
+ const instruction = getString(input.values, 'instruction') ?? input.positionals.slice(1).join(' ');
508
+ if (!instruction.trim())
509
+ throw new Error('Usage: coauthor draft revise <projectId> --instruction "..." [--wait] [--apply]');
510
+ const started = await context.client.request({
511
+ method: 'POST',
512
+ path: `projects/${encodeURIComponent(projectId)}/draft/revisions`,
513
+ body: { instruction },
514
+ });
515
+ const revisionId = getResponseString(started, 'revision_id');
516
+ if (!getBoolean(input.values, 'wait') || !revisionId) {
517
+ return { ok: true, message: revisionId ? `Revision ${revisionId} queued. Check it with: coauthor draft revision show ${projectId} ${revisionId}` : undefined, data: started };
518
+ }
519
+ const revision = await waitForRevision(context.client, projectId, revisionId);
520
+ if (!revision) {
521
+ return {
522
+ ok: false,
523
+ status: 'still_running',
524
+ exitCode: 2,
525
+ message: `Revision ${revisionId} is still running. Check again with: coauthor draft revision show ${projectId} ${revisionId} --json`,
526
+ data: started,
527
+ };
528
+ }
529
+ if (getResponseValue(revision, 'awaiting_review') !== true) {
530
+ return { ok: true, message: `Revision ${revisionId} finished as ${getResponseString(revision, 'state') ?? 'unknown'} with no changes to review.`, data: revision };
531
+ }
532
+ if (getBoolean(input.values, 'apply')) {
533
+ const applied = await applyRevision(context.client, projectId, revisionId, input);
534
+ return { ok: true, message: `Applied revision ${revisionId}.`, data: { revision, applied } };
535
+ }
536
+ return {
537
+ ok: true,
538
+ status: 'awaiting_review',
539
+ message: `Revision ${revisionId} is ready to review. Apply with: coauthor draft revision apply ${projectId} ${revisionId} (or --accept/--reject <group ids>), or discard it.`,
540
+ data: revision,
541
+ };
466
542
  }
543
+ async function runDraftRevisionCommand(action, projectId, input, context) {
544
+ const revisionId = input.positionals[1];
545
+ if (!action || !revisionId)
546
+ throw new Error('Usage: coauthor draft revision <show|apply|discard> <projectId> <revisionId>');
547
+ const path = `projects/${encodeURIComponent(projectId)}/draft/revisions/${encodeURIComponent(revisionId)}`;
548
+ if (action === 'show')
549
+ return { ok: true, data: await context.client.request({ path }) };
550
+ if (action === 'apply')
551
+ return { ok: true, message: `Applied revision ${revisionId}.`, data: await applyRevision(context.client, projectId, revisionId, input) };
552
+ if (action === 'discard')
553
+ return { ok: true, data: await context.client.request({ method: 'POST', path: `${path}/discard`, body: {} }) };
554
+ throw new Error('Usage: coauthor draft revision <show|apply|discard> <projectId> <revisionId>');
555
+ }
556
+ function applyRevision(client, projectId, revisionId, input) {
557
+ const list = (name) => getString(input.values, name)?.split(',').map((id) => id.trim()).filter(Boolean);
558
+ const accept = list('accept');
559
+ const reject = list('reject');
560
+ if (accept && reject)
561
+ throw new Error('Pass --accept or --reject, not both.');
562
+ return client.request({
563
+ method: 'POST',
564
+ path: `projects/${encodeURIComponent(projectId)}/draft/revisions/${encodeURIComponent(revisionId)}/apply`,
565
+ body: { ...(accept ? { accept } : {}), ...(reject ? { reject } : {}) },
566
+ });
567
+ }
568
+ async function waitForRevision(client, projectId, revisionId) {
569
+ // Stay under the 10-minute foreground limit of agent shells; the caller
570
+ // gets a resumable still_running result instead of being killed.
571
+ const deadline = Date.now() + waitTimeoutMs(9 * 60_000);
572
+ const pollMs = Math.min(waitPollMs(), 2000);
573
+ while (Date.now() < deadline) {
574
+ const revision = await client.request({ path: `projects/${encodeURIComponent(projectId)}/draft/revisions/${encodeURIComponent(revisionId)}` });
575
+ if (getResponseValue(revision, 'running') !== true)
576
+ return revision;
577
+ await sleep(pollMs);
578
+ }
579
+ return null;
580
+ }
581
+ 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`.';
467
582
  async function runResourceCommand(resource, action, input, client) {
468
583
  const projectId = getString(input.values, 'project') ?? input.positionals[0];
469
584
  const resourceId = getString(input.values, 'id') ?? input.positionals[1];
@@ -515,6 +630,31 @@ async function runResourceCommand(resource, action, input, client) {
515
630
  const data = await client.request({ method: 'POST', path: `${basePath}/${action}`, body });
516
631
  return { ok: true, data };
517
632
  }
633
+ if (resource === 'images' && action === 'metadata') {
634
+ if (!projectId)
635
+ throw new Error('Missing project id for image metadata');
636
+ if (!resourceId) {
637
+ throw new Error('Usage: coauthor image metadata <projectId> <placeholderId> [--alt-text <text>] [--description <text>] [--file-slug <slug>]');
638
+ }
639
+ // Server keys (alt_text/description/file_slug) are snake_case, unlike
640
+ // the camelCase withNamedOptions produces, so they are set directly.
641
+ const body = parseJsonOption(input.values);
642
+ const altText = getString(input.values, 'alt-text');
643
+ if (altText !== undefined)
644
+ body.alt_text = altText;
645
+ const description = getString(input.values, 'description');
646
+ if (description !== undefined)
647
+ body.description = description;
648
+ const fileSlug = getString(input.values, 'file-slug');
649
+ if (fileSlug !== undefined)
650
+ body.file_slug = fileSlug;
651
+ const data = await client.request({
652
+ method: 'POST',
653
+ path: `${basePath}/${encodeURIComponent(resourceId)}/metadata`,
654
+ body,
655
+ });
656
+ return { ok: true, data };
657
+ }
518
658
  if (['create', 'generate', 'save', 'edit', 'publish', 'export', 'cancel', 'retry'].includes(action)) {
519
659
  if (!projectId)
520
660
  throw new Error(`Missing project id for ${resourceCommandName(resource)} ${action}`);
@@ -784,9 +924,11 @@ async function waitForResearch(client, projectId, initialData, baseUrl) {
784
924
  const deadline = Date.now() + waitTimeoutMs(20 * 60_000);
785
925
  const pollMs = waitPollMs();
786
926
  let latest = initialData;
927
+ let liveness = null;
787
928
  while (Date.now() < deadline) {
788
929
  await sleep(pollMs);
789
930
  latest = await client.request({ path: `projects/${encodeURIComponent(projectId)}/research/status` });
931
+ liveness = observeResearchLiveness(liveness, latest);
790
932
  const status = extractNestedString(latest, ['run', 'status']);
791
933
  if (status === 'succeeded')
792
934
  return { ok: true, message: 'Research completed', data: latest };
@@ -798,7 +940,7 @@ async function waitForResearch(client, projectId, initialData, baseUrl) {
798
940
  if (status === 'paused_credits_exhausted') {
799
941
  return creditsExhaustedPauseResult(projectId, 'research', extractNestedString(latest, ['run', 'error_message']) ?? 'Research paused until included credits reset.', latest);
800
942
  }
801
- const stale = researchRunningStaleResult(projectId, latest, null, initialData);
943
+ const stale = researchRunningStaleResult(projectId, latest, null, initialData, liveness);
802
944
  if (stale)
803
945
  return stale;
804
946
  }
@@ -832,6 +974,7 @@ async function waitForWorkflowDraft(client, projectId, initialData, baseUrl, mod
832
974
  let latestResearch = null;
833
975
  let draftGenerate = null;
834
976
  let attemptedDraftStart = false;
977
+ let liveness = null;
835
978
  while (Date.now() < deadline) {
836
979
  await sleep(pollMs);
837
980
  latestDraft = await client.request({ path: `projects/${encodeURIComponent(projectId)}/draft/status` });
@@ -866,6 +1009,7 @@ async function waitForWorkflowDraft(client, projectId, initialData, baseUrl, mod
866
1009
  });
867
1010
  }
868
1011
  latestResearch = await client.request({ path: `projects/${encodeURIComponent(projectId)}/research/status` });
1012
+ liveness = observeResearchLiveness(liveness, latestResearch);
869
1013
  const researchStatus = extractNestedString(latestResearch, ['run', 'status']);
870
1014
  if (researchStatus === 'failed') {
871
1015
  throw new Error(extractNestedString(latestResearch, ['run', 'error_message']) ?? 'Research failed');
@@ -884,11 +1028,14 @@ async function waitForWorkflowDraft(client, projectId, initialData, baseUrl, mod
884
1028
  draft_status: latestDraft,
885
1029
  });
886
1030
  }
887
- const stale = researchRunningStaleResult(projectId, latestResearch, latestDraft, initialData);
1031
+ const stale = researchRunningStaleResult(projectId, latestResearch, latestDraft, initialData, liveness);
888
1032
  if (stale)
889
1033
  return stale;
1034
+ // Only start the draft once the project reaches research_structured. The
1035
+ // research run is marked succeeded before structuring finishes, and a draft
1036
+ // request in that window is rejected with state "research_complete".
890
1037
  if (!attemptedDraftStart
891
- && (researchStatus === 'succeeded' || isResearchReadyForDraft(draftState))
1038
+ && isResearchReadyForDraft(draftState)
892
1039
  && draftPhase !== 'queued'
893
1040
  && draftPhase !== 'running') {
894
1041
  attemptedDraftStart = true;
@@ -915,9 +1062,30 @@ function waitTimeoutMs(defaultMs) {
915
1062
  const raw = Number(process.env.COAUTHOR_CLI_WAIT_TIMEOUT_MS);
916
1063
  return Number.isFinite(raw) && raw > 0 ? raw : defaultMs;
917
1064
  }
1065
+ // While waiting, research is stale only when its progress (sections done, run
1066
+ // status, project state) stops changing for this long. A long deep-research
1067
+ // section can legitimately run for well over ten minutes.
918
1068
  function researchStaleMs() {
919
1069
  const raw = Number(process.env.COAUTHOR_CLI_RESEARCH_STALE_MS);
920
- return Number.isFinite(raw) && raw > 0 ? raw : 10 * 60_000;
1070
+ return Number.isFinite(raw) && raw > 0 ? raw : 30 * 60_000;
1071
+ }
1072
+ // A one-off `research status` has no progress history, so it can only judge by
1073
+ // the run's age.
1074
+ function researchStatusStaleMs() {
1075
+ const raw = Number(process.env.COAUTHOR_CLI_RESEARCH_STALE_MS);
1076
+ return Number.isFinite(raw) && raw > 0 ? raw : 60 * 60_000;
1077
+ }
1078
+ function observeResearchLiveness(previous, data) {
1079
+ const signature = JSON.stringify([
1080
+ extractNestedString(data, ['run', 'id']) ?? null,
1081
+ extractNestedString(data, ['run', 'status']) ?? null,
1082
+ getResponseString(data, 'project_state') ?? null,
1083
+ extractNestedValue(data, ['run', 'progress', 'completed_sections']) ?? null,
1084
+ extractNestedValue(data, ['run', 'progress', 'in_progress_section_ids']) ?? null,
1085
+ ]);
1086
+ if (previous && previous.signature === signature)
1087
+ return previous;
1088
+ return { signature, changedAt: Date.now() };
921
1089
  }
922
1090
  function researchRunAgeMs(data) {
923
1091
  const timestamp = extractNestedString(data, ['run', 'updated_at'])
@@ -929,22 +1097,24 @@ function researchRunAgeMs(data) {
929
1097
  return null;
930
1098
  return Date.now() - time;
931
1099
  }
932
- function isResearchRunningStale(data) {
1100
+ function isResearchRunningStale(data, liveness = null) {
933
1101
  if (extractNestedString(data, ['run', 'status']) !== 'running')
934
1102
  return false;
935
1103
  if (getResponseString(data, 'project_state') !== 'research_running')
936
1104
  return false;
1105
+ if (liveness)
1106
+ return Date.now() - liveness.changedAt >= researchStaleMs();
937
1107
  const ageMs = researchRunAgeMs(data);
938
- return typeof ageMs === 'number' && ageMs >= researchStaleMs();
1108
+ return typeof ageMs === 'number' && ageMs >= researchStatusStaleMs();
939
1109
  }
940
- function researchRunningStaleResult(projectId, researchStatus, draftStatus, workflow) {
941
- if (!isResearchRunningStale(researchStatus))
1110
+ function researchRunningStaleResult(projectId, researchStatus, draftStatus, workflow, liveness) {
1111
+ if (!isResearchRunningStale(researchStatus, liveness))
942
1112
  return null;
943
1113
  return {
944
1114
  ok: false,
945
1115
  status: 'research_running_stale',
946
1116
  exitCode: 2,
947
- message: 'Research is still marked running and has not reported a terminal state within the expected window.',
1117
+ message: `Research is still marked running and its progress has not changed for ${Math.round(researchStaleMs() / 60_000)} minutes.`,
948
1118
  data: {
949
1119
  workflow,
950
1120
  research_status: enrichResearchStatus(researchStatus),
@@ -1031,7 +1201,7 @@ function enrichResearchStatus(data) {
1031
1201
  ...data,
1032
1202
  diagnostic: {
1033
1203
  code: 'research_running_stale',
1034
- message: 'Research is still marked running and has not reported a terminal state within the expected window. Inspect structured output before deciding whether to rewind.',
1204
+ message: `Research has been running for over ${Math.round(researchStatusStaleMs() / 60_000)} minutes. Check status again a few minutes apart; rewind only if run.progress has stopped changing, because rewinding discards the research already done.`,
1035
1205
  next_commands: [
1036
1206
  'coauthor research status <project-id> --json',
1037
1207
  'coauthor research structured <project-id> --json',
@@ -1155,7 +1325,7 @@ function isAlreadyStartedOrComplete(error) {
1155
1325
  if (!(error instanceof AgentHttpError))
1156
1326
  return false;
1157
1327
  const message = extractErrorMessage(error);
1158
- return /already|state "draft_generated"|state "editing"|state "draft_running"|draft.*running/i.test(message);
1328
+ return /already|state "draft_generated"|state "editing"/i.test(message);
1159
1329
  }
1160
1330
  function extractErrorMessage(error) {
1161
1331
  const body = error.responseBody;
@@ -1189,6 +1359,9 @@ export function helpResult(command = []) {
1189
1359
  message: scoped ?? [
1190
1360
  'Usage: coauthor <command> [options]',
1191
1361
  '',
1362
+ 'Global options: --json, --help, --version, --base-url <url>, --token <token>',
1363
+ 'JSON options (--data, --contract) also accept @file.json, or @- to read stdin.',
1364
+ '',
1192
1365
  'Commands:',
1193
1366
  ' auth login|status|logout (logout supports --local-only)',
1194
1367
  ' project create|list|show',
@@ -1198,15 +1371,16 @@ export function helpResult(command = []) {
1198
1371
  ' outline show|generate|save|approve',
1199
1372
  ' research-plan show|generate|save|approve',
1200
1373
  ' research run|status|structured',
1201
- ' draft generate|status|get|save',
1374
+ ' draft generate|status|get|save|revise',
1375
+ ' draft revision show|apply|discard',
1202
1376
  ' draft get supports --format json|markdown|html|text',
1203
1377
  ' workflow show|status|advance|run|rewind|approve|resume',
1204
1378
  ' workflow run/advance supports --briefing-mode auto|strict|off and --require-brief-review',
1205
- ' image list|status|show|generate|edit',
1379
+ ' image list|status|show|generate|edit|metadata',
1206
1380
  ' thread list|show|create|generate|save',
1207
1381
  ' slideshow show|save',
1208
1382
  ' publish thread',
1209
- ' export blog|clickminded|wordpress',
1383
+ ' export list|blog|clickminded|wordpress',
1210
1384
  ' operation list|show|status',
1211
1385
  ' credits',
1212
1386
  ' share <project-id>',
@@ -1262,14 +1436,44 @@ function commandHelp(command) {
1262
1436
  'Retrieves a saved generated draft. Chat responses are available through coauthor chat show.',
1263
1437
  ].join('\n'),
1264
1438
  'draft save': [
1265
- 'Usage: coauthor draft save <project-id> --data \'<json>\' [--json]',
1439
+ 'Usage: coauthor draft save <project-id> --data @payload.json [--force] [--json]',
1440
+ '',
1441
+ 'Replaces the draft with an edited ProseMirror document. Markdown is not accepted.',
1442
+ 'Fails with 409 if the draft changed since you read it (re-read and reapply), or if the user edited it in the browser in the last 90 seconds (--force overrides).',
1443
+ DRAFT_SAVE_SHAPE,
1444
+ ].join('\n'),
1445
+ 'draft revise': [
1446
+ 'Usage: coauthor draft revise <project-id> --instruction "..." [--wait] [--apply] [--accept <ids> | --reject <ids>] [--json]',
1266
1447
  '',
1267
- 'Saves a draft document payload through the agent API.',
1448
+ "CoAuthor's editor rewrites the draft from your instruction. With --wait the command returns the proposed changes as groups (before/after markdown) for you to review.",
1449
+ 'Then: coauthor draft revision apply <project-id> <revision-id> [--accept g1,g2 | --reject g3], or coauthor draft revision discard <project-id> <revision-id>.',
1450
+ '--apply applies every group as soon as the revision is ready. Only one revision can be open on a draft at a time.',
1451
+ ].join('\n'),
1452
+ 'draft revision': [
1453
+ 'Usage: coauthor draft revision <show|apply|discard> <project-id> <revision-id> [--accept <ids> | --reject <ids>] [--json]',
1454
+ '',
1455
+ '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).',
1268
1456
  ].join('\n'),
1269
1457
  'image generate': [
1270
- 'Usage: coauthor image generate <project-id> --placeholder-id <placeholder-id> [--prompt "..."] [--json]',
1458
+ 'Usage: coauthor image generate <project-id> --placeholder-id <id> [--grounding-mode <mode>] [--image-generation-model <id>] [--json]',
1459
+ '',
1460
+ 'Pass the placeholder `id` from coauthor image list. Draft generation creates placeholders.',
1461
+ 'Generation is asynchronous: poll coauthor image status <project-id> --json until it is done.',
1462
+ ].join('\n'),
1463
+ 'image edit': [
1464
+ 'Usage: coauthor image edit <project-id> --placeholder-id <id> --edit-prompt "..." [--json]',
1465
+ '',
1466
+ 'Edits the current image for a placeholder. Poll coauthor image status <project-id> --json for the result.',
1467
+ ].join('\n'),
1468
+ 'contract save': [
1469
+ 'Usage: coauthor contract save <project-id> --data @contract.json [--json]',
1470
+ '',
1471
+ 'Send the contract fields, e.g. {"contract":{"topic":"...","target_audience":"..."}}.',
1472
+ ].join('\n'),
1473
+ 'outline save': [
1474
+ 'Usage: coauthor outline save <project-id> --data @outline.json [--json]',
1271
1475
  '',
1272
- 'Image generation requires an image placeholder from coauthor image list. Draft generation creates placeholders.',
1476
+ 'Send the complete outline in order as {"sections":[...]}. Sections you omit are removed.',
1273
1477
  ].join('\n'),
1274
1478
  'thread generate': [
1275
1479
  'Usage: coauthor thread generate <project-id> [--writing-model <id>] [--json]',
@@ -1277,5 +1481,5 @@ function commandHelp(command) {
1277
1481
  'Generates a social thread from the saved draft.',
1278
1482
  ].join('\n'),
1279
1483
  };
1280
- return help[key] ?? null;
1484
+ return help[key] ?? help[command.slice(0, 2).join(' ')] ?? null;
1281
1485
  }
package/dist/index.js CHANGED
@@ -1,5 +1,5 @@
1
1
  #!/usr/bin/env node
2
- import { realpathSync } from 'node:fs';
2
+ import { readFileSync, realpathSync } from 'node:fs';
3
3
  import { fileURLToPath } from 'node:url';
4
4
  import { AgentHttpError, AgentClient, normalizeBaseUrl } from './client.js';
5
5
  import { DEFAULT_BASE_URL, resolveRuntimeConfig } from './config.js';
@@ -10,6 +10,10 @@ export async function main(argv = process.argv.slice(2)) {
10
10
  let resolvedBaseUrl = resolveBaseUrlFromArgv(argv);
11
11
  try {
12
12
  const parsed = parseCliArgs(argv);
13
+ 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`);
15
+ return 0;
16
+ }
13
17
  if (parsed.globals.help) {
14
18
  process.stdout.write(renderResult(helpResult(parsed.command), parsed.globals.json));
15
19
  return 0;
@@ -43,11 +47,31 @@ function formatCliError(error, baseUrl, argv = []) {
43
47
  const requiresKey = formatRequiresKeyResult(error.responseBody, baseUrl);
44
48
  if (requiresKey)
45
49
  return { error: new Error(requiresKey.message), result: requiresKey, exitCode: 2 };
46
- const message = extractErrorMessage(error.responseBody) ?? error.message;
50
+ const serverMessage = extractErrorMessage(error.responseBody) ?? error.message;
51
+ const message = error.status === 401
52
+ ? `${serverMessage}\nSign in with \`coauthor auth login\` (or set COAUTHOR_TOKEN).`
53
+ : serverMessage;
47
54
  const researchBlock = formatResearchDraftBlock(message, argv);
48
55
  if (researchBlock)
49
56
  return { error: new Error(researchBlock.message), result: researchBlock, exitCode: 2 };
50
- return { error: new Error(message), exitCode: 1 };
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);
60
+ 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;
64
+ return {
65
+ error: new Error(humanMessage),
66
+ result: {
67
+ ok: false,
68
+ error: humanMessage,
69
+ ...(envelope?.code ? { code: envelope.code } : {}),
70
+ http_status: error.status,
71
+ ...(envelope?.details !== undefined ? { details: envelope.details } : {}),
72
+ },
73
+ exitCode: 1,
74
+ };
51
75
  }
52
76
  return { error: error instanceof Error ? error : new Error(String(error)), exitCode: 1 };
53
77
  }
@@ -211,6 +235,23 @@ function extractEnvelopeError(body) {
211
235
  details: error.details,
212
236
  };
213
237
  }
238
+ function cliVersion() {
239
+ try {
240
+ const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
241
+ return typeof pkg.version === 'string' ? pkg.version : 'unknown';
242
+ }
243
+ catch {
244
+ return 'unknown';
245
+ }
246
+ }
247
+ function currentDraftDetails(details) {
248
+ if (!details || typeof details !== 'object' || Array.isArray(details))
249
+ return null;
250
+ const current = details.current;
251
+ if (!current || typeof current !== 'object' || Array.isArray(current))
252
+ return null;
253
+ return current;
254
+ }
214
255
  function resolveBaseUrlFromArgv(argv) {
215
256
  const index = argv.indexOf('--base-url');
216
257
  const value = index >= 0 ? argv[index + 1] : undefined;
package/dist/parser.d.ts CHANGED
@@ -3,6 +3,7 @@ import type { JsonValue } from './client.js';
3
3
  export type GlobalOptions = {
4
4
  json: boolean;
5
5
  help: boolean;
6
+ version: boolean;
6
7
  baseUrl?: string;
7
8
  token?: string;
8
9
  };
@@ -18,6 +19,7 @@ export declare const commandInputSchema: z.ZodObject<{
18
19
  globals: z.ZodObject<{
19
20
  json: z.ZodBoolean;
20
21
  help: z.ZodBoolean;
22
+ version: z.ZodBoolean;
21
23
  baseUrl: z.ZodOptional<z.ZodString>;
22
24
  token: z.ZodOptional<z.ZodString>;
23
25
  }, z.core.$strip>;
@@ -27,4 +29,5 @@ export declare function parseCliArgs(argv: string[]): ParsedCommand;
27
29
  export declare function getString(values: ParsedCommand['values'], name: string): string | undefined;
28
30
  export declare function requireString(values: ParsedCommand['values'], name: string): string;
29
31
  export declare function getBoolean(values: ParsedCommand['values'], name: string): boolean;
32
+ export declare function readJsonOptionText(values: ParsedCommand['values'], name?: string): string | undefined;
30
33
  export declare function parseJsonOption(values: ParsedCommand['values'], name?: string): Record<string, JsonValue>;
package/dist/parser.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { readFileSync } from 'node:fs';
1
2
  import { parseArgs } from 'node:util';
2
3
  import { z } from 'zod';
3
4
  export const commandInputSchema = z.object({
@@ -6,61 +7,76 @@ export const commandInputSchema = z.object({
6
7
  globals: z.object({
7
8
  json: z.boolean(),
8
9
  help: z.boolean(),
10
+ version: z.boolean(),
9
11
  baseUrl: z.string().url().optional(),
10
12
  token: z.string().min(1).optional(),
11
13
  }),
12
14
  values: z.record(z.string(), z.union([z.string(), z.boolean(), z.array(z.string())]).optional()),
13
15
  });
16
+ // Every flag any command reads must be declared here. Parsing is strict: an
17
+ // undeclared flag used to parse as `true` and push its value into the
18
+ // positionals, silently dropping it (and sometimes misreading it as an id).
19
+ const OPTIONS = {
20
+ json: { type: 'boolean', default: false },
21
+ help: { type: 'boolean', short: 'h', default: false },
22
+ version: { type: 'boolean', short: 'v', default: false },
23
+ 'base-url': { type: 'string' },
24
+ token: { type: 'string' },
25
+ 'with-publish': { type: 'boolean', default: false },
26
+ 'no-browser': { type: 'boolean', default: false },
27
+ 'local-only': { type: 'boolean', default: false },
28
+ yes: { type: 'boolean', default: false },
29
+ wait: { type: 'boolean', default: false },
30
+ force: { type: 'boolean', default: false },
31
+ 'dry-run': { type: 'boolean', default: false },
32
+ data: { type: 'string' },
33
+ cwd: { type: 'string' },
34
+ title: { type: 'string' },
35
+ topic: { type: 'string' },
36
+ audience: { type: 'string' },
37
+ contract: { type: 'string' },
38
+ project: { type: 'string' },
39
+ id: { type: 'string' },
40
+ 'placeholder-id': { type: 'string' },
41
+ message: { type: 'string' },
42
+ stage: { type: 'string' },
43
+ target: { type: 'string' },
44
+ reason: { type: 'string' },
45
+ 'briefing-mode': { type: 'string' },
46
+ 'require-brief-review': { type: 'boolean', default: false },
47
+ 'max-brief-questions': { type: 'string' },
48
+ prompt: { type: 'string' },
49
+ format: { type: 'string' },
50
+ thread: { type: 'string' },
51
+ image: { type: 'string' },
52
+ slug: { type: 'string' },
53
+ permalink: { type: 'string' },
54
+ 'connection-id': { type: 'string' },
55
+ status: { type: 'string' },
56
+ limit: { type: 'string' },
57
+ cursor: { type: 'string' },
58
+ 'execution-token': { type: 'string' },
59
+ 'planning-model': { type: 'string' },
60
+ 'writing-model': { type: 'string' },
61
+ 'alt-text': { type: 'string' },
62
+ description: { type: 'string' },
63
+ 'file-slug': { type: 'string' },
64
+ 'edit-prompt': { type: 'string' },
65
+ 'grounding-mode': { type: 'string' },
66
+ 'image-generation-model': { type: 'string' },
67
+ instruction: { type: 'string' },
68
+ apply: { type: 'boolean', default: false },
69
+ accept: { type: 'string' },
70
+ reject: { type: 'string' },
71
+ };
14
72
  export function parseCliArgs(argv) {
15
- const parsed = parseArgs({
16
- args: argv,
17
- allowPositionals: true,
18
- strict: false,
19
- options: {
20
- json: { type: 'boolean', default: false },
21
- help: { type: 'boolean', short: 'h', default: false },
22
- 'base-url': { type: 'string' },
23
- token: { type: 'string' },
24
- email: { type: 'string' },
25
- password: { type: 'string' },
26
- 'with-publish': { type: 'boolean', default: false },
27
- 'no-browser': { type: 'boolean', default: false },
28
- 'local-only': { type: 'boolean', default: false },
29
- yes: { type: 'boolean', default: false },
30
- wait: { type: 'boolean', default: false },
31
- force: { type: 'boolean', default: false },
32
- 'dry-run': { type: 'boolean', default: false },
33
- data: { type: 'string' },
34
- cwd: { type: 'string' },
35
- title: { type: 'string' },
36
- topic: { type: 'string' },
37
- audience: { type: 'string' },
38
- contract: { type: 'string' },
39
- project: { type: 'string' },
40
- id: { type: 'string' },
41
- 'placeholder-id': { type: 'string' },
42
- message: { type: 'string' },
43
- stage: { type: 'string' },
44
- target: { type: 'string' },
45
- reason: { type: 'string' },
46
- 'briefing-mode': { type: 'string' },
47
- 'require-brief-review': { type: 'boolean', default: false },
48
- 'max-brief-questions': { type: 'string' },
49
- prompt: { type: 'string' },
50
- format: { type: 'string' },
51
- thread: { type: 'string' },
52
- image: { type: 'string' },
53
- slug: { type: 'string' },
54
- permalink: { type: 'string' },
55
- 'connection-id': { type: 'string' },
56
- status: { type: 'string' },
57
- limit: { type: 'string' },
58
- cursor: { type: 'string' },
59
- 'execution-token': { type: 'string' },
60
- 'planning-model': { type: 'string' },
61
- 'writing-model': { type: 'string' },
62
- },
63
- });
73
+ let parsed;
74
+ try {
75
+ parsed = parseArgs({ args: argv, allowPositionals: true, strict: true, options: OPTIONS });
76
+ }
77
+ catch (error) {
78
+ throw new Error(formatParseError(error, argv));
79
+ }
64
80
  const positionals = parsed.positionals;
65
81
  const command = positionals.slice(0, commandLength(positionals));
66
82
  return commandInputSchema.parse({
@@ -69,6 +85,7 @@ export function parseCliArgs(argv) {
69
85
  globals: {
70
86
  json: Boolean(parsed.values.json),
71
87
  help: Boolean(parsed.values.help),
88
+ version: Boolean(parsed.values.version),
72
89
  baseUrl: stringValue(parsed.values['base-url']),
73
90
  token: stringValue(parsed.values.token),
74
91
  },
@@ -87,11 +104,28 @@ export function requireString(values, name) {
87
104
  export function getBoolean(values, name) {
88
105
  return values[name] === true;
89
106
  }
90
- export function parseJsonOption(values, name = 'data') {
107
+ // `--data @payload.json` reads a file and `--data @-` reads stdin, so large
108
+ // payloads (draft documents, contracts) never go through shell quoting.
109
+ export function readJsonOptionText(values, name = 'data') {
91
110
  const raw = getString(values, name);
111
+ if (raw === undefined || !raw.startsWith('@'))
112
+ return raw;
113
+ const source = raw.slice(1);
114
+ if (!source)
115
+ throw new Error(`--${name} @<file> needs a file path (or @- for stdin)`);
116
+ return readFileSync(source === '-' ? 0 : source, 'utf8');
117
+ }
118
+ export function parseJsonOption(values, name = 'data') {
119
+ const raw = readJsonOptionText(values, name);
92
120
  if (!raw)
93
121
  return {};
94
- const parsed = JSON.parse(raw);
122
+ let parsed;
123
+ try {
124
+ parsed = JSON.parse(raw);
125
+ }
126
+ catch (error) {
127
+ throw new Error(`--${name} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
128
+ }
95
129
  return z.record(z.string(), z.unknown()).transform((value) => value).parse(parsed);
96
130
  }
97
131
  function commandLength(positionals) {
@@ -115,12 +149,25 @@ function commandLength(positionals) {
115
149
  : 1;
116
150
  if (first === 'workflow')
117
151
  return second ? 2 : 1;
152
+ if (first === 'draft' && second === 'revision')
153
+ return positionals[2] && ['show', 'apply', 'discard'].includes(positionals[2]) ? 3 : 2;
118
154
  if (first === 'credits')
119
155
  return 1;
120
156
  if (['contract', 'outline', 'research-plan', 'research', 'draft', 'image', 'thread', 'slideshow', 'publish', 'export', 'operation'].includes(first ?? ''))
121
157
  return second ? 2 : 1;
122
158
  return 1;
123
159
  }
160
+ function formatParseError(error, argv) {
161
+ const message = error instanceof Error ? error.message : String(error);
162
+ const code = error?.code;
163
+ const command = argv.filter((arg) => !arg.startsWith('-')).slice(0, 2).join(' ');
164
+ const help = command ? `coauthor ${command} --help` : 'coauthor --help';
165
+ if (code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION') {
166
+ const option = /'(--?[^']+)'/.exec(message)?.[1] ?? 'option';
167
+ return `Unknown option ${option}. Run \`${help}\` for supported options.`;
168
+ }
169
+ return `${message.split('\n')[0]} Run \`${help}\` for usage.`;
170
+ }
124
171
  function stringValue(value) {
125
172
  if (typeof value === 'string')
126
173
  return value;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.19",
3
+ "version": "0.0.21",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -253,6 +253,14 @@ Use `coauthor chat show <project-id> --json` to retrieve the workspace chat tran
253
253
 
254
254
  When using `coauthor chat <project-id> --stage draft --json`, treat the returned text as a workspace chat response, not a saved draft document. The CLI returns `draft_saved: false` and `transcript_command` when applicable. Use `coauthor draft get <project-id> --format markdown --json` only for a saved generated draft.
255
255
 
256
+ ## Editing a Draft
257
+
258
+ Two ways to change a generated draft. Both work whichever editor the user has opened the draft in.
259
+
260
+ - **Revise by instruction (prose changes):** `coauthor draft revise <project-id> --instruction "Make the intro two sentences" --wait --json`. CoAuthor's own editor rewrites the draft in the project's voice and returns `data.groups`, each with `before_markdown` and `after_markdown`. Review every group against the brief before applying: `coauthor draft revision apply <project-id> <revision-id> --json`, keep only some with `--accept g1,g2` or `--reject g3`, or drop it with `coauthor draft revision discard <project-id> <revision-id> --json`. Only one revision can be open on a draft; an unresolved one blocks the user's browser saves, so always apply or discard it. If `--wait` returns `still_running`, run `coauthor draft revision show <project-id> <revision-id> --json` again. `revise_unavailable` means this account cannot revise by instruction yet; use a direct edit.
261
+ - **Direct edit (exact text you already have):** `coauthor draft get <project-id> --format json --json`, edit nodes inside `data.content` (keep node ids and `imagePlaceholder` nodes), write `{"document_id": ..., "expected_base_version": <data.version_number>, "expected_content_hash": <data.content_hash, if present>, "content": <edited doc>}` to a file, then `coauthor draft save <project-id> --data @payload.json --json`. Never send markdown as `content`.
262
+ - On `stale_draft`, re-read with `draft get` and reapply your edit; never retry the same payload. On `user_recently_editing`, the user is typing in the browser: wait or ask them, and pass `--force` only if they agree.
263
+
256
264
  ## Draft Export
257
265
 
258
266
  Use `coauthor draft get <project-id> --format markdown --json` when the user needs a finished draft in Markdown. Generated images are resolved into Markdown image URLs when available.
@@ -253,6 +253,14 @@ Use `coauthor chat show <project-id> --json` to retrieve the workspace chat tran
253
253
 
254
254
  When using `coauthor chat <project-id> --stage draft --json`, treat the returned text as a workspace chat response, not a saved draft document. The CLI returns `draft_saved: false` and `transcript_command` when applicable. Use `coauthor draft get <project-id> --format markdown --json` only for a saved generated draft.
255
255
 
256
+ ## Editing a Draft
257
+
258
+ Two ways to change a generated draft. Both work whichever editor the user has opened the draft in.
259
+
260
+ - **Revise by instruction (prose changes):** `coauthor draft revise <project-id> --instruction "Make the intro two sentences" --wait --json`. CoAuthor's own editor rewrites the draft in the project's voice and returns `data.groups`, each with `before_markdown` and `after_markdown`. Review every group against the brief before applying: `coauthor draft revision apply <project-id> <revision-id> --json`, keep only some with `--accept g1,g2` or `--reject g3`, or drop it with `coauthor draft revision discard <project-id> <revision-id> --json`. Only one revision can be open on a draft; an unresolved one blocks the user's browser saves, so always apply or discard it. If `--wait` returns `still_running`, run `coauthor draft revision show <project-id> <revision-id> --json` again. `revise_unavailable` means this account cannot revise by instruction yet; use a direct edit.
261
+ - **Direct edit (exact text you already have):** `coauthor draft get <project-id> --format json --json`, edit nodes inside `data.content` (keep node ids and `imagePlaceholder` nodes), write `{"document_id": ..., "expected_base_version": <data.version_number>, "expected_content_hash": <data.content_hash, if present>, "content": <edited doc>}` to a file, then `coauthor draft save <project-id> --data @payload.json --json`. Never send markdown as `content`.
262
+ - On `stale_draft`, re-read with `draft get` and reapply your edit; never retry the same payload. On `user_recently_editing`, the user is typing in the browser: wait or ask them, and pass `--force` only if they agree.
263
+
256
264
  ## Draft Export
257
265
 
258
266
  Use `coauthor draft get <project-id> --format markdown --json` when the user needs a finished draft in Markdown. Generated images are resolved into Markdown image URLs when available.
@@ -253,6 +253,14 @@ Use `coauthor chat show <project-id> --json` to retrieve the workspace chat tran
253
253
 
254
254
  When using `coauthor chat <project-id> --stage draft --json`, treat the returned text as a workspace chat response, not a saved draft document. The CLI returns `draft_saved: false` and `transcript_command` when applicable. Use `coauthor draft get <project-id> --format markdown --json` only for a saved generated draft.
255
255
 
256
+ ## Editing a Draft
257
+
258
+ Two ways to change a generated draft. Both work whichever editor the user has opened the draft in.
259
+
260
+ - **Revise by instruction (prose changes):** `coauthor draft revise <project-id> --instruction "Make the intro two sentences" --wait --json`. CoAuthor's own editor rewrites the draft in the project's voice and returns `data.groups`, each with `before_markdown` and `after_markdown`. Review every group against the brief before applying: `coauthor draft revision apply <project-id> <revision-id> --json`, keep only some with `--accept g1,g2` or `--reject g3`, or drop it with `coauthor draft revision discard <project-id> <revision-id> --json`. Only one revision can be open on a draft; an unresolved one blocks the user's browser saves, so always apply or discard it. If `--wait` returns `still_running`, run `coauthor draft revision show <project-id> <revision-id> --json` again. `revise_unavailable` means this account cannot revise by instruction yet; use a direct edit.
261
+ - **Direct edit (exact text you already have):** `coauthor draft get <project-id> --format json --json`, edit nodes inside `data.content` (keep node ids and `imagePlaceholder` nodes), write `{"document_id": ..., "expected_base_version": <data.version_number>, "expected_content_hash": <data.content_hash, if present>, "content": <edited doc>}` to a file, then `coauthor draft save <project-id> --data @payload.json --json`. Never send markdown as `content`.
262
+ - On `stale_draft`, re-read with `draft get` and reapply your edit; never retry the same payload. On `user_recently_editing`, the user is typing in the browser: wait or ask them, and pass `--force` only if they agree.
263
+
256
264
  ## Draft Export
257
265
 
258
266
  Use `coauthor draft get <project-id> --format markdown --json` when the user needs a finished draft in Markdown. Generated images are resolved into Markdown image URLs when available.
@@ -230,6 +230,14 @@ Persuasive opinion essay:
230
230
  - Require explicit user intent before live publish/export.
231
231
  - Use `--yes` only after the user has clearly approved the live publish/export action.
232
232
 
233
+ ## Editing a Draft
234
+
235
+ Two ways to change a generated draft. Both work whichever editor the user has opened the draft in.
236
+
237
+ - **Revise by instruction (prose changes):** `coauthor draft revise <project-id> --instruction "Make the intro two sentences" --wait --json`. CoAuthor's own editor rewrites the draft in the project's voice and returns `data.groups`, each with `before_markdown` and `after_markdown`. Review every group against the brief before applying: `coauthor draft revision apply <project-id> <revision-id> --json`, keep only some with `--accept g1,g2` or `--reject g3`, or drop it with `coauthor draft revision discard <project-id> <revision-id> --json`. Only one revision can be open on a draft; an unresolved one blocks the user's browser saves, so always apply or discard it. If `--wait` returns `still_running`, run `coauthor draft revision show <project-id> <revision-id> --json` again. `revise_unavailable` means this account cannot revise by instruction yet; use a direct edit.
238
+ - **Direct edit (exact text you already have):** `coauthor draft get <project-id> --format json --json`, edit nodes inside `data.content` (keep node ids and `imagePlaceholder` nodes), write `{"document_id": ..., "expected_base_version": <data.version_number>, "expected_content_hash": <data.content_hash, if present>, "content": <edited doc>}` to a file, then `coauthor draft save <project-id> --data @payload.json --json`. Never send markdown as `content`.
239
+ - On `stale_draft`, re-read with `draft get` and reapply your edit; never retry the same payload. On `user_recently_editing`, the user is typing in the browser: wait or ask them, and pass `--force` only if they agree.
240
+
233
241
  ## Draft Export
234
242
 
235
243
  - Use `coauthor chat show <project-id> --json` to retrieve workspace chat transcripts after long chat responses.