@clickminded/coauthor-cli 0.0.9 → 0.0.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -148,7 +148,7 @@ Images and threads:
148
148
 
149
149
  ```sh
150
150
  coauthor image list <project-id> --json
151
- coauthor image generate <project-id> --prompt "..." --json
151
+ coauthor image generate <project-id> --placeholder-id <placeholder-id> --prompt "..." --json
152
152
  coauthor thread generate <project-id> --json
153
153
  coauthor thread save <project-id> --data '{"posts":[]}' --json
154
154
  ```
@@ -189,6 +189,8 @@ Agents should:
189
189
  - Use `--json` on every command they need to parse.
190
190
  - Use `--wait` when starting long-running research or draft jobs and the user expects completion.
191
191
  - Treat `status: "requires_key"` as a recoverable pause, not a failed workflow. Tell the user to add keys in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
192
+ - Treat `status: "research_running_stale"` or `data.diagnostic.code: "research_running_stale"` as a stale research run. Inspect `coauthor research structured <project-id> --json` and use the returned next commands instead of retrying blindly.
193
+ - Treat `status: "research_structuring"` or `data.diagnostic.code: "research_structuring"` as a normal transition after raw research completes. Wait for `project_state: "research_structured"` before generating a draft; do not rewind for this state.
192
194
  - Use `coauthor credits <project-id> --json` to inspect credit allowance, pending holds, and remaining credits.
193
195
  - Avoid retrying publish/export after uncertain network failures.
194
196
  - Use `coauthor operation status <operation-key>` after uncertainty.
@@ -221,6 +223,10 @@ The CLI talks to `/api/agent/v1/*`. Treat this as a public beta API surface:
221
223
 
222
224
  `requires_key` means included credits are exhausted and no usable provider key is configured for the requested capability. The task is paused when possible. Open AI settings in the web app, add the required key, then run `coauthor workflow resume <project-id> --wait --json`.
223
225
 
226
+ `research_running_stale` means a research run is still marked running beyond the expected progress window. Inspect `coauthor research structured <project-id> --json`; if it only contains empty section shells, rewind research or report the stale run instead of repeatedly resuming.
227
+
228
+ Image generation requires an existing image placeholder. Run `coauthor image list <project-id> --json` after draft generation and pass the placeholder id to `coauthor image generate <project-id> --placeholder-id <placeholder-id> --json`.
229
+
224
230
  If `npx @clickminded/coauthor-cli help` fails while you are inside the CLI package source directory, run it from another directory or use:
225
231
 
