@clickminded/coauthor-cli 0.0.80 → 0.0.82

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,
@@ -1988,6 +2076,22 @@ function revisionMessage(artifact, data) {
1988
2076
  if (diff.reordered === true)
1989
2077
  lines.push('Sections were reordered.');
1990
2078
  }
2079
+ const notApplied = getResponseValue(data, 'not_applied');
2080
+ if (Array.isArray(notApplied) && notApplied.length > 0) {
2081
+ lines.push(`Not applied (${notApplied.length}):`);
2082
+ for (const entry of notApplied) {
2083
+ const record = entry && typeof entry === 'object' && !Array.isArray(entry) ? entry : {};
2084
+ const request = typeof record.request === 'string' ? record.request : JSON.stringify(entry);
2085
+ const reason = typeof record.reason === 'string' && record.reason ? ` (${record.reason})` : '';
2086
+ lines.push(`- ${request}${reason}`);
2087
+ }
2088
+ }
2089
+ const plan = getResponseValue(data, 'research_plan');
2090
+ if (plan && typeof plan === 'object' && !Array.isArray(plan) && plan.stale === true) {
2091
+ const missing = plan.sections_without_tasks;
2092
+ const names = Array.isArray(missing) ? missing.filter((name) => typeof name === 'string') : [];
2093
+ lines.push(`The research plan is out of date${names.length ? ` (no tasks for: ${names.join('; ')})` : ''}. After approving the outline, run: coauthor research-plan generate <project-id> --json`);
2094
+ }
1991
2095
  lines.push(`Review it with: coauthor ${artifact} show <project-id> --json, then approve with: coauthor ${artifact} approve <project-id> --json`);
1992
2096
  return lines.join('\n');
1993
2097
  }
