@clickminded/coauthor-cli 0.0.79 → 0.0.81

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
@@ -430,10 +430,29 @@ async function runWorkflowCommand(action, input, context) {
430
430
  return getBoolean(input.values, 'wait') ? waitForWorkflowDraft(client, projectId, data, context.baseUrl, modelOverrides) : { ok: true, data };
431
431
  }
432
432
  const draftStatus = await client.request({ path: `projects/${encodeURIComponent(projectId)}/draft/status` });
433
+ // A draft that already finished (e.g. after `workflow run --wait` timed out while it kept going) is reported
434
+ // as done. Dispatching again only returned the worker's dedupe ("draft_running", already_running: true).
435
+ if (isDraftComplete(draftStatus)) {
436
+ return {
437
+ ok: true,
438
+ status: 'draft_generated',
439
+ message: draftCompletionMessage('Draft already complete; nothing was started', draftStatus),
440
+ data: { status: 'draft_generated', draft_status: draftStatus },
441
+ };
442
+ }
433
443
  if (['paused_requires_key', 'paused_credits_exhausted'].includes(getResponseString(draftStatus, 'phase') ?? '')) {
434
444
  const data = await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/draft/generate`, body: modelOverrides });
435
445
  return getBoolean(input.values, 'wait') ? waitForDraft(client, projectId, data, context.baseUrl) : { ok: true, data };
436
446
  }
447
+ // Research still running or being structured: attach and wait instead of starting anything (item 46).
448
+ const researchRun = extractNestedString(researchStatus, ['run', 'status']);
449
+ const researchState = getResponseString(researchStatus, 'project_state') ?? getResponseString(draftStatus, 'project_state');
450
+ if (researchRun === 'running' || researchState === 'research_running' || researchState === 'research_complete') {
451
+ const attached = { target: 'draft', status: 'research_running', attached: true };
452
+ return getBoolean(input.values, 'wait')
453
+ ? waitForWorkflowDraft(client, projectId, attached, context.baseUrl, modelOverrides)
454
+ : { ok: true, status: 'research_running', message: `Research is still running or being structured; nothing was restarted. Wait with: coauthor workflow resume ${projectId} --target draft --wait --json`, data: { ...attached, research_status: researchStatus } };
455
+ }
437
456
  const data = await client.request({ method: 'POST', path: `${projectPath}/run`, body: { target, ...modelOverrides } });
438
457
  return getBoolean(input.values, 'wait') ? waitForWorkflowDraft(client, projectId, data, context.baseUrl, modelOverrides) : { ok: true, data };
439
458
  }
@@ -593,7 +612,15 @@ async function runArtifactCommand(artifact, action, input, client) {
593
612
  ]);
594
613
  const path = action === 'save' ? basePath : `${basePath}/${action}`;
595
614
  const data = await client.request({ method: 'POST', path, body });
596
- return { ok: true, data };
615
+ // These calls finish before they return (no --wait needed). Say what state the artifact is in: a bare
616
+ // payload read as `state: None` to agents (dogfood Nov 2026, item 56).
617
+ const status = action === 'approve' ? 'approved' : action === 'generate' ? 'generated' : 'saved';
618
+ const sections = getResponseValue(data, 'sections');
619
+ const tasks = getResponseValue(data, 'research_tasks');
620
+ const count = Array.isArray(sections) ? ` (${sections.length} sections)` : Array.isArray(tasks) ? ` (${tasks.length} research tasks)` : '';
621
+ const name = artifact === 'research-plan' ? 'Research plan' : artifact === 'outline' ? 'Outline' : 'Contract';
622
+ const next = action === 'approve' ? '' : artifact === 'contract' ? '' : ` Not approved yet: coauthor ${artifact} approve <project-id>.`;
623
+ return { ok: true, status, message: `${name} ${status}${count}.${next}`, data };
597
624
  }
598
625
  throw new Error(`Usage: coauthor ${artifact} <${artifact === 'contract' ? 'show|save|approve' : 'show|generate|save|approve'}> <projectId>`);
599
626
  }
@@ -1142,6 +1169,8 @@ async function imageOperationRequest(client, input, projectId, path, body, actio
1142
1169
  data,
1143
1170
  };
1144
1171
  }
1172
+ if (getBoolean(input.values, 'wait'))
1173
+ return waitForImageOperation(client, idempotencyKey, action, data);
1145
1174
  return {
1146
1175
  ok: true,
1147
1176
  message: `Image ${action === 'edit' ? 'edit' : 'generation'} queued. ${lookup} Or poll coauthor image status ${projectId} --json.`,
@@ -1149,6 +1178,39 @@ async function imageOperationRequest(client, input, projectId, path, body, actio
1149
1178
  data,
1150
1179
  };
1151
1180
  }
1181
+ const IMAGE_OPERATION_DONE = new Set(['succeeded', 'failed', 'unknown']);
1182
+ /** `image generate|edit --wait`: follows the recorded operation until the image is finished or failed (up to 9 minutes). */
1183
+ async function waitForImageOperation(client, idempotencyKey, action, queued) {
1184
+ const deadline = Date.now() + waitTimeoutMs(9 * 60_000);
1185
+ const pollMs = Math.max(waitPollMs(), 0);
1186
+ let latest = queued;
1187
+ let status = 'queued';
1188
+ while (Date.now() < deadline) {
1189
+ await sleep(Math.min(pollMs, 15_000));
1190
+ latest = await client.request({ path: `operations/${encodeURIComponent(idempotencyKey)}` });
1191
+ const operation = getResponseValue(latest, 'operation');
1192
+ status = operation && typeof operation === 'object' && !Array.isArray(operation) && typeof operation.status === 'string' ? operation.status : 'unknown';
1193
+ if (IMAGE_OPERATION_DONE.has(status)) {
1194
+ const message = describeImageOperation(operation) ?? `image.${action} ${status}.`;
1195
+ return {
1196
+ ok: status === 'succeeded',
1197
+ status: status === 'succeeded' ? undefined : status === 'failed' ? 'failed' : 'unknown',
1198
+ exitCode: status === 'succeeded' ? undefined : 1,
1199
+ message,
1200
+ idempotency_key: idempotencyKey,
1201
+ data: latest,
1202
+ };
1203
+ }
1204
+ }
1205
+ return {
1206
+ ok: true,
1207
+ status: 'still_running',
1208
+ exitCode: 2,
1209
+ message: `Image ${action} is still running. Keep waiting with: coauthor operation status ${idempotencyKey} --json`,
1210
+ idempotency_key: idempotencyKey,
1211
+ data: latest,
1212
+ };
1213
+ }
1152
1214
  const IMAGE_ARTIFACTS = ['article', 'slideshow', 'video'];
1153
1215
  // `--artifact article|slideshow|video` narrows image list/status (and
1154
1216
  // generate --all) to one artifact's placeholders. Without it, every image.
@@ -1294,8 +1356,11 @@ async function runOperationCommand(action, input, client) {
1294
1356
  if (!key)
1295
1357
  throw new Error('Usage: coauthor operation status <operationKey>');
1296
1358
  const data = await client.request({ path: `operations/${encodeURIComponent(key)}` });
1297
- const message = describeImageOperation(getResponseValue(data, 'operation'));
1298
- return message ? { ok: true, message, data } : { ok: true, data };
1359
+ const operation = getResponseValue(data, 'operation');
1360
+ const message = describeImageOperation(operation);
1361
+ // Mirror the operation's status at the top level: agents polling `status` read None (item 83).
1362
+ const status = operation && typeof operation === 'object' && !Array.isArray(operation) && typeof operation.status === 'string' ? operation.status : undefined;
1363
+ return { ok: true, ...(status ? { status } : {}), ...(message ? { message } : {}), data };
1299
1364
  }
1300
1365
  throw new Error('Usage: coauthor operation <list|show|status>');
1301
1366
  }
@@ -1703,7 +1768,16 @@ export function draftCompletionMessage(base, status) {
1703
1768
  const record = check;
1704
1769
  const open = Array.isArray(record.unresolved) ? record.unresolved.length : 0;
1705
1770
  if (record.status === 'needs_review' && open > 0) {
1706
- return `${base}, with ${open} draft check ${open === 1 ? 'item' : 'items'} to review (quality_check.unresolved): the draft may miss part of the brief.`;
1771
+ // Name each item: "may miss part of the brief" alone did not say which part (dogfood Nov 2026, ca17ad34).
1772
+ const lines = record.unresolved.slice(0, 8).map((item) => {
1773
+ const issue = item && typeof item === 'object' && !Array.isArray(item) ? item : {};
1774
+ const where = typeof issue.section_heading === 'string' && issue.section_heading ? ` [${issue.section_heading}]` : '';
1775
+ const detail = typeof issue.detail === 'string' ? issue.detail : String(issue.kind ?? 'issue');
1776
+ const requirement = typeof issue.requirement === 'string' && issue.requirement ? ` Brief item: "${issue.requirement}".` : '';
1777
+ return `- ${String(issue.kind ?? 'issue')}${where}: ${detail}${requirement}`;
1778
+ });
1779
+ const more = open > lines.length ? `\n- …and ${open - lines.length} more in quality_check.unresolved` : '';
1780
+ return `${base}, with ${open} draft check ${open === 1 ? 'item' : 'items'} to review (quality_check.unresolved):\n${lines.join('\n')}${more}`;
1707
1781
  }
1708
1782
  if (record.status === 'failed')
1709
1783
  return `${base}; the draft check could not run, so check it against the brief yourself.`;
@@ -1716,10 +1790,9 @@ async function waitForDraft(client, projectId, initialData, baseUrl) {
1716
1790
  while (Date.now() < deadline) {
1717
1791
  await sleep(pollMs);
1718
1792
  latest = await client.request({ path: `projects/${encodeURIComponent(projectId)}/draft/status` });
1719
- const state = getResponseString(latest, 'project_state');
1720
1793
  const phase = getResponseString(latest, 'phase');
1721
- if (state === 'draft_generated' || state === 'editing' || phase === 'complete') {
1722
- return { ok: true, message: draftCompletionMessage('Draft completed', latest), data: latest };
1794
+ if (isDraftComplete(latest)) {
1795
+ return { ok: true, status: 'draft_generated', message: draftCompletionMessage('Draft completed', latest), data: latest };
1723
1796
  }
1724
1797
  if (phase === 'paused_requires_key')
1725
1798
  return requiresKeyPauseResult(projectId, 'draft', getResponseString(latest, 'message') ?? 'Draft paused: add the required API key to continue.', latest, baseUrl);
@@ -1730,6 +1803,17 @@ async function waitForDraft(client, projectId, initialData, baseUrl) {
1730
1803
  }
1731
1804
  return waitTimedOutResult(projectId, 'draft', initialData, null, latest);
1732
1805
  }
1806
+ /**
1807
+ * The draft is done only when the project says so. The status row keeps the previous draft's "complete" phase
1808
+ * until the worker picks up a new job, so `phase: complete` while the project is still research_structured is
1809
+ * stale: resume used to report "Workflow target draft completed" a minute before the draft finished (item 46).
1810
+ */
1811
+ function isDraftComplete(draftStatus) {
1812
+ const state = getResponseString(draftStatus, 'project_state');
1813
+ if (state === 'draft_generated' || state === 'editing')
1814
+ return true;
1815
+ return state === undefined && getResponseString(draftStatus, 'phase') === 'complete';
1816
+ }
1733
1817
  async function waitForWorkflowDraft(client, projectId, initialData, baseUrl, modelOverrides = {}) {
1734
1818
  const deadline = Date.now() + waitTimeoutMs(40 * 60_000);
1735
1819
  const pollMs = waitPollMs();
@@ -1743,11 +1827,15 @@ async function waitForWorkflowDraft(client, projectId, initialData, baseUrl, mod
1743
1827
  latestDraft = await client.request({ path: `projects/${encodeURIComponent(projectId)}/draft/status` });
1744
1828
  const draftState = getResponseString(latestDraft, 'project_state');
1745
1829
  const draftPhase = getResponseString(latestDraft, 'phase');
1746
- if (draftState === 'draft_generated' || draftState === 'editing' || draftPhase === 'complete') {
1830
+ if (isDraftComplete(latestDraft)) {
1831
+ // `status` is the final state. `workflow` is the start request's reply, whose own status
1832
+ // ("draft_running") describes the moment the wait began, not now.
1747
1833
  return {
1748
1834
  ok: true,
1835
+ status: 'draft_generated',
1749
1836
  message: draftCompletionMessage('Workflow target draft completed', latestDraft),
1750
1837
  data: {
1838
+ status: 'draft_generated',
1751
1839
  workflow: initialData,
1752
1840
  research_status: latestResearch,
1753
1841
  draft_generate: draftGenerate,
@@ -3317,6 +3405,17 @@ function imageStatusRows(data) {
3317
3405
  // Generates every planned image that isn't already done or generating, then
3318
3406
  // optionally waits (under the 10-minute agent shell limit) until none are
3319
3407
  // still generating.
3408
+ /** The server's own error message when there is one ("Worker responded with 502."), else the error text. */
3409
+ function requestErrorText(error) {
3410
+ const body = error && typeof error === 'object' && 'responseBody' in error ? error.responseBody : null;
3411
+ const envelope = body && typeof body === 'object' && !Array.isArray(body) ? body.error : null;
3412
+ if (envelope && typeof envelope === 'object' && !Array.isArray(envelope)) {
3413
+ const { code, message } = envelope;
3414
+ if (typeof message === 'string' && message)
3415
+ return typeof code === 'string' && code ? `${message} (${code})` : message;
3416
+ }
3417
+ return error instanceof Error ? error.message : String(error);
3418
+ }
3320
3419
  async function generateAllImages(client, projectId, wait, artifactQuery = '') {
3321
3420
  const statusPath = `projects/${encodeURIComponent(projectId)}/images/status${artifactQuery}`;
3322
3421
  const before = imageStatusRows(await client.request({ path: statusPath }));
@@ -3333,7 +3432,7 @@ async function generateAllImages(client, projectId, wait, artifactQuery = '') {
3333
3432
  operations.push({ placeholder_id: row.id, idempotency_key: idempotencyKey });
3334
3433
  }
3335
3434
  catch (error) {
3336
- failedToStart.push({ id: row.id, error: error instanceof Error ? error.message : String(error) });
3435
+ failedToStart.push({ id: row.id, error: requestErrorText(error) });
3337
3436
  }
3338
3437
  }
3339
3438
  let rows = before;
@@ -3352,7 +3451,7 @@ async function generateAllImages(client, projectId, wait, artifactQuery = '') {
3352
3451
  started: started.length,
3353
3452
  already_done: before.filter((row) => row.status === 'done').length,
3354
3453
  done: wait ? count('done') : null,
3355
- failed: wait ? count('failed') : null,
3454
+ failed: wait ? count('failed') + failedToStart.length : failedToStart.length || null,
3356
3455
  generating,
3357
3456
  failed_to_start: failedToStart,
3358
3457
  operations,
@@ -3361,9 +3460,11 @@ async function generateAllImages(client, projectId, wait, artifactQuery = '') {
3361
3460
  ok: failedToStart.length === 0 && (!wait || count('failed') === 0),
3362
3461
  status: wait && generating > 0 ? 'still_running' : undefined,
3363
3462
  exitCode: wait && generating > 0 ? 2 : undefined,
3364
- message: wait
3365
- ? `Images: ${count('done')} done, ${count('failed')} failed, ${generating} still generating.${generating > 0 ? ` Check again with: coauthor image status ${projectId} --json` : ''}`
3366
- : `Started ${started.length} image${started.length === 1 ? '' : 's'}. Check progress with: coauthor image status ${projectId} --json`,
3463
+ // Placeholders the worker refused to start count as failed, with the first error: a worker outage read
3464
+ // as "0 done, 0 failed" (item 62).
3465
+ message: `${wait
3466
+ ? `Images: ${count('done')} done, ${count('failed') + failedToStart.length} failed${failedToStart.length ? ` (${failedToStart.length} could not start)` : ''}, ${generating} still generating.${generating > 0 ? ` Check again with: coauthor image status ${projectId} --json` : ''}`
3467
+ : `Started ${started.length} image${started.length === 1 ? '' : 's'}${failedToStart.length ? `; ${failedToStart.length} could not start` : ''}. Check progress with: coauthor image status ${projectId} --json`}${failedToStart.length ? ` First error: ${failedToStart[0].error}` : ''}`,
3367
3468
  data: summary,
3368
3469
  };
3369
3470
  }
@@ -3614,6 +3715,7 @@ function commandHelp(command) {
3614
3715
  '',
3615
3716
  'Creates a project. When --topic or --audience is provided, CoAuthor seeds the saved contract so workflow briefing review can use that context.',
3616
3717
  '--contract accepts a JSON editorial contract object. Top-level --topic and --audience fill missing contract topic/audience fields.',
3718
+ 'Field limits (longer text is rejected with contract_field_too_long, never cut): each must_include, must_avoid, non_negotiables, structure_preferences, evidence_expectations and citation_expectations item up to 600 characters (40 items; 20 for structure_preferences, 30 for evidence/citation); liked/rejected examples 500; topic, angle, target_audience, core_promise and constraints 2,000; additional_editorial_guidance 10,000. Split a long point into several items.',
3617
3719
  '--keyword (SEO mode) sets the Google search keyword the post targets. It is researched when the outline is generated and never replaced automatically.',
3618
3720
  '--seo (SEO mode) sets how the post uses search: optimize (the outline covers what ranks and keeps your angle), my-way (written as planned; the keyword goes only in the SEO title, meta description and slug) or off. Without it, the profile\'s Search optimization setting applies, and "Ask each time" optimizes.',
3619
3721
  ].join('\n'),
@@ -3626,6 +3728,7 @@ function commandHelp(command) {
3626
3728
  'Usage: coauthor workflow resume <project-id> [--target <research|draft>] [--planning-model <id>] [--writing-model <id>] [--wait] [--json]',
3627
3729
  '',
3628
3730
  'Use after an interruption, timeout, or requires_key pause. For draft targets, --wait continues through research and draft generation.',
3731
+ 'If the draft already finished, it reports status draft_generated and starts nothing. With --wait, the top-level status is the final state; data.workflow is the start request\'s reply.',
3629
3732
  ].join('\n'),
3630
3733
  'draft generate': [
3631
3734
  'Usage: coauthor draft generate <project-id> [--writing-model <id>] [--wait] [--json]',
@@ -3890,13 +3993,13 @@ function commandHelp(command) {
3890
3993
  '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).',
3891
3994
  ].join('\n'),
3892
3995
  'image generate': [
3893
- 'Usage: coauthor image generate <project-id> --placeholder-id <id> [--prompt "..."] [--grounding-mode <mode>] [--image-generation-model <id>] [--idempotency-key <key>] [--json]',
3996
+ 'Usage: coauthor image generate <project-id> --placeholder-id <id> [--prompt "..."] [--grounding-mode <mode>] [--image-generation-model <id>] [--idempotency-key <key>] [--wait] [--json]',
3894
3997
  '',
3895
3998
  'Pass the placeholder `id` (UUID) or its `placeholder_id` from coauthor image list. Draft generation creates placeholders.',
3896
3999
  '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)',
3897
4000
  'and is saved, so later regenerations keep it;',
3898
4001
  '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.',
3899
- 'Generation is asynchronous: poll coauthor image status <project-id> --json until it is done.',
4002
+ 'Generation is asynchronous: --wait waits for the image (up to 9 minutes; exit code 2 if it is still running), or poll coauthor image status <project-id> --json.',
3900
4003
  'Prints an operation key (data.idempotency_key in --json): coauthor operation status <key> reports the finished image url or the error.',
3901
4004
  '--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).',
3902
4005
  ].join('\n'),
@@ -3909,9 +4012,9 @@ function commandHelp(command) {
3909
4012
  'and restyling panels skips it. Article and featured images cannot be replaced here.',
3910
4013
  ].join('\n'),
3911
4014
  'image edit': [
3912
- 'Usage: coauthor image edit <project-id> --placeholder-id <id> --edit-prompt "..." [--idempotency-key <key>] [--json]',
4015
+ 'Usage: coauthor image edit <project-id> --placeholder-id <id> --edit-prompt "..." [--idempotency-key <key>] [--wait] [--json]',
3913
4016
  '',
3914
- 'Edits the current image for a placeholder. Poll coauthor image status <project-id> --json for the result.',
4017
+ 'Edits the current image for a placeholder. --wait waits for the edited image (up to 9 minutes; exit code 2 if it is still running); without it, poll coauthor image status <project-id> --json.',
3915
4018
  'Prints an operation key: coauthor operation status <key> reports the edited image url or the error; --idempotency-key <key> replays instead of editing twice.',
3916
4019
  ].join('\n'),
3917
4020
  operation: [
package/dist/index.js CHANGED
@@ -63,7 +63,7 @@ export function formatCliError(error, baseUrl, argv = [], context = {}) {
63
63
  ...(envelope?.details !== undefined ? { details: envelope.details } : {}),
64
64
  ...(error.idempotencyKey ? { idempotency_key: error.idempotencyKey } : {}),
65
65
  };
66
- const operationHint = operationLookupHint(envelope?.details, error.idempotencyKey);
66
+ const operationHint = operationLookupHint(envelope?.details, error.idempotencyKey, error.status);
67
67
  const entitlement = formatEntitlementResult(error.responseBody);
68
68
  if (entitlement)
69
69
  return { error: new Error(entitlement.message), result: { ...entitlement, ...errorFields }, exitCode: 2 };
@@ -123,11 +123,18 @@ function isUsageMessage(message) {
123
123
  // Live actions (publish, export) are recorded as operations under the
124
124
  // Idempotency-Key the CLI sent. Point at it so a caller can check the outcome
125
125
  // instead of retrying blind.
126
- function operationLookupHint(details, idempotencyKey) {
126
+ function operationLookupHint(details, idempotencyKey, httpStatus) {
127
127
  if (!idempotencyKey)
128
128
  return null;
129
129
  if (!details || typeof details !== 'object' || Array.isArray(details) || !('operation' in details))
130
130
  return null;
131
+ const operation = details.operation;
132
+ const status = operation && typeof operation === 'object' && !Array.isArray(operation) ? operation.status : undefined;
133
+ // A recorded failure replays as the same failure ("no new job was queued"), so after a server or worker error
134
+ // the useful retry is a fresh request without the key (item 58).
135
+ if (status === 'failed' || (httpStatus !== undefined && httpStatus >= 500)) {
136
+ return `Operation key: ${idempotencyKey} (recorded as failed; replaying this key returns the same failure). Check it with \`coauthor operation status ${idempotencyKey} --json\`; to try again, rerun without --idempotency-key once the service is back.`;
137
+ }
131
138
  return `Operation key: ${idempotencyKey} (check it with \`coauthor operation status ${idempotencyKey} --json\`; retry with --idempotency-key ${idempotencyKey} to replay safely).`;