226
232
  ```sh
@@ -9,4 +9,4 @@ export type CommandContext = {
9
9
  token: string;
10
10
  };
11
11
  export declare function runCommand(input: ParsedCommand, context: CommandContext): Promise<CommandResult>;
12
- export declare function helpResult(): CommandResult;
12
+ export declare function helpResult(command?: string[]): CommandResult;
package/dist/commands.js CHANGED
@@ -632,10 +632,11 @@ function openBrowser(url) {
632
632
  child.unref();
633
633
  }
634
634
  async function waitForResearch(client, projectId, initialData) {
635
- const deadline = Date.now() + 20 * 60_000;
635
+ const deadline = Date.now() + waitTimeoutMs(20 * 60_000);
636
+ const pollMs = waitPollMs();
636
637
  let latest = initialData;
637
638
  while (Date.now() < deadline) {
638
- await sleep(3000);
639
+ await sleep(pollMs);
639
640
  latest = await client.request({ path: `projects/${encodeURIComponent(projectId)}/research/status` });
640
641
  const status = extractNestedString(latest, ['run', 'status']);
641
642
  if (status === 'succeeded')
@@ -645,14 +646,18 @@ async function waitForResearch(client, projectId, initialData) {
645
646
  if (status === 'paused_requires_key') {
646
647
  return requiresKeyPauseResult(projectId, 'research', extractNestedString(latest, ['run', 'error_message']) ?? 'Research paused: add the required API key to continue.', latest);
647
648
  }
649
+ const stale = researchRunningStaleResult(projectId, latest, null, initialData);
650
+ if (stale)
651
+ return stale;
648
652
  }
649
- return { ok: true, message: 'Timed out waiting for research; check status with coauthor research status', data: latest };
653
+ return waitTimedOutResult(projectId, 'research', initialData, latest, null);
650
654
  }
651
655
  async function waitForDraft(client, projectId, initialData) {
652
- const deadline = Date.now() + 20 * 60_000;
656
+ const deadline = Date.now() + waitTimeoutMs(20 * 60_000);
657
+ const pollMs = waitPollMs();
653
658
  let latest = initialData;
654
659
  while (Date.now() < deadline) {
655
- await sleep(3000);
660
+ await sleep(pollMs);
656
661
  latest = await client.request({ path: `projects/${encodeURIComponent(projectId)}/draft/status` });
657
662
  const state = getResponseString(latest, 'project_state');
658
663
  const phase = getResponseString(latest, 'phase');
@@ -664,19 +669,17 @@ async function waitForDraft(client, projectId, initialData) {
664
669
  if (phase === 'failed')
665
670
  throw new Error(getResponseString(latest, 'message') ?? 'Draft generation failed');
666
671
  }
667
- return { ok: true, message: 'Timed out waiting for draft; check status with coauthor draft status', data: latest };
672
+ return waitTimedOutResult(projectId, 'draft', initialData, null, latest);
668
673
  }
669
674
  async function waitForWorkflowDraft(client, projectId, initialData) {
670
- const deadline = Date.now() + 40 * 60_000;
675
+ const deadline = Date.now() + waitTimeoutMs(40 * 60_000);
676
+ const pollMs = waitPollMs();
671
677
  let latestDraft = initialData;
672
678
  let latestResearch = null;
673
679
  let draftGenerate = null;
674
680
  let attemptedDraftStart = false;
675
- if (workflowIndicatesBackgroundResearch(initialData)) {
676
- return researchRunningWorkflowResult(projectId, initialData, null, null);
677
- }
678
681
  while (Date.now() < deadline) {
679
- await sleep(3000);
682
+ await sleep(pollMs);
680
683
  latestDraft = await client.request({ path: `projects/${encodeURIComponent(projectId)}/draft/status` });
681
684
  const draftState = getResponseString(latestDraft, 'project_state');
682
685
  const draftPhase = getResponseString(latestDraft, 'phase');
@@ -713,6 +716,9 @@ async function waitForWorkflowDraft(client, projectId, initialData) {
713
716
  draft_status: latestDraft,
714
717
  });
715
718
  }
719
+ const stale = researchRunningStaleResult(projectId, latestResearch, latestDraft, initialData);
720
+ if (stale)
721
+ return stale;
716
722
  if (!attemptedDraftStart
717
723
  && (researchStatus === 'succeeded' || isResearchReadyForDraft(draftState))
718
724
  && draftPhase !== 'queued'
@@ -731,13 +737,73 @@ async function waitForWorkflowDraft(client, projectId, initialData) {
731
737
  }
732
738
  }
733
739
  }
740
+ return waitTimedOutResult(projectId, 'workflow draft target', initialData, latestResearch, latestDraft);
741
+ }
742
+ function waitPollMs() {
743
+ const raw = Number(process.env.COAUTHOR_CLI_WAIT_POLL_MS);
744
+ return Number.isFinite(raw) && raw >= 0 ? raw : 3000;
745
+ }
746
+ function waitTimeoutMs(defaultMs) {
747
+ const raw = Number(process.env.COAUTHOR_CLI_WAIT_TIMEOUT_MS);
748
+ return Number.isFinite(raw) && raw > 0 ? raw : defaultMs;
749
+ }
750
+ function researchStaleMs() {
751
+ const raw = Number(process.env.COAUTHOR_CLI_RESEARCH_STALE_MS);
752
+ return Number.isFinite(raw) && raw > 0 ? raw : 10 * 60_000;
753
+ }
754
+ function researchRunAgeMs(data) {
755
+ const timestamp = extractNestedString(data, ['run', 'updated_at'])
756
+ ?? extractNestedString(data, ['run', 'created_at']);
757
+ if (!timestamp)
758
+ return null;
759
+ const time = Date.parse(timestamp);
760
+ if (!Number.isFinite(time))
761
+ return null;
762
+ return Date.now() - time;
763
+ }
764
+ function isResearchRunningStale(data) {
765
+ if (extractNestedString(data, ['run', 'status']) !== 'running')
766
+ return false;
767
+ if (getResponseString(data, 'project_state') !== 'research_running')
768
+ return false;
769
+ const ageMs = researchRunAgeMs(data);
770
+ return typeof ageMs === 'number' && ageMs >= researchStaleMs();
771
+ }
772
+ function researchRunningStaleResult(projectId, researchStatus, draftStatus, workflow) {
773
+ if (!isResearchRunningStale(researchStatus))
774
+ return null;
734
775
  return {
735
- ok: true,
736
- message: 'Timed out waiting for workflow draft target; check status with coauthor draft status',
776
+ ok: false,
777
+ status: 'research_running_stale',
778
+ exitCode: 2,
779
+ message: 'Research is still marked running and has not reported a terminal state within the expected window.',
737
780
  data: {
738
- workflow: initialData,
739
- research_status: latestResearch,
740
- draft_status: latestDraft,
781
+ workflow,
782
+ research_status: enrichResearchStatus(researchStatus),
783
+ draft_status: draftStatus,
784
+ next_commands: [
785
+ `coauthor research status ${projectId} --json`,
786
+ `coauthor research structured ${projectId} --json`,
787
+ `coauthor workflow rewind ${projectId} --target research --json`,
788
+ ],
789
+ },
790
+ };
791
+ }
792
+ function waitTimedOutResult(projectId, target, workflow, researchStatus, draftStatus) {
793
+ return {
794
+ ok: false,
795
+ status: 'timed_out',
796
+ exitCode: 2,
797
+ message: `Timed out waiting for ${target}; check status before retrying.`,
798
+ data: {
799
+ workflow,
800
+ research_status: researchStatus,
801
+ draft_status: draftStatus,
802
+ next_commands: [
803
+ `coauthor research status ${projectId} --json`,
804
+ `coauthor draft status ${projectId} --json`,
805
+ `coauthor workflow resume ${projectId} --target draft --wait --json`,
806
+ ],
741
807
  },
742
808
  };
743
809
  }
@@ -790,8 +856,38 @@ function enrichResearchStatus(data) {
790
856
  return data;
791
857
  const runStatus = extractNestedString(data, ['run', 'status']);
792
858
  const projectState = getResponseString(data, 'project_state');
793
- if (runStatus !== 'running' || projectState === 'research_running')
859
+ if (runStatus !== 'running')
860
+ return data;
861
+ if (isResearchRunningStale(data)) {
862
+ return {
863
+ ...data,
864
+ diagnostic: {
865
+ code: 'research_running_stale',
866
+ message: 'Research is still marked running and has not reported a terminal state within the expected window. Inspect structured output before deciding whether to rewind.',
867
+ next_commands: [
868
+ 'coauthor research status <project-id> --json',
869
+ 'coauthor research structured <project-id> --json',
870
+ 'coauthor workflow rewind <project-id> --target research --json',
871
+ ],
872
+ },
873
+ };
874
+ }
875
+ if (projectState === 'research_running')
794
876
  return data;
877
+ if (projectState === 'research_complete') {
878
+ return {
879
+ ...data,
880
+ diagnostic: {
881
+ code: 'research_structuring',
882
+ message: 'Raw research is complete and the worker is structuring the results. Keep waiting until project_state is "research_structured"; do not rewind for this transition.',
883
+ next_commands: [
884
+ 'coauthor research status <project-id> --json',
885
+ 'coauthor draft status <project-id> --json',
886
+ 'coauthor workflow resume <project-id> --target draft --wait --json',
887
+ ],
888
+ },
889
+ };
890
+ }
795
891
  return {
796
892
  ...data,
797
893
  diagnostic: {
@@ -805,29 +901,6 @@ function enrichResearchStatus(data) {
805
901
  },
806
902
  };
807
903
  }
808
- function workflowIndicatesBackgroundResearch(data) {
809
- if (!data || typeof data !== 'object' || Array.isArray(data))
810
- return false;
811
- return getResponseString(data, 'project_state') === 'research_running'
812
- || getResponseString(data, 'status') === 'research_running';
813
- }
814
- function researchRunningWorkflowResult(projectId, workflow, researchStatus, draftStatus) {
815
- return {
816
- ok: true,
817
- status: 'research_running',
818
- message: 'Research is running in the background. Draft generation has not started yet.',
819
- data: {
820
- workflow,
821
- research_status: researchStatus,
822
- draft_status: draftStatus,
823
- next_commands: [
824
- `coauthor research status ${projectId} --json`,
825
- `coauthor workflow resume ${projectId} --target draft --wait --json`,
826
- `coauthor workflow rewind ${projectId} --target research --json`,
827
- ],
828
- },
829
- };
830
- }
831
904
  function requiresKeyPauseResult(projectId, target, message, data) {
832
905
  const resumeCommand = `coauthor workflow resume ${projectId} --target ${target} --wait --json`;
833
906
  return {
@@ -895,10 +968,11 @@ function resourceCommandName(resource) {
895
968
  return 'operation';
896
969
  return resource;
897
970
  }
898
- export function helpResult() {
971
+ export function helpResult(command = []) {
972
+ const scoped = commandHelp(command);
899
973
  return {
900
974
  ok: true,
901
- message: [
975
+ message: scoped ?? [
902
976
  'Usage: coauthor <command> [options]',
903
977
  '',
904
978
  'Commands:',
@@ -925,3 +999,44 @@ export function helpResult() {
925
999
  ].join('\n'),
926
1000
  };
927
1001
  }
1002
+ function commandHelp(command) {
1003
+ const key = command.join(' ');
1004
+ const help = {
1005
+ 'project create': [
1006
+ 'Usage: coauthor project create [--title <title>] [--topic <brief>] [--audience <audience>] [--json]',
1007
+ '',
1008
+ 'Creates a project. When --topic or --audience is provided, CoAuthor seeds the saved contract so workflow briefing review can use that context.',
1009
+ ].join('\n'),
1010
+ 'workflow run': [
1011
+ 'Usage: coauthor workflow run <project-id> --target <outline|research|draft> [--wait] [--briefing-mode auto|strict|off] [--json]',
1012
+ '',
1013
+ '--wait blocks until the requested target completes, pauses for a key, fails, reports stale research, or times out.',
1014
+ ].join('\n'),
1015
+ 'workflow resume': [
1016
+ 'Usage: coauthor workflow resume <project-id> [--target <research|draft>] [--wait] [--json]',
1017
+ '',
1018
+ 'Use after an interruption, timeout, or requires_key pause. For draft targets, --wait continues through research and draft generation.',
1019
+ ].join('\n'),
1020
+ 'draft generate': [
1021
+ 'Usage: coauthor draft generate <project-id> [--wait] [--json]',
1022
+ '',
1023
+ 'Requires project_state "research_structured". If research is still running or structuring, inspect the returned status and next commands.',
1024
+ ].join('\n'),
1025
+ 'draft get': [
1026
+ 'Usage: coauthor draft get <project-id> [--format json|markdown|html|text] [--json]',
1027
+ '',
1028
+ 'Retrieves a saved generated draft. Chat responses are available through coauthor chat show.',
1029
+ ].join('\n'),
1030
+ 'draft save': [
1031
+ 'Usage: coauthor draft save <project-id> --data \'<json>\' [--json]',
1032
+ '',
1033
+ 'Saves a draft document payload through the agent API.',
1034
+ ].join('\n'),
1035
+ 'image generate': [
1036
+ 'Usage: coauthor image generate <project-id> --placeholder-id <placeholder-id> [--prompt "..."] [--json]',
1037
+ '',
1038
+ 'Image generation requires an image placeholder from coauthor image list. Draft generation creates placeholders.',
1039
+ ].join('\n'),
1040
+ };
1041
+ return help[key] ?? null;
1042
+ }
package/dist/index.js CHANGED
@@ -11,7 +11,7 @@ export async function main(argv = process.argv.slice(2)) {
11
11
  try {
12
12
  const parsed = parseCliArgs(argv);
13
13
  if (parsed.globals.help) {
14
- process.stdout.write(renderResult(helpResult(), parsed.globals.json));
14
+ process.stdout.write(renderResult(helpResult(parsed.command), parsed.globals.json));
15
15
  return 0;
16
16
  }
17
17
  const runtimeConfig = await resolveRuntimeConfig({
@@ -41,26 +41,44 @@ function formatCliError(error, baseUrl, argv = []) {
41
41
  if (requiresKey)
42
42
  return { error: new Error(requiresKey.message), result: requiresKey, exitCode: 2 };
43
43
  const message = extractErrorMessage(error.responseBody) ?? error.message;
44
- const researchBlock = formatResearchRunningDraftBlock(message, argv);
44
+ const researchBlock = formatResearchDraftBlock(message, argv);
45
45
  if (researchBlock)
46
46
  return { error: new Error(researchBlock.message), result: researchBlock, exitCode: 2 };
47
47
  return { error: new Error(message), exitCode: 1 };
48
48
  }
49
49
  return { error: error instanceof Error ? error : new Error(String(error)), exitCode: 1 };
50
50
  }
51
- function formatResearchRunningDraftBlock(message, argv) {
52
- if (!/Cannot generate draft in state "research_running"/i.test(message))
51
+ function formatResearchDraftBlock(message, argv) {
52
+ const stateMatch = /Cannot generate draft in state "(research_running|research_complete)"/i.exec(message);
53
+ if (!stateMatch)
53
54
  return null;
55
+ const state = stateMatch[1]?.toLowerCase();
54
56
  const projectId = resolveProjectIdFromArgv(argv);
57
+ const statusCommand = projectId ? `coauthor research status ${projectId} --json` : 'coauthor research status <project-id> --json';
58
+ const resumeCommand = projectId
59
+ ? `coauthor workflow resume ${projectId} --target draft --wait --json`
60
+ : 'coauthor workflow resume <project-id> --target draft --wait --json';
61
+ if (state === 'research_complete') {
62
+ return {
63
+ ok: false,
64
+ status: 'research_structuring',
65
+ message: `${message}\nResearch is complete and the results are being structured. Wait for project_state "research_structured" before generating a draft.`,
66
+ next_commands: [
67
+ statusCommand,
68
+ resumeCommand,
69
+ ],
70
+ exitCode: 2,
71
+ };
72
+ }
55
73
  const recoveryCommands = projectId
56
74
  ? [
57
- `coauthor research status ${projectId} --json`,
58
- `coauthor workflow resume ${projectId} --target draft --wait --json`,
75
+ statusCommand,
76
+ resumeCommand,
59
77
  `coauthor workflow rewind ${projectId} --target research --json`,
60
78
  ]
61
79
  : [
62
- 'coauthor research status <project-id> --json',
63
- 'coauthor workflow resume <project-id> --target draft --wait --json',
80
+ statusCommand,
81
+ resumeCommand,
64
82
  'coauthor workflow rewind <project-id> --target research --json',
65
83
  ];
66
84
  return {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.9",
3
+ "version": "0.0.11",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -16,7 +16,11 @@ This skill guides agent use of the CoAuthor CLI.
16
16
  - Let the default bounded briefing review run before outline/draft generation. Use `--briefing-mode strict` when the user explicitly wants a stronger brief gate, and answer or relay `data.clarification_questions` if the CLI returns `status: "needs_clarification"`.
17
17
  - Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable pause. Do not retry in a loop; tell the user to add the required provider key in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
18
18
  - Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
19
+ - Treat `status: "research_running_stale"` or `data.diagnostic.code: "research_running_stale"` as a stale research run. Inspect `coauthor research structured <project-id> --json` and use the returned next commands instead of retrying blindly.
20
+ - Treat `status: "research_structuring"` or `data.diagnostic.code: "research_structuring"` as a normal transition after raw research completes. Keep waiting or resume toward draft; do not rewind or generate a draft until project state reaches `research_structured`.
19
21
  - If `coauthor research status <project-id> --json` returns `data.diagnostic.code: "research_run_state_mismatch"`, report the mismatch and use the returned recovery commands.
22
+ - `coauthor workflow run <project-id> --target draft --wait` should not be treated as complete until the CLI reports draft completion, a key pause, terminal failure, `research_running_stale`, or `timed_out`.
23
+ - For images, run `coauthor image list <project-id> --json` and pass an existing placeholder with `coauthor image generate <project-id> --placeholder-id <placeholder-id> --json`. Draft generation creates placeholders.
20
24
  - Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
21
25
  - After a timeout, interruption, network error, or unclear result, check operation status before retrying.
22
26
  - `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