@@ -3317,6 +3421,17 @@ function imageStatusRows(data) {
3317
3421
  // Generates every planned image that isn't already done or generating, then
3318
3422
  // optionally waits (under the 10-minute agent shell limit) until none are
3319
3423
  // still generating.
3424
+ /** The server's own error message when there is one ("Worker responded with 502."), else the error text. */
3425
+ function requestErrorText(error) {
3426
+ const body = error && typeof error === 'object' && 'responseBody' in error ? error.responseBody : null;
3427
+ const envelope = body && typeof body === 'object' && !Array.isArray(body) ? body.error : null;
3428
+ if (envelope && typeof envelope === 'object' && !Array.isArray(envelope)) {
3429
+ const { code, message } = envelope;
3430
+ if (typeof message === 'string' && message)
3431
+ return typeof code === 'string' && code ? `${message} (${code})` : message;
3432
+ }
3433
+ return error instanceof Error ? error.message : String(error);
3434
+ }
3320
3435
  async function generateAllImages(client, projectId, wait, artifactQuery = '') {
3321
3436
  const statusPath = `projects/${encodeURIComponent(projectId)}/images/status${artifactQuery}`;
3322
3437
  const before = imageStatusRows(await client.request({ path: statusPath }));
@@ -3333,7 +3448,7 @@ async function generateAllImages(client, projectId, wait, artifactQuery = '') {
3333
3448
  operations.push({ placeholder_id: row.id, idempotency_key: idempotencyKey });
3334
3449
  }
3335
3450
  catch (error) {
3336
- failedToStart.push({ id: row.id, error: error instanceof Error ? error.message : String(error) });
3451
+ failedToStart.push({ id: row.id, error: requestErrorText(error) });
3337
3452
  }
3338
3453
  }
3339
3454
  let rows = before;
@@ -3352,7 +3467,7 @@ async function generateAllImages(client, projectId, wait, artifactQuery = '') {
3352
3467
  started: started.length,
3353
3468
  already_done: before.filter((row) => row.status === 'done').length,
3354
3469
  done: wait ? count('done') : null,
3355
- failed: wait ? count('failed') : null,
3470
+ failed: wait ? count('failed') + failedToStart.length : failedToStart.length || null,
3356
3471
  generating,
3357
3472
  failed_to_start: failedToStart,
3358
3473
  operations,
@@ -3361,9 +3476,11 @@ async function generateAllImages(client, projectId, wait, artifactQuery = '') {
3361
3476
  ok: failedToStart.length === 0 && (!wait || count('failed') === 0),
3362
3477
  status: wait && generating > 0 ? 'still_running' : undefined,
3363
3478
  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`,
3479
+ // Placeholders the worker refused to start count as failed, with the first error: a worker outage read
3480
+ // as "0 done, 0 failed" (item 62).
3481
+ message: `${wait
3482
+ ? `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` : ''}`
3483
+ : `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
3484
  data: summary,
3368
3485
  };
3369
3486
  }
@@ -3614,6 +3731,7 @@ function commandHelp(command) {
3614
3731
  '',
3615
3732
  'Creates a project. When --topic or --audience is provided, CoAuthor seeds the saved contract so workflow briefing review can use that context.',
3616
3733
  '--contract accepts a JSON editorial contract object. Top-level --topic and --audience fill missing contract topic/audience fields.',
3734
+ '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
3735
  '--keyword (SEO mode) sets the Google search keyword the post targets. It is researched when the outline is generated and never replaced automatically.',
3618
3736
  '--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
3737
  ].join('\n'),
@@ -3626,6 +3744,7 @@ function commandHelp(command) {
3626
3744
  'Usage: coauthor workflow resume <project-id> [--target <research|draft>] [--planning-model <id>] [--writing-model <id>] [--wait] [--json]',
3627
3745
  '',
3628
3746
  'Use after an interruption, timeout, or requires_key pause. For draft targets, --wait continues through research and draft generation.',
3747
+ '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
3748
  ].join('\n'),
3630
3749
  'draft generate': [
3631
3750
  'Usage: coauthor draft generate <project-id> [--writing-model <id>] [--wait] [--json]',
@@ -3769,7 +3888,7 @@ function commandHelp(command) {
3769
3888
  'Usage: coauthor outline <show|generate|revise|save|approve> <project-id> [--feedback "..."] [--data <json|@file>] [--planning-model <id>] [--json]',
3770
3889
  '',
3771
3890
  'generate creates an outline without approving it (data.sections). show returns the saved outline (data.artifact).',
3772
- 'revise --feedback: CoAuthor rewrites the outline from your feedback, saves it (not approved), and returns data.diff.',
3891
+ 'revise --feedback: CoAuthor rewrites the outline from your feedback, saves it (not approved), and returns data.diff and data.not_applied (requested changes it did not make, with reasons).',
3773
3892
  'save replaces it with the complete list {"sections":[...]}; omitted sections are removed. approve approves the saved outline.',
3774
3893
  ].join('\n'),
3775
3894
  'research-plan': [
@@ -3890,13 +4009,13 @@ function commandHelp(command) {
3890
4009
  '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
4010
  ].join('\n'),
3892
4011
  'image generate': [
3893
- 'Usage: coauthor image generate <project-id> --placeholder-id <id> [--prompt "..."] [--grounding-mode <mode>] [--image-generation-model <id>] [--idempotency-key <key>] [--json]',
4012
+ 'Usage: coauthor image generate <project-id> --placeholder-id <id> [--prompt "..."] [--grounding-mode <mode>] [--image-generation-model <id>] [--idempotency-key <key>] [--wait] [--json]',
3894
4013
  '',
3895
4014
  'Pass the placeholder `id` (UUID) or its `placeholder_id` from coauthor image list. Draft generation creates placeholders.',
3896
4015
  '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
4016
  'and is saved, so later regenerations keep it;',
3898
4017
  '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.',
4018
+ '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
4019
  'Prints an operation key (data.idempotency_key in --json): coauthor operation status <key> reports the finished image url or the error.',
3901
4020
  '--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
4021
  ].join('\n'),
@@ -3909,9 +4028,9 @@ function commandHelp(command) {
3909
4028
  'and restyling panels skips it. Article and featured images cannot be replaced here.',
3910
4029
  ].join('\n'),
3911
4030
  'image edit': [
3912
- 'Usage: coauthor image edit <project-id> --placeholder-id <id> --edit-prompt "..." [--idempotency-key <key>] [--json]',
4031
+ 'Usage: coauthor image edit <project-id> --placeholder-id <id> --edit-prompt "..." [--idempotency-key <key>] [--wait] [--json]',
3913
4032
  '',
3914
- 'Edits the current image for a placeholder. Poll coauthor image status <project-id> --json for the result.',
4033
+ '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
4034
  '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
4035
  ].join('\n'),
3917
4036
  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.80",
3
+ "version": "0.0.82",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -33,7 +33,7 @@ Typical timing: brief and outline under a minute; research and draft 3–10 minu
33
33
  **Profile first.** A writer profile carries the voice, writer and business context, and image style, and a project keeps its profile for good. Run `coauthor profile list --json`. With one profile, omit `--profile`. With several, pick the one that fits the request (for example the company blog vs a personal newsletter) and ask the user if it isn't clear.
34
34
  **Sources.** If the user gave you documents to work from (PDF, .txt, .md), add each before research: `coauthor source add <id> <file> --json` (up to 5; see `references/brief-and-contract.md`). Put source URLs in the brief instead.
35
35
  2. **Brief review.** `coauthor brief review <id> --json`. CoAuthor critiques the brief and returns `data.verdict`, `data.concerns`, and `data.questions`, each with `why`, the `field` it changes, and `answerable_by`. Answer the `agent` questions from your context; take `human` ones (opinions, private business facts, numbers, risk tolerance) to the user in one message, or, if they asked not to be interrupted, answer them as assumptions. Write `{"answers":[{"question","answer","source":"agent|user|assumption"}]}` to a file (add `"apply_suggested_patch": <data.suggested_patch>` if its suggestions are good) and run `coauthor brief answer <id> --data @answers.json --json`. Repeat once if the verdict was `needs_answers`, then approve: `coauthor contract approve <id> --json`. Log what you assumed: `coauthor log add <id> --kind assumption --message "..." --json`.
36
- 3. **Outline checkpoint.** `coauthor outline generate <id> --json` (this does not approve it; sections are in `data.sections`). Review it as the user's editor: every section serves the core promise, must-includes are covered, the order builds, nothing is generic, repeated, or unsupported. Find problems; a bare approval is the exception. Send all your changes in one request: `coauthor outline revise <id> --feedback "Merge sections 3 and 4. Replace the conclusion with a one-week checklist." --json`. It saves the revision and returns `data.diff` (added, removed, renamed, changed, reordered); check the diff matches what you asked, and revise again (at most twice) if not. For exact wording you already have, `coauthor outline save <id> --data @outline.json --json` with the complete `{"sections":[...]}` instead. Then `coauthor outline approve <id> --json` and log it (`coauthor log add <id> --message "Approved the outline after …" --json`). If the user asked to see the outline, show it to them here and wait.
36
+ 3. **Outline checkpoint.** `coauthor outline generate <id> --json` (this does not approve it; sections are in `data.sections`). Review it as the user's editor: every section serves the core promise, must-includes are covered, the order builds, nothing is generic, repeated, or unsupported. Find problems; a bare approval is the exception. Send all your changes in one request: `coauthor outline revise <id> --feedback "Merge sections 3 and 4. Replace the conclusion with a one-week checklist." --json`. It saves the revision and returns `data.diff` (added, removed, renamed, changed, reordered); check the diff matches what you asked, and revise again (at most twice) if not. `data.not_applied` lists any requested change CoAuthor did not make, each with `request` and `reason`; resend those with clearer wording or tell the user why they were left out. When `data.research_plan.stale` is true (the outline changed after a research plan was made; `sections_without_tasks` lists sections it does not cover), run `coauthor research-plan generate <id> --json` after approving the outline instead of approving the old plan. For exact wording you already have, `coauthor outline save <id> --data @outline.json --json` with the complete `{"sections":[...]}` instead. Then `coauthor outline approve <id> --json` and log it (`coauthor log add <id> --message "Approved the outline after …" --json`). If the user asked to see the outline, show it to them here and wait.
37
37
  4. **Research-plan checkpoint.** `coauthor research-plan generate <id> --json` (tasks in `data.research_tasks`). Check every section has a task, every claim that needs proof points at the right sources (including URLs the user gave you), and deep research is used only where it matters. Fix it with `coauthor research-plan revise <id> --feedback "Add a task for the checklist section. Use https://… as a required source for the limits section." --json` and check `data.diff`, then `coauthor research-plan approve <id> --json` and log it.
38
38
  5. **Research and draft.** `COAUTHOR_CLI_WAIT_TIMEOUT_MS=540000 coauthor workflow run <id> --target draft --wait --json`. It is done when the message says the draft completed (`data.draft_status.project_state` is `draft_generated`); ignore the stale `data.workflow.status`. On `timed_out`: `coauthor workflow resume <id> --target draft --wait --json`.
39
39
  6. **Quality pass.** CoAuthor already checks each new draft against the brief and for consistency, and fixes what it can: must-include items, non-negotiables, tables vs their sections, "see the table" references, unsourced "most readers" claims, FAQ answers that defer, and links (cut-short or malformed URLs, dead pages, citations that open a page about something else). Whatever is still open is in `quality_check.unresolved` of `coauthor draft status <id> --json` (and `post-details show`), and the completion message says how many. Fix those first. Then `coauthor draft get <id> --format markdown --json` and read `data.markdown` in full. Check it against the brief's must-include, must-avoid, and non-negotiables. Look for: notes about the research process ("the retrieved sources do not…"), invented "checked <date>" lines, numbered lists that restart at 1, garbled `*`, `_`, or code spans, literal `[ ]` in checklists, the same caveat repeated across sections, claims without a source or cited to a page that doesn't support them, contradictions, and a messy Sources list (generic titles like "Google", duplicate entries). Fix them in step 8.
@@ -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
 
@@ -22,6 +22,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
22
22
  | `draft_exists` | `brief answer` on a project that already has a draft. | Edit the draft instead. `--force` only if the user wants to restart from the brief (the draft is regenerated). |
23
23
  | `downstream_exists` | `outline revise` or `research-plan revise` after research ran. | Same: edit the draft, or `--force` to restart from that stage with the user's OK. |
24
24
  | `outline_generation_failed` | `outline generate` (or `workflow run`/`advance` reaching the outline) couldn't produce an outline. Nothing was saved; the current outline is unchanged. | Retry once after a minute. If it fails again, tell the user; never write a generic outline yourself and approve it. |
25
+ | `research_plan_stale` | `research-plan approve` on a plan made before the outline changed, with no tasks for some current sections. | `coauthor research-plan generate <id> --json`, review it, then approve. |
25
26
  | `revision_invalid` | CoAuthor's revision referenced sections that don't exist. | Run `revise` again with feedback that names sections by their current headings. |
26
27
  | `stale_draft` | The draft changed after you read it. | Re-read with `draft get`, reapply your edit, save. |
27
28
  | `user_recently_editing` | The user saved in the browser in the last 90 seconds. | Wait, or ask them. `--force` only with their OK. |
@@ -35,7 +35,7 @@ Typical timing: brief and outline under a minute; research and draft 3–10 minu
35
35
  **Profile first.** A writer profile carries the voice, writer and business context, and image style, and a project keeps its profile for good. Run `coauthor profile list --json`. With one profile, omit `--profile`. With several, pick the one that fits the request (for example the company blog vs a personal newsletter) and ask the user if it isn't clear.
36
36
  **Sources.** If the user gave you documents to work from (PDF, .txt, .md), add each before research: `coauthor source add <id> <file> --json` (up to 5; see `references/brief-and-contract.md`). Put source URLs in the brief instead.
37
37
  2. **Brief review.** `coauthor brief review <id> --json`. CoAuthor critiques the brief and returns `data.verdict`, `data.concerns`, and `data.questions`, each with `why`, the `field` it changes, and `answerable_by`. Answer the `agent` questions from your context; take `human` ones (opinions, private business facts, numbers, risk tolerance) to the user in one message, or, if they asked not to be interrupted, answer them as assumptions. Write `{"answers":[{"question","answer","source":"agent|user|assumption"}]}` to a file (add `"apply_suggested_patch": <data.suggested_patch>` if its suggestions are good) and run `coauthor brief answer <id> --data @answers.json --json`. Repeat once if the verdict was `needs_answers`, then approve: `coauthor contract approve <id> --json`. Log what you assumed: `coauthor log add <id> --kind assumption --message "..." --json`.
38
- 3. **Outline checkpoint.** `coauthor outline generate <id> --json` (this does not approve it; sections are in `data.sections`). Review it as the user's editor: every section serves the core promise, must-includes are covered, the order builds, nothing is generic, repeated, or unsupported. Find problems; a bare approval is the exception. Send all your changes in one request: `coauthor outline revise <id> --feedback "Merge sections 3 and 4. Replace the conclusion with a one-week checklist." --json`. It saves the revision and returns `data.diff` (added, removed, renamed, changed, reordered); check the diff matches what you asked, and revise again (at most twice) if not. For exact wording you already have, `coauthor outline save <id> --data @outline.json --json` with the complete `{"sections":[...]}` instead. Then `coauthor outline approve <id> --json` and log it (`coauthor log add <id> --message "Approved the outline after …" --json`). If the user asked to see the outline, show it to them here and wait.
38
+ 3. **Outline checkpoint.** `coauthor outline generate <id> --json` (this does not approve it; sections are in `data.sections`). Review it as the user's editor: every section serves the core promise, must-includes are covered, the order builds, nothing is generic, repeated, or unsupported. Find problems; a bare approval is the exception. Send all your changes in one request: `coauthor outline revise <id> --feedback "Merge sections 3 and 4. Replace the conclusion with a one-week checklist." --json`. It saves the revision and returns `data.diff` (added, removed, renamed, changed, reordered); check the diff matches what you asked, and revise again (at most twice) if not. `data.not_applied` lists any requested change CoAuthor did not make, each with `request` and `reason`; resend those with clearer wording or tell the user why they were left out. When `data.research_plan.stale` is true (the outline changed after a research plan was made; `sections_without_tasks` lists sections it does not cover), run `coauthor research-plan generate <id> --json` after approving the outline instead of approving the old plan. For exact wording you already have, `coauthor outline save <id> --data @outline.json --json` with the complete `{"sections":[...]}` instead. Then `coauthor outline approve <id> --json` and log it (`coauthor log add <id> --message "Approved the outline after …" --json`). If the user asked to see the outline, show it to them here and wait.
39
39
  4. **Research-plan checkpoint.** `coauthor research-plan generate <id> --json` (tasks in `data.research_tasks`). Check every section has a task, every claim that needs proof points at the right sources (including URLs the user gave you), and deep research is used only where it matters. Fix it with `coauthor research-plan revise <id> --feedback "Add a task for the checklist section. Use https://… as a required source for the limits section." --json` and check `data.diff`, then `coauthor research-plan approve <id> --json` and log it.
40
40
  5. **Research and draft.** `COAUTHOR_CLI_WAIT_TIMEOUT_MS=540000 coauthor workflow run <id> --target draft --wait --json`. It is done when the message says the draft completed (`data.draft_status.project_state` is `draft_generated`); ignore the stale `data.workflow.status`. On `timed_out`: `coauthor workflow resume <id> --target draft --wait --json`.
41
41
  6. **Quality pass.** CoAuthor already checks each new draft against the brief and for consistency, and fixes what it can: must-include items, non-negotiables, tables vs their sections, "see the table" references, unsourced "most readers" claims, FAQ answers that defer, and links (cut-short or malformed URLs, dead pages, citations that open a page about something else). Whatever is still open is in `quality_check.unresolved` of `coauthor draft status <id> --json` (and `post-details show`), and the completion message says how many. Fix those first. Then `coauthor draft get <id> --format markdown --json` and read `data.markdown` in full. Check it against the brief's must-include, must-avoid, and non-negotiables. Look for: notes about the research process ("the retrieved sources do not…"), invented "checked <date>" lines, numbered lists that restart at 1, garbled `*`, `_`, or code spans, literal `[ ]` in checklists, the same caveat repeated across sections, claims without a source or cited to a page that doesn't support them, contradictions, and a messy Sources list (generic titles like "Google", duplicate entries). Fix them in step 8.
@@ -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
 
@@ -739,6 +741,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
739
741
  | `draft_exists` | `brief answer` on a project that already has a draft. | Edit the draft instead. `--force` only if the user wants to restart from the brief (the draft is regenerated). |
740
742
  | `downstream_exists` | `outline revise` or `research-plan revise` after research ran. | Same: edit the draft, or `--force` to restart from that stage with the user's OK. |
741
743
  | `outline_generation_failed` | `outline generate` (or `workflow run`/`advance` reaching the outline) couldn't produce an outline. Nothing was saved; the current outline is unchanged. | Retry once after a minute. If it fails again, tell the user; never write a generic outline yourself and approve it. |
744
+ | `research_plan_stale` | `research-plan approve` on a plan made before the outline changed, with no tasks for some current sections. | `coauthor research-plan generate <id> --json`, review it, then approve. |
742
745
  | `revision_invalid` | CoAuthor's revision referenced sections that don't exist. | Run `revise` again with feedback that names sections by their current headings. |
743
746
  | `stale_draft` | The draft changed after you read it. | Re-read with `draft get`, reapply your edit, save. |
744
747
  | `user_recently_editing` | The user saved in the browser in the last 90 seconds. | Wait, or ask them. `--force` only with their OK. |