@clickminded/coauthor-cli 0.0.23 → 0.0.24

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
@@ -29,6 +29,10 @@ export async function runCommand(input, context) {
29
29
  return runArtifactCommand('research-plan', action, input, context.client);
30
30
  if (scope === 'research')
31
31
  return runResearchCommand(action, input, context);
32
+ if (scope === 'brief')
33
+ return runBriefCommand(action, input, context.client);
34
+ if (scope === 'log')
35
+ return runLogCommand(action, input, context.client);
32
36
  if (scope === 'draft')
33
37
  return runDraftCommand(action, input, context);
34
38
  if (scope === 'workflow')
@@ -412,6 +416,17 @@ async function runArtifactCommand(artifact, action, input, client) {
412
416
  const data = await client.request({ path: basePath });
413
417
  return { ok: true, data };
414
418
  }
419
+ if (action === 'revise' && artifact !== 'contract') {
420
+ const feedback = getString(input.values, 'feedback') ?? input.positionals.slice(1).join(' ');
421
+ if (!feedback.trim())
422
+ throw new Error(`Usage: coauthor ${artifact} revise <projectId> --feedback "..." [--force]`);
423
+ const data = await client.request({
424
+ method: 'POST',
425
+ path: `${basePath}/revise`,
426
+ body: { feedback, ...(getBoolean(input.values, 'force') ? { force: true } : {}) },
427
+ });
428
+ return { ok: true, message: revisionMessage(artifact, data), data };
429
+ }
415
430
  if (artifact === 'contract' && action === 'generate') {
416
431
  throw new Error('contract generate is not supported. The brief comes from `coauthor project create`; refine it with `coauthor chat <project-id> --stage contract --message "..."` or replace it with `coauthor contract save <project-id> --data @contract.json`.');
417
432
  }
@@ -1287,8 +1302,21 @@ async function buildArtifactApproveBody(artifact, input, client, basePath) {
1287
1302
  function enrichChatResult(data, projectId, stage) {
1288
1303
  if (!data || typeof data !== 'object' || Array.isArray(data))
1289
1304
  return data;
1305
+ // Return the reply and which tools CoAuthor used, not the raw model message
1306
+ // (reasoning signatures and tool payloads are noise for an agent).
1307
+ const parts = extractNestedValue(data, ['responseMessage', 'parts']);
1308
+ const tools = Array.isArray(parts)
1309
+ ? parts.flatMap((part) => {
1310
+ const type = part && typeof part === 'object' && !Array.isArray(part) ? part.type : null;
1311
+ if (typeof type !== 'string' || !type.startsWith('tool-'))
1312
+ return [];
1313
+ const state = part.state;
1314
+ return [{ tool: type.slice('tool-'.length), state: typeof state === 'string' ? state : null }];
1315
+ })
1316
+ : [];
1290
1317
  const result = {
1291
- ...data,
1318
+ text: typeof data.text === 'string' ? data.text : '',
1319
+ tools,
1292
1320
  transcript_command: `coauthor chat show ${projectId} --json`,
1293
1321
  };
1294
1322
  if (stage?.trim().toLowerCase() === 'draft') {
@@ -1297,6 +1325,66 @@ function enrichChatResult(data, projectId, stage) {
1297
1325
  }
1298
1326
  return result;
1299
1327
  }
1328
+ function revisionMessage(artifact, data) {
1329
+ const summary = getResponseString(data, 'summary');
1330
+ const diff = getResponseValue(data, 'diff');
1331
+ const lines = [`${artifact === 'outline' ? 'Outline' : 'Research plan'} revised and saved (not approved).`];
1332
+ if (summary)
1333
+ lines.push(summary);
1334
+ if (diff && typeof diff === 'object' && !Array.isArray(diff)) {
1335
+ const list = (key) => {
1336
+ const value = diff[key];
1337
+ return Array.isArray(value) ? value : [];
1338
+ };
1339
+ const names = (values) => values.map((value) => typeof value === 'string' ? value : JSON.stringify(value)).join('; ');
1340
+ if (list('added').length > 0)
1341
+ lines.push(`Added: ${names(list('added'))}`);
1342
+ if (list('removed').length > 0)
1343
+ lines.push(`Removed: ${names(list('removed'))}`);
1344
+ if (list('renamed').length > 0)
1345
+ lines.push(`Renamed: ${list('renamed').map((entry) => `${entry.from} -> ${entry.to}`).join('; ')}`);
1346
+ if (list('changed').length > 0)
1347
+ lines.push(`Changed: ${list('changed').map((entry) => entry.heading ?? entry.section).join('; ')}`);
1348
+ if (diff.reordered === true)
1349
+ lines.push('Sections were reordered.');
1350
+ }
1351
+ lines.push(`Review it with: coauthor ${artifact} show <project-id> --json, then approve with: coauthor ${artifact} approve <project-id> --json`);
1352
+ return lines.join('\n');
1353
+ }
1354
+ async function runBriefCommand(action, input, client) {
1355
+ const projectId = requireProjectId(input);
1356
+ const path = `projects/${encodeURIComponent(projectId)}/brief`;
1357
+ if (action === 'review') {
1358
+ const data = await client.request({ method: 'POST', path: `${path}/review`, body: {} });
1359
+ return { ok: true, data };
1360
+ }
1361
+ if (action === 'answer') {
1362
+ if (readJsonOptionText(input.values) === undefined) {
1363
+ throw new Error('Usage: coauthor brief answer <projectId> --data @answers.json ({"answers":[{"question":"...","answer":"...","source":"agent|user|assumption"}]})');
1364
+ }
1365
+ const body = parseJsonOption(input.values);
1366
+ if (getBoolean(input.values, 'force'))
1367
+ body.force = true;
1368
+ const data = await client.request({ method: 'POST', path: `${path}/answer`, body });
1369
+ return { ok: true, message: `Brief updated (not approved). Changed: ${getResponseValue(data, 'changed_fields')?.join(', ') || 'nothing'}.`, data };
1370
+ }
1371
+ throw new Error('Usage: coauthor brief <review|answer> <projectId>');
1372
+ }
1373
+ async function runLogCommand(action, input, client) {
1374
+ const projectId = requireProjectId(input);
1375
+ const path = `projects/${encodeURIComponent(projectId)}/log`;
1376
+ if (action === 'show' || !action)
1377
+ return { ok: true, data: await client.request({ path }) };
1378
+ if (action === 'add') {
1379
+ const message = getString(input.values, 'message') ?? input.positionals.slice(1).join(' ');
1380
+ if (!message.trim())
1381
+ throw new Error('Usage: coauthor log add <projectId> --message "..." [--kind decision|assumption|question]');
1382
+ const kind = getString(input.values, 'kind');
1383
+ const data = await client.request({ method: 'POST', path, body: { message, ...(kind ? { kind } : {}) } });
1384
+ return { ok: true, message: 'Logged.', data };
1385
+ }
1386
+ throw new Error('Usage: coauthor log <add|show> <projectId>');
1387
+ }
1300
1388
  function enrichResearchStatus(data) {
1301
1389
  if (!data || typeof data !== 'object' || Array.isArray(data))
1302
1390
  return data;
@@ -1476,8 +1564,10 @@ export function helpResult(command = []) {
1476
1564
  ' workspace show',
1477
1565
  ' chat [show|list]',
1478
1566
  ' contract show|save|approve',
1479
- ' outline show|generate|save|approve',
1480
- ' research-plan show|generate|save|approve',
1567
+ ' outline show|generate|revise|save|approve',
1568
+ ' research-plan show|generate|revise|save|approve',
1569
+ ' brief review|answer',
1570
+ ' log add|show',
1481
1571
  ' research run|status|structured',
1482
1572
  ' draft generate|status|get|save|revise',
1483
1573
  ' draft revision show|apply|discard',
@@ -1555,21 +1645,36 @@ function commandHelp(command) {
1555
1645
  '',
1556
1646
  'create: --title, --topic, --audience, --contract <json|@file>. list: --limit. show: one project.',
1557
1647
  ].join('\n'),
1648
+ brief: [
1649
+ 'Usage: coauthor brief review <project-id> [--json]',
1650
+ ' coauthor brief answer <project-id> --data @answers.json [--force] [--json]',
1651
+ '',
1652
+ 'review: CoAuthor critiques the brief and returns data.verdict, concerns, and questions (each with why, the field it changes, and answerable_by agent|human). Nothing is saved.',
1653
+ 'answer: {"answers":[{"question","answer","source":"agent|user|assumption"}], "apply_suggested_patch"?: {...}}. CoAuthor folds them into the brief and returns changed_fields. The brief is saved, not approved.',
1654
+ ].join('\n'),
1655
+ log: [
1656
+ 'Usage: coauthor log add <project-id> --message "..." [--kind decision|assumption|question] [--json]',
1657
+ ' coauthor log show <project-id> [--json]',
1658
+ '',
1659
+ 'A decision log the user also sees in the project workspace in the web app.',
1660
+ ].join('\n'),
1558
1661
  contract: [
1559
1662
  'Usage: coauthor contract <show|save|approve> <project-id> [--data <json|@file>] [--json]',
1560
1663
  '',
1561
1664
  'save replaces the brief ({"contract":{...}}); approve approves the saved brief. To have CoAuthor review it: coauthor workflow run <project-id> --target contract --briefing-mode strict --json',
1562
1665
  ].join('\n'),
1563
1666
  outline: [
1564
- 'Usage: coauthor outline <show|generate|save|approve> <project-id> [--data <json|@file>] [--planning-model <id>] [--json]',
1667
+ 'Usage: coauthor outline <show|generate|revise|save|approve> <project-id> [--feedback "..."] [--data <json|@file>] [--planning-model <id>] [--json]',
1565
1668
  '',
1566
1669
  'generate creates an outline without approving it (data.sections). show returns the saved outline (data.artifact).',
1670
+ 'revise --feedback: CoAuthor rewrites the outline from your feedback, saves it (not approved), and returns data.diff.',
1567
1671
  'save replaces it with the complete list {"sections":[...]}; omitted sections are removed. approve approves the saved outline.',
1568
1672
  ].join('\n'),
1569
1673
  'research-plan': [
1570
- 'Usage: coauthor research-plan <show|generate|save|approve> <project-id> [--data <json|@file>] [--planning-model <id>] [--json]',
1674
+ 'Usage: coauthor research-plan <show|generate|revise|save|approve> <project-id> [--feedback "..."] [--data <json|@file>] [--planning-model <id>] [--json]',
1571
1675
  '',
1572
1676
  'generate requires an approved outline (data.research_tasks). show returns the saved plan (data.artifact).',
1677
+ 'revise --feedback: CoAuthor rewrites the plan from your feedback (add sources, change depth), saves it (not approved), and returns data.diff.',
1573
1678
  'save replaces it with {"research_tasks":[...]}; approve approves the saved plan.',
1574
1679
  ].join('\n'),
1575
1680
  research: [
package/dist/parser.js CHANGED
@@ -66,6 +66,8 @@ const OPTIONS = {
66
66
  'image-generation-model': { type: 'string' },
67
67
  instruction: { type: 'string' },
68
68
  scope: { type: 'string' },
69
+ feedback: { type: 'string' },
70
+ kind: { type: 'string' },
69
71
  apply: { type: 'boolean', default: false },
70
72
  accept: { type: 'string' },
71
73
  reject: { type: 'string' },
@@ -142,6 +144,10 @@ function commandLength(positionals) {
142
144
  return second === 'show' ? 2 : 1;
143
145
  if (first === 'chat')
144
146
  return second && ['show', 'list'].includes(second) ? 2 : 1;
147
+ if (first === 'brief')
148
+ return second && ['review', 'answer'].includes(second) ? 2 : 1;
149
+ if (first === 'log')
150
+ return second && ['add', 'show'].includes(second) ? 2 : 1;
145
151
  if (first === 'skills')
146
152
  return second && ['list', 'install'].includes(second) ? 2 : 1;
147
153
  if (first === 'models')
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.23",
3
+ "version": "0.0.24",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -30,20 +30,21 @@ Typical timing: brief and outline under a minute; research and draft 3–10 minu
30
30
 
31
31
  1. **Brief.** Gather topic, audience, angle, core promise, length, must-include points, and sources from the conversation and your context (the repo, docs, the user's site). Ask the user only what you cannot infer, in one message of at most 2–3 questions. Write the contract to a file (schema, field guide, and examples: `references/brief-and-contract.md`), then:
32
32
  `coauthor project create --title "..." --contract @brief.json --json` → `data.project.id`
33
- 2. **Brief review.** `coauthor workflow run <id> --target contract --briefing-mode strict --json`. `status: "completed"` with no questions means the brief passed and is now approved. If `status` is `needs_clarification`, answer `data.clarification_questions` from your context, update the file, `coauthor contract save <id> --data @brief.json --json`, and run again. For a deeper interview, let CoAuthor question you: `coauthor chat <id> --stage contract --message "Interview me about this brief before we outline." --json`, read `data.text`, and reply the same way. Pass to the user only questions about their opinions, business facts, numbers, or risk tolerance.
34
- 3. **Outline checkpoint.** `coauthor outline generate <id> --json` (this does not approve it; sections are in `data.sections`). Review it against the brief: every section serves the core promise, must-includes are covered, the order builds, nothing is generic or repeated. To change it, ask CoAuthor (`coauthor chat <id> --stage outline --message "Merge sections 3 and 4; replace the conclusion with a checklist." --json`) or save the complete edited list (`coauthor outline save <id> --data @outline.json --json` with `{"sections":[...]}`; omitted sections are removed). **Chat summaries can be wrong: after every chat edit, re-read with `coauthor outline show <id> --json` (sections are in `data.artifact`) and fix anything that didn't land with `outline save`.** Then `coauthor outline approve <id> --json`. If the user asked to see the outline, show it to them here and wait.
35
- 4. **Research-plan checkpoint.** `coauthor research-plan generate <id> --json` (tasks in `data.research_tasks`; `research-plan show` returns them in `data.artifact`). Check every section has a task and every claim that needs proof points at the right sources, including URLs the user gave you. Adjust with `chat --stage research-plan` (then re-read) or `research-plan save` with `{"research_tasks":[...]}`, then `coauthor research-plan approve <id> --json`.
33
+ 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`.
34
+ 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.
35
+ 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.
36
36
  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`.
37
37
  6. **Quality pass.** `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.
38
38
  7. **Images.** `coauthor image list <id> --json`, then for each placeholder `coauthor image generate <id> --placeholder-id <placeholder id> --json` (the `id` UUID, not `placeholder_id`), then poll `coauthor image status <id> --json` until none are generating. CoAuthor decides how many images a draft gets, sometimes only the featured image; the CLI can't add more, so tell the user if they expected several. Open each image and check it does not state numbers or claims the article does not make, then rewrite its alt text to match what is actually visible (the stored alt text describes the plan, not the result). See `references/images-and-social.md`.
39
39
  8. **Edits.** For prose changes: `coauthor draft revise <id> --instruction "..." --wait --json` (be specific: name the section and give a number, such as "cut the intro to under 60 words"), review each group's `before_markdown` and `after_markdown`, then `coauthor draft revision apply <id> <revision-id> --json` (optionally `--accept` or `--reject` with ids copied from `data.groups[].id`) or `coauthor draft revision discard <id> <revision-id> --json`. For exact text you already have, edit the document JSON and `draft save`. See `references/editing-drafts.md`.
40
- 9. **Deliver.** Give the user the final markdown (or `--format html`), a short decision log (what you approved, what you asked CoAuthor to change, what you assumed), and the credits used (`coauthor credits <id> --json`). With their yes: share link, WordPress export, or X thread (`references/publishing-and-export.md`).
40
+ 9. **Deliver.** Give the user the final markdown (or `--format html`), the decision log (`coauthor log show <id> --json`: what you approved, what you asked CoAuthor to change, what you assumed), and the credits used (`coauthor credits <id> --json`). The user also sees the log in the project's workspace in the web app. With their yes: share link, WordPress export, or X thread (`references/publishing-and-export.md`).
41
41
 
42
42
  ## When something stops
43
43
 
44
44
  | Status or code | What to do |
45
45
  | --- | --- |
46
- | `needs_clarification` | Answer `data.clarification_questions`, update the contract, run again. |
46
+ | `needs_clarification` | Answer `data.clarification_questions`, update the contract, run again. (Prefer `brief review` / `brief answer`.) |
47
+ | `draft_exists`, `downstream_exists` | A later stage already depends on this one. Edit the draft instead; pass `--force` only if the user wants to restart from here. |
47
48
  | `timed_out`, `still_running` | Run the resume or show command in the output. Do not restart the step. |
48
49
  | `research_structuring` | Normal after research. Keep waiting or resume toward draft. |
49
50
  | `research_running_stale` | Research progress stopped for 30+ minutes. Show the user `coauthor research structured <id> --json` and ask before `coauthor workflow rewind <id> --target research --json`, which discards research done so far. |
@@ -18,6 +18,9 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
18
18
  | `byok_not_allowed` | The plan can't use provider keys. | Wait for the credit reset, or the user upgrades in CoAuthor. |
19
19
  | `coauthor_access_required` | No active CoAuthor subscription on this account. | Tell the user. `coauthor auth status` still works. |
20
20
  | `entitlement_sync_unavailable` | Subscription status couldn't be checked right now. | Don't retry in a loop. Try again in a few minutes. |
21
+ | `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). |
22
+ | `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. |
23
+ | `revision_invalid` | CoAuthor's revision referenced sections that don't exist. | Run `revise` again with feedback that names sections by their current headings. |
21
24
  | `stale_draft` | The draft changed after you read it. | Re-read with `draft get`, reapply your edit, save. |
22
25
  | `user_recently_editing` | The user saved in the browser in the last 90 seconds. | Wait, or ask them. `--force` only with their OK. |
23
26
  | `review_pending`, `document_locked` | An AI review or edit is in progress in the editor. | Wait, or apply or discard it. |
@@ -32,20 +32,21 @@ Typical timing: brief and outline under a minute; research and draft 3–10 minu
32
32
 
33
33
  1. **Brief.** Gather topic, audience, angle, core promise, length, must-include points, and sources from the conversation and your context (the repo, docs, the user's site). Ask the user only what you cannot infer, in one message of at most 2–3 questions. Write the contract to a file (schema, field guide, and examples: `references/brief-and-contract.md`), then:
34
34
  `coauthor project create --title "..." --contract @brief.json --json` → `data.project.id`
35
- 2. **Brief review.** `coauthor workflow run <id> --target contract --briefing-mode strict --json`. `status: "completed"` with no questions means the brief passed and is now approved. If `status` is `needs_clarification`, answer `data.clarification_questions` from your context, update the file, `coauthor contract save <id> --data @brief.json --json`, and run again. For a deeper interview, let CoAuthor question you: `coauthor chat <id> --stage contract --message "Interview me about this brief before we outline." --json`, read `data.text`, and reply the same way. Pass to the user only questions about their opinions, business facts, numbers, or risk tolerance.
36
- 3. **Outline checkpoint.** `coauthor outline generate <id> --json` (this does not approve it; sections are in `data.sections`). Review it against the brief: every section serves the core promise, must-includes are covered, the order builds, nothing is generic or repeated. To change it, ask CoAuthor (`coauthor chat <id> --stage outline --message "Merge sections 3 and 4; replace the conclusion with a checklist." --json`) or save the complete edited list (`coauthor outline save <id> --data @outline.json --json` with `{"sections":[...]}`; omitted sections are removed). **Chat summaries can be wrong: after every chat edit, re-read with `coauthor outline show <id> --json` (sections are in `data.artifact`) and fix anything that didn't land with `outline save`.** Then `coauthor outline approve <id> --json`. If the user asked to see the outline, show it to them here and wait.
37
- 4. **Research-plan checkpoint.** `coauthor research-plan generate <id> --json` (tasks in `data.research_tasks`; `research-plan show` returns them in `data.artifact`). Check every section has a task and every claim that needs proof points at the right sources, including URLs the user gave you. Adjust with `chat --stage research-plan` (then re-read) or `research-plan save` with `{"research_tasks":[...]}`, then `coauthor research-plan approve <id> --json`.
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.
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 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.
40
40
  7. **Images.** `coauthor image list <id> --json`, then for each placeholder `coauthor image generate <id> --placeholder-id <placeholder id> --json` (the `id` UUID, not `placeholder_id`), then poll `coauthor image status <id> --json` until none are generating. CoAuthor decides how many images a draft gets, sometimes only the featured image; the CLI can't add more, so tell the user if they expected several. Open each image and check it does not state numbers or claims the article does not make, then rewrite its alt text to match what is actually visible (the stored alt text describes the plan, not the result). See `references/images-and-social.md`.
41
41
  8. **Edits.** For prose changes: `coauthor draft revise <id> --instruction "..." --wait --json` (be specific: name the section and give a number, such as "cut the intro to under 60 words"), review each group's `before_markdown` and `after_markdown`, then `coauthor draft revision apply <id> <revision-id> --json` (optionally `--accept` or `--reject` with ids copied from `data.groups[].id`) or `coauthor draft revision discard <id> <revision-id> --json`. For exact text you already have, edit the document JSON and `draft save`. See `references/editing-drafts.md`.
42
- 9. **Deliver.** Give the user the final markdown (or `--format html`), a short decision log (what you approved, what you asked CoAuthor to change, what you assumed), and the credits used (`coauthor credits <id> --json`). With their yes: share link, WordPress export, or X thread (`references/publishing-and-export.md`).
42
+ 9. **Deliver.** Give the user the final markdown (or `--format html`), the decision log (`coauthor log show <id> --json`: what you approved, what you asked CoAuthor to change, what you assumed), and the credits used (`coauthor credits <id> --json`). The user also sees the log in the project's workspace in the web app. With their yes: share link, WordPress export, or X thread (`references/publishing-and-export.md`).
43
43
 
44
44
  ## When something stops
45
45
 
46
46
  | Status or code | What to do |
47
47
  | --- | --- |
48
- | `needs_clarification` | Answer `data.clarification_questions`, update the contract, run again. |
48
+ | `needs_clarification` | Answer `data.clarification_questions`, update the contract, run again. (Prefer `brief review` / `brief answer`.) |
49
+ | `draft_exists`, `downstream_exists` | A later stage already depends on this one. Edit the draft instead; pass `--force` only if the user wants to restart from here. |
49
50
  | `timed_out`, `still_running` | Run the resume or show command in the output. Do not restart the step. |
50
51
  | `research_structuring` | Normal after research. Keep waiting or resume toward draft. |
51
52
  | `research_running_stale` | Research progress stopped for 30+ minutes. Show the user `coauthor research structured <id> --json` and ask before `coauthor workflow rewind <id> --target research --json`, which discards research done so far. |
@@ -405,6 +406,9 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
405
406
  | `byok_not_allowed` | The plan can't use provider keys. | Wait for the credit reset, or the user upgrades in CoAuthor. |
406
407
  | `coauthor_access_required` | No active CoAuthor subscription on this account. | Tell the user. `coauthor auth status` still works. |
407
408
  | `entitlement_sync_unavailable` | Subscription status couldn't be checked right now. | Don't retry in a loop. Try again in a few minutes. |
409
+ | `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). |
410
+ | `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. |
411
+ | `revision_invalid` | CoAuthor's revision referenced sections that don't exist. | Run `revise` again with feedback that names sections by their current headings. |
408
412
  | `stale_draft` | The draft changed after you read it. | Re-read with `draft get`, reapply your edit, save. |
409
413
  | `user_recently_editing` | The user saved in the browser in the last 90 seconds. | Wait, or ask them. `--force` only with their OK. |
410
414
  | `review_pending`, `document_locked` | An AI review or edit is in progress in the editor. | Wait, or apply or discard it. |