@@ -16,7 +16,11 @@ This skill guides agent use of the CoAuthor CLI.
16
16
  - Let the default bounded briefing review run before outline/draft generation. Use `--briefing-mode strict` when the user explicitly wants a stronger brief gate, and answer or relay `data.clarification_questions` if the CLI returns `status: "needs_clarification"`.
17
17
  - Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable pause. Do not retry in a loop; tell the user to add the required provider key in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
18
18
  - Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
19
+ - Treat `status: "research_running_stale"` or `data.diagnostic.code: "research_running_stale"` as a stale research run. Inspect `coauthor research structured <project-id> --json` and use the returned next commands instead of retrying blindly.
20
+ - Treat `status: "research_structuring"` or `data.diagnostic.code: "research_structuring"` as a normal transition after raw research completes. Keep waiting or resume toward draft; do not rewind or generate a draft until project state reaches `research_structured`.
19
21
  - If `coauthor research status <project-id> --json` returns `data.diagnostic.code: "research_run_state_mismatch"`, report the mismatch and use the returned recovery commands.
22
+ - `coauthor workflow run <project-id> --target draft --wait` should not be treated as complete until the CLI reports draft completion, a key pause, terminal failure, `research_running_stale`, or `timed_out`.
23
+ - For images, run `coauthor image list <project-id> --json` and pass an existing placeholder with `coauthor image generate <project-id> --placeholder-id <placeholder-id> --json`. Draft generation creates placeholders.
20
24
  - Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