132
139
  }
133
140
  function formatEntitlementResult(body) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.79",
3
+ "version": "0.0.81",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -134,6 +134,8 @@ SEO mode is rolling out gradually; accounts outside it get `feature_unavailable`
134
134
  - `structure_preference`: A one-string summary of the overall structure. Use `structure_preferences` for the detailed list.
135
135
  - `confidence_notes`: Explain what the contract was based on and where uncertainty remains.
136
136
 
137
+ **Field limits.** Text over a limit is rejected with `contract_field_too_long` (the error names the field and item), never silently cut. List items: `must_include`, `must_avoid`, `non_negotiables`, `structure_preferences`, `evidence_expectations` and `citation_expectations` items up to 600 characters each (40 items; 20 for `structure_preferences`, 30 for evidence and citation); `liked_examples` / `rejected_examples` items 500. Text fields: `topic`, `angle`, `target_audience`, `core_promise`, `constraints` and `confidence_notes` 2,000; `audience_knowledge_assumptions` and `desired_reader_experience` 600; `additional_editorial_guidance` 10,000. Split a long must-include point into several items rather than one paragraph.
138
+
137
139
  ## Example: practical B2B guide
138
140
 
139
141
  ```json
@@ -13,7 +13,7 @@ Draft generation plans image placeholders, including a featured image (`is_featu
13
13
  - Charts and tables must match the article's numbers, and must not state figures the article deliberately leaves open.