21
25
  - After a timeout, interruption, network error, or unclear result, check operation status before retrying.
22
26
  - `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
@@ -16,7 +16,11 @@ This skill guides agent use of the CoAuthor CLI.
16
16
  - Let the default bounded briefing review run before outline/draft generation. Use `--briefing-mode strict` when the user explicitly wants a stronger brief gate, and answer or relay `data.clarification_questions` if the CLI returns `status: "needs_clarification"`.
17
17
  - Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable pause. Do not retry in a loop; tell the user to add the required provider key in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
18
18
  - Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
19
+ - Treat `status: "research_running_stale"` or `data.diagnostic.code: "research_running_stale"` as a stale research run. Inspect `coauthor research structured <project-id> --json` and use the returned next commands instead of retrying blindly.
20
+ - Treat `status: "research_structuring"` or `data.diagnostic.code: "research_structuring"` as a normal transition after raw research completes. Keep waiting or resume toward draft; do not rewind or generate a draft until project state reaches `research_structured`.
19
21
  - If `coauthor research status <project-id> --json` returns `data.diagnostic.code: "research_run_state_mismatch"`, report the mismatch and use the returned recovery commands.
22
+ - `coauthor workflow run <project-id> --target draft --wait` should not be treated as complete until the CLI reports draft completion, a key pause, terminal failure, `research_running_stale`, or `timed_out`.
23
+ - For images, run `coauthor image list <project-id> --json` and pass an existing placeholder with `coauthor image generate <project-id> --placeholder-id <placeholder-id> --json`. Draft generation creates placeholders.
20
24
  - Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
21
25
  - After a timeout, interruption, network error, or unclear result, check operation status before retrying.
22
26
  - `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.
@@ -13,7 +13,11 @@ alwaysApply: true
13
13
  - Let the default bounded briefing review run before outline/draft generation. Use `--briefing-mode strict` for a stronger brief gate, and answer or relay `data.clarification_questions` if the CLI returns `status: "needs_clarification"`.
14
14
  - Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable pause. Do not retry in a loop; tell the user to add the required provider key in AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
15
15
  - Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
16
+ - Treat `status: "research_running_stale"` or `data.diagnostic.code: "research_running_stale"` as a stale research run. Inspect `coauthor research structured <project-id> --json` and use the returned next commands instead of retrying blindly.
17
+ - Treat `status: "research_structuring"` or `data.diagnostic.code: "research_structuring"` as a normal transition after raw research completes. Keep waiting or resume toward draft; do not rewind or generate a draft until project state reaches `research_structured`.
16
18
  - If `coauthor research status <project-id> --json` returns `data.diagnostic.code: "research_run_state_mismatch"`, report the mismatch and use the returned recovery commands.
19
+ - `coauthor workflow run <project-id> --target draft --wait` should not be treated as complete until the CLI reports draft completion, a key pause, terminal failure, `research_running_stale`, or `timed_out`.
20
+ - For images, run `coauthor image list <project-id> --json` and pass an existing placeholder with `coauthor image generate <project-id> --placeholder-id <placeholder-id> --json`. Draft generation creates placeholders.
17
21
  - Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
18
22
  - After timeout, interruption, network error, or ambiguous output, check operation status before retrying or reporting success.
19
23
  - `contract approve`, `outline approve`, and `research-plan approve` approve the saved artifact when `--data` is omitted. Pass `--data` only when intentionally approving a replacement payload.