14
14
  - Screens of real products (for example a Google or Meta interface) must not be presented as genuine.
15
15
  - Prices, dates, and text inside the image must match the article.
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`).
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." --wait --json`. `--wait` waits for the edited image (up to 9 minutes; exit code 2 if it is still running) and returns its URL; one image generate takes `--wait` too. To drop an image entirely, remove its `imagePlaceholder` node with a direct draft edit (`references/editing-drafts.md`).
17
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
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`).
19
19
  6. Check the SEO metadata of every generated image (`image list` shows `alt_text`, `file_slug`, `description`). After an article image is generated or edited, CoAuthor looks at the finished image and rewrites all three to describe what is actually in it; this lands a few seconds after the image shows `done`. Fields you or the user set with `coauthor image metadata <id> <placeholder id UUID> --alt-text "..." --file-slug "..." --description "..." --json` (or in the editor) are never rewritten, so set them only to fix something wrong. Images from drafts made before this change (mid-November 2026) keep their plan-based text: rewrite those by hand, because that text was written before the image existed.
@@ -33,7 +33,7 @@ The live URL is where the post is published. `post_details.published_url` holds
33
33
 
34
34
  Posts written without a target search (mostly drafted before SEO mode, many with no post details at all) are still tracked by the monthly check: CoAuthor finds the live page and picks a search to track. `post-details show` returns `data.tracking`: `{published_url, published_url_source, tracking_keyword, tracking_keyword_source}`, the live address and search used for tracking (post details first, then CoAuthor's own record), where `tracking_keyword_source` is `ranked` or `suggested` (CoAuthor picked it), `manual` (set with `--track-search`) or `null`. `--live-url` and `--clear-live-url` work for these posts even without post details. `--track-search` sets the search (1 to 120 characters, kept over later picks; changing the address makes CoAuthor pick again unless you set the search by hand) and `--clear-track-search` asks for a new pick at the next check. `--clear-live-url` stops tracking the post. A post that has a target search of its own answers `post_has_target_search`: its tracked search is that one.
35
35
 
36
- For SEO posts on a profile with a website, `post_details.incoming_link_suggestions` lists existing pages on the user's site that could link to the new post: `{status, suggestions: [{url, title, anchor, sentence}]}`. `status` is `ready`, `none`, or `index_not_ready` (the site was still being indexed when the draft was written; links appear on the next post). It is read-only. After the post is published, offer the user the sentences to add on those pages, linking the anchor text to the new post's URL. It is `null` for other posts.
36
+ For SEO posts on a profile with a website, `post_details.incoming_link_suggestions` lists existing pages on the user's site that could link to the new post: `{status, suggestions: [{url, title, anchor, sentence, placement}]}`. `status` is `ready`, `none`, or `index_not_ready` (the site was still being indexed when the draft was written; links appear on the next post). It is read-only. `placement` is `existing_text` when `sentence` is already on that page: link its `anchor` words to the new post, and add nothing. It is `new_sentence` when the page has no fitting sentence and `sentence` is a proposed addition. Older posts have no `placement`; treat those as new sentences. After the post is published, offer the user these edits. It is `null` for other posts.
37
37
 
38
38
  For SEO posts, `post-details show` also returns `seo`: the target `keyword`, its `market`, `seo_research_credits`, and a `checks` list computed from the current draft and title. Each check has an `id`, a `status` (`pass`, `warn`, `fail`, or `skip` when there is nothing to measure) and a plain `detail`. The ids are `keyword_in_title`, `keyword_in_intro` (first 100 words), `secondary_in_h2`, `table_stakes`, `angle_section`, `questions_answered`, `internal_link`, `outbound_sources` and `length`. A `fail` on the title is worth fixing before publishing: edit it with `project rename`. A `warn` on `keyword_in_intro` is fine when the keyword wouldn't read naturally in the opening, so don't force it in. `secondary_in_h2` and `questions_answered` are optional: they report `pass` or `skip`, never `warn`. `seo` is `null` for other posts.
39
39
 
@@ -8,6 +8,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
8
8
  | --- | --- | --- |
9
9
  | `needs_clarification` | The brief is too thin to outline well. | Answer `data.clarification_questions` from your context (ask the user only what you can't know), update the contract, run again. |
10
10
  | `timed_out` | The wait window ended; the work is still running on CoAuthor's side. | Run the resume command in `data.next_commands`, usually `coauthor workflow resume <id> --target draft --wait --json`. |
11
+ | `contract_field_too_long` | A brief field or list item is over its limit (`data.fields` lists each one: list items 600 characters, `additional_editorial_guidance` 10,000, other text fields 600 or 2,000, and 20–40 items per list). Nothing was saved. | Shorten the named fields, or split a long item into several items, and save again. |
11
12
  | `still_running` | Same, for a draft revision. | `coauthor draft revision show <id> <revision-id> --json`. |
12
13
  | `research_structuring` | Research finished and is being organized for drafting. Normal. | Keep waiting or resume toward draft. Don't rewind. |
13
14
  | `research_running_stale` | Research progress has not changed for 30+ minutes. | Check `coauthor research status <id> --json` a few minutes apart and look at `coauthor research structured <id> --json`. Rewinding (`coauthor workflow rewind <id> --target research --json`) discards the research done so far and costs credits to redo, so ask the user first. |
@@ -227,6 +227,8 @@ SEO mode is rolling out gradually; accounts outside it get `feature_unavailable`
227
227
  - `structure_preference`: A one-string summary of the overall structure. Use `structure_preferences` for the detailed list.
228
228
  - `confidence_notes`: Explain what the contract was based on and where uncertainty remains.
229
229
 
230
+ **Field limits.** Text over a limit is rejected with `contract_field_too_long` (the error names the field and item), never silently cut. List items: `must_include`, `must_avoid`, `non_negotiables`, `structure_preferences`, `evidence_expectations` and `citation_expectations` items up to 600 characters each (40 items; 20 for `structure_preferences`, 30 for evidence and citation); `liked_examples` / `rejected_examples` items 500. Text fields: `topic`, `angle`, `target_audience`, `core_promise`, `constraints` and `confidence_notes` 2,000; `audience_knowledge_assumptions` and `desired_reader_experience` 600; `additional_editorial_guidance` 10,000. Split a long must-include point into several items rather than one paragraph.
231
+
230
232
  ### Example: practical B2B guide
231
233
 
232
234
  ```json
@@ -378,7 +380,7 @@ Draft generation plans image placeholders, including a featured image (`is_featu
378
380
  - Charts and tables must match the article's numbers, and must not state figures the article deliberately leaves open.
379
381
  - Screens of real products (for example a Google or Meta interface) must not be presented as genuine.
380
382
  - Prices, dates, and text inside the image must match the article.
381
- 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`).
383
+ 5. Fix an image with an instruction: `coauthor image edit <id> --placeholder-id <id UUID> --edit-prompt "Remove the price tag; keep everything else." --wait --json`. `--wait` waits for the edited image (up to 9 minutes; exit code 2 if it is still running) and returns its URL; one image generate takes `--wait` too. To drop an image entirely, remove its `imagePlaceholder` node with a direct draft edit (`references/editing-drafts.md`).
382
384
  - 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.
383
385
  - `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`).
384
386
  6. Check the SEO metadata of every generated image (`image list` shows `alt_text`, `file_slug`, `description`). After an article image is generated or edited, CoAuthor looks at the finished image and rewrites all three to describe what is actually in it; this lands a few seconds after the image shows `done`. Fields you or the user set with `coauthor image metadata <id> <placeholder id UUID> --alt-text "..." --file-slug "..." --description "..." --json` (or in the editor) are never rewritten, so set them only to fix something wrong. Images from drafts made before this change (mid-November 2026) keep their plan-based text: rewrite those by hand, because that text was written before the image existed.
@@ -479,7 +481,7 @@ The live URL is where the post is published. `post_details.published_url` holds
479
481
 
480
482
  Posts written without a target search (mostly drafted before SEO mode, many with no post details at all) are still tracked by the monthly check: CoAuthor finds the live page and picks a search to track. `post-details show` returns `data.tracking`: `{published_url, published_url_source, tracking_keyword, tracking_keyword_source}`, the live address and search used for tracking (post details first, then CoAuthor's own record), where `tracking_keyword_source` is `ranked` or `suggested` (CoAuthor picked it), `manual` (set with `--track-search`) or `null`. `--live-url` and `--clear-live-url` work for these posts even without post details. `--track-search` sets the search (1 to 120 characters, kept over later picks; changing the address makes CoAuthor pick again unless you set the search by hand) and `--clear-track-search` asks for a new pick at the next check. `--clear-live-url` stops tracking the post. A post that has a target search of its own answers `post_has_target_search`: its tracked search is that one.
481
483
 
482
- For SEO posts on a profile with a website, `post_details.incoming_link_suggestions` lists existing pages on the user's site that could link to the new post: `{status, suggestions: [{url, title, anchor, sentence}]}`. `status` is `ready`, `none`, or `index_not_ready` (the site was still being indexed when the draft was written; links appear on the next post). It is read-only. After the post is published, offer the user the sentences to add on those pages, linking the anchor text to the new post's URL. It is `null` for other posts.
484
+ For SEO posts on a profile with a website, `post_details.incoming_link_suggestions` lists existing pages on the user's site that could link to the new post: `{status, suggestions: [{url, title, anchor, sentence, placement}]}`. `status` is `ready`, `none`, or `index_not_ready` (the site was still being indexed when the draft was written; links appear on the next post). It is read-only. `placement` is `existing_text` when `sentence` is already on that page: link its `anchor` words to the new post, and add nothing. It is `new_sentence` when the page has no fitting sentence and `sentence` is a proposed addition. Older posts have no `placement`; treat those as new sentences. After the post is published, offer the user these edits. It is `null` for other posts.
483
485
 
484
486
  For SEO posts, `post-details show` also returns `seo`: the target `keyword`, its `market`, `seo_research_credits`, and a `checks` list computed from the current draft and title. Each check has an `id`, a `status` (`pass`, `warn`, `fail`, or `skip` when there is nothing to measure) and a plain `detail`. The ids are `keyword_in_title`, `keyword_in_intro` (first 100 words), `secondary_in_h2`, `table_stakes`, `angle_section`, `questions_answered`, `internal_link`, `outbound_sources` and `length`. A `fail` on the title is worth fixing before publishing: edit it with `project rename`. A `warn` on `keyword_in_intro` is fine when the keyword wouldn't read naturally in the opening, so don't force it in. `secondary_in_h2` and `questions_answered` are optional: they report `pass` or `skip`, never `warn`. `seo` is `null` for other posts.
485
487
 
@@ -725,6 +727,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
725
727
  | --- | --- | --- |
726
728
  | `needs_clarification` | The brief is too thin to outline well. | Answer `data.clarification_questions` from your context (ask the user only what you can't know), update the contract, run again. |
727
729
  | `timed_out` | The wait window ended; the work is still running on CoAuthor's side. | Run the resume command in `data.next_commands`, usually `coauthor workflow resume <id> --target draft --wait --json`. |
730
+ | `contract_field_too_long` | A brief field or list item is over its limit (`data.fields` lists each one: list items 600 characters, `additional_editorial_guidance` 10,000, other text fields 600 or 2,000, and 20–40 items per list). Nothing was saved. | Shorten the named fields, or split a long item into several items, and save again. |
728
731
  | `still_running` | Same, for a draft revision. | `coauthor draft revision show <id> <revision-id> --json`. |
729
732
  | `research_structuring` | Research finished and is being organized for drafting. Normal. | Keep waiting or resume toward draft. Don't rewind. |
730
733
  | `research_running_stale` | Research progress has not changed for 30+ minutes. | Check `coauthor research status <id> --json` a few minutes apart and look at `coauthor research structured <id> --json`. Rewinding (`coauthor workflow rewind <id> --target research --json`) discards the research done so far and costs credits to redo, so ask the user first. |