@clickminded/coauthor-cli 0.0.10 → 0.0.12

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
@@ -1,16 +1,13 @@
1
1
  # CoAuthor CLI
2
2
 
3
- `@clickminded/coauthor-cli` installs the `coauthor` command for working with CoAuthor projects from a terminal or from AI coding agents such as Codex, Claude Code, and Cursor.
3
+ `@clickminded/coauthor-cli` installs the `coauthor` command for working with CoAuthor projects from a terminal or from AI coding agents such as Codex, Claude Code, Cursor, and other local agents.
4
4
 
5
- The CLI is public, but your CoAuthor data is private. Every project command requires a scoped token issued by browser/device login.
5
+ The CLI connects to CoAuthor at `https://tools.clickminded.com/coauthor`. Your projects stay private and every project command requires browser/device login.
6
6
 
7
7
  ## Requirements
8
8
 
9
9
  - Node.js 20 or newer.
10
- - A CoAuthor account.
11
- - The base URL for the CoAuthor workspace you want to use.
12
-
13
- CoAuthor server setup, database migrations, and web app environment variables are maintainer/deployment concerns. They are not required for normal CLI users.
10
+ - A CoAuthor account with access to CoAuthor.
14
11
 
15
12
  ## Install
16
13
 
@@ -18,7 +15,6 @@ Install globally:
18
15
 
19
16
  ```sh
20
17
  npm install -g @clickminded/coauthor-cli
21
- coauthor auth status
22
18
  ```
23
19
 
24
20
  Or run without a global install:
@@ -27,35 +23,23 @@ Or run without a global install:
27
23
  npx @clickminded/coauthor-cli help
28
24
  ```
29
25
 
30
- ## Authenticate
26
+ ## Sign In
31
27
 
32
28
  Start browser/device login:
33
29
 
34
30
  ```sh
35
- coauthor auth login --base-url <coauthor-app-url>
31
+ coauthor auth login
36
32
  ```
37
33
 
38
- For example, when testing against a local CoAuthor app:
39
-
40
- ```sh
41
- coauthor auth login --base-url http://localhost:3000
42
- ```
34
+ The CLI opens a browser approval page. After approval, it stores a scoped local token for your signed-in CoAuthor account.
43
35
 
44
- Request publish/export permission during login:
45
-
46
- ```sh
47
- coauthor auth login --base-url <coauthor-app-url> --with-publish
48
- ```
49
-
50
- The CLI opens a browser approval page. Approving there issues a scoped API token for the signed-in CoAuthor user.
51
-
52
- Check the current token:
36
+ Check your login:
53
37
 
54
38
  ```sh
55
39
  coauthor auth status --json
56
40
  ```
57
41
 
58
- Log out and clear local credentials:
42
+ Log out and revoke the local token:
59
43
 
60
44
  ```sh
61
45
  coauthor auth logout
@@ -63,20 +47,6 @@ coauthor auth logout
63
47
 
64
48
  Local credentials are stored at `~/.coauthor/config.json` with best-effort `0600` permissions. Do not print, paste, or commit this file.
65
49
 
66
- Environment variables override the config file:
67
-
68
- ```sh
69
- COAUTHOR_BASE_URL=<coauthor-app-url>
70
- COAUTHOR_TOKEN=coauthor_xxx
71
- ```
72
-
73
- Global options are:
74
-
75
- - `--json` for machine-readable output.
76
- - `--base-url <url>` to target a specific CoAuthor app.
77
- - `--token <token>` for non-persistent token injection.
78
- - `--data '<json>'` to send command-specific JSON request bodies.
79
-
80
50
  ## Agent Skills
81
51
 
82
52
  Install agent instructions after installing the CLI:
@@ -101,34 +71,32 @@ Default install paths are:
101
71
  - Cursor: `./.cursor/rules/coauthor-cli.mdc`
102
72
  - Agents: `./.agents/skills/coauthor/SKILL.md`
103
73
 
104
- Use `--dry-run` to preview, `--force` to overwrite existing files, and `--cwd <path>` to install project-local Claude/Cursor/Agents skills into a specific project.
74
+ Use `--dry-run` to preview, `--force` to overwrite existing files, and `--cwd <path>` to install project-local Claude, Cursor, or Agents skills into a specific project.
105
75
 
106
- Skill installs are recorded in `~/.config/coauthor/managed-skills.json`. Future npm package updates automatically refresh recorded skill files when they still match the previously installed template. If you edit a skill file by hand, the auto-update leaves it alone until you run `coauthor skills install <target> --force`.
76
+ Skill installs are recorded in `~/.config/coauthor/managed-skills.json`. Future package updates automatically refresh recorded skill files when they still match the previously installed template. If you edit a skill file by hand, the auto-update leaves it alone until you run `coauthor skills install <target> --force`.
107
77
 
108
78
  ## Common Commands
109
79
 
110
- Projects:
80
+ Create and inspect projects:
111
81
 
112
82
  ```sh
113
- coauthor project create --topic "..."
83
+ coauthor project create --title "Post title" --topic "Post brief" --audience "Target reader" --json
114
84
  coauthor project list --json
115
85
  coauthor project show <project-id> --json
116
86
  coauthor workspace show <project-id> --json
117
87
  ```
118
88
 
119
- Chat and workflow:
89
+ Work with the project:
120
90
 
121
91
  ```sh
122
- coauthor chat <project-id> --message "..." --json
92
+ coauthor chat <project-id> --message "Refine the angle for this post" --json
123
93
  coauthor workflow status <project-id> --json
124
94
  coauthor workflow run <project-id> --target draft --wait --json
125
95
  coauthor workflow resume <project-id> --target draft --wait --json
126
- coauthor workflow rewind <project-id> --stage outline --reason "..." --json
127
- coauthor workflow approve <project-id> --stage research_plan --json
128
96
  coauthor credits <project-id> --json
129
97
  ```
130
98
 
131
- Artifacts:
99
+ Read or generate artifacts:
132
100
 
133
101
  ```sh
134
102
  coauthor contract show <project-id> --json
@@ -137,63 +105,61 @@ coauthor research-plan generate <project-id> --json
137
105
  coauthor research run <project-id> --wait --json
138
106
  coauthor draft generate <project-id> --wait --json
139
107
  coauthor draft get <project-id> --format markdown --json
140
- coauthor draft get <project-id> --format html --json
141
- coauthor draft get <project-id> --format text --json
142
- coauthor draft get <project-id> --format json --json
143
108
  ```
144
109
 
145
- Draft exports resolve generated image URLs for Markdown, HTML, and text output when images are available. Use `--format json` or omit `--format` for the raw editor document JSON.
146
-
147
- Images and threads:
110
+ Images and social content:
148
111
 
149
112
  ```sh
150
113
  coauthor image list <project-id> --json
151
- coauthor image generate <project-id> --prompt "..." --json
114
+ coauthor image generate <project-id> --placeholder-id <placeholder-id> --prompt "Image direction" --json
152
115
  coauthor thread generate <project-id> --json
153
- coauthor thread save <project-id> --data '{"posts":[]}' --json
154
116
  ```
155
117
 
156
- Live publish/export actions:
118
+ Use `--json` when another tool or agent needs to parse command output. Use `--wait` when starting longer-running work and you want the command to wait for completion.
119
+
120
+ ## Draft Export
121
+
122
+ Export a finished draft in the format you need:
157
123
 
158
124
  ```sh
159
- coauthor publish thread <project-id> --yes --json
160
- coauthor export blog <project-id> --yes --slug "post-slug" --json
161
- coauthor export clickminded <project-id> --yes --json
162
- coauthor operation status <operation-key> --json
125
+ coauthor draft get <project-id> --format markdown --json
126
+ coauthor draft get <project-id> --format html --json
127
+ coauthor draft get <project-id> --format text --json
128
+ coauthor draft get <project-id> --format json --json
163
129
  ```
164
130
 
165
- Live actions require both token scope and `--yes`.
131
+ Markdown, HTML, and text exports resolve generated image URLs when images are available. Use `--format json` or omit `--format` for the raw editor document JSON.
166
132
 
167
- ## Briefing Review
133
+ ## Live Actions
168
134
 
169
- Workflow runs perform a bounded briefing review before the CLI moves from brainstorming to outline. This avoids weak briefs without trapping an agent in an open-ended conversation.
135
+ Publishing and external exports are real side effects. The default login grants project/workflow access only. To run live publish/export commands, sign in with publish permission:
170
136
 
171
137
  ```sh
172
- coauthor workflow run <project-id> --target draft --briefing-mode auto --wait --json
173
- coauthor workflow run <project-id> --target outline --briefing-mode strict --max-brief-questions 2 --json
138
+ coauthor auth login --with-publish
174
139
  ```
175
140
 
176
- `--briefing-mode` options:
141
+ Then run live actions only when you mean to publish or export:
177
142
 
178
- - `auto` (default): enrich a thin brief and continue when the reviewer can make safe assumptions.
179
- - `strict`: stop with structured clarification questions unless the brief is clearly strong enough.
180
- - `off`: skip the bounded review.
143
+ ```sh
144
+ coauthor publish thread <project-id> --yes --json
145
+ coauthor export blog <project-id> --yes --slug "post-slug" --json
146
+ coauthor export clickminded <project-id> --yes --json
147
+ coauthor operation status <operation-key> --json
148
+ ```
181
149
 
182
- `--require-brief-review` is equivalent to strict mode. If the review needs input, the command returns `ok: true` with `data.status = "needs_clarification"` and a `clarification_questions` array.
150
+ Live actions require both publish scope and `--yes`.
183
151
 
184
152
  ## Agent Usage Rules
185
153
 
186
154
  Agents should:
187
155
 
188
- - Prefer `coauthor` over browser automation, `curl` to session APIs, or direct database access.
189
- - Use `--json` on every command they need to parse.
190
- - Use `--wait` when starting long-running research or draft jobs and the user expects completion.
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_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.
193
- - Use `coauthor credits <project-id> --json` to inspect credit allowance, pending holds, and remaining credits.
194
- - Avoid retrying publish/export after uncertain network failures.
195
- - Use `coauthor operation status <operation-key>` after uncertainty.
196
- - Never print tokens, cookies, service-role keys, provider API keys, or authorization headers.
156
+ - Prefer `coauthor` commands over browser automation, hand-written HTTP requests, or direct database access.
157
+ - Use `--json` for machine-readable output.
158
+ - Use `--wait` when starting asynchronous work and the user expects the result.
159
+ - Treat `status: "requires_key"` or `paused_requires_key` as a recoverable pause. Ask the user to add the required provider key in CoAuthor AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
160
+ - Treat `status: "research_running_stale"` as a stale research run and inspect `coauthor research structured <project-id> --json` before retrying.
161
+ - Check operation status after timeouts, interruptions, network errors, or uncertain live-action results.
162
+ - Never print tokens, cookies, provider keys, service-role keys, or authorization headers.
197
163
 
198
164
  ## Security
199
165
 
@@ -203,34 +169,16 @@ Agents should:
203
169
  - Tokens are stored locally at `~/.coauthor/config.json`.
204
170
  - Run `coauthor auth logout` to revoke the current token and remove local credentials.
205
171
 
206
- ## Public API Stability
207
-
208
- The CLI talks to `/api/agent/v1/*`. Treat this as a public beta API surface:
209
-
210
- - Existing commands should keep stable JSON envelopes.
211
- - New behavior should be additive when possible.
212
- - Errors should stay structured and machine-readable with `--json`.
213
- - Server-side auth, ownership checks, scopes, and rate limits remain mandatory.
214
-
215
172
  ## Troubleshooting
216
173
 
217
- `No token configured` means the CLI has no credential for the selected base URL. Run `coauthor auth login --base-url <url>`.
174
+ `No token configured` means the CLI has no saved CoAuthor credential. Run `coauthor auth login`.
218
175
 
219
- `insufficient_scope` means the token does not include the required scope. For publish/export, log in again with `--with-publish`.
176
+ `insufficient_scope` means the token does not include the required scope. For publish/export, log in again with `coauthor auth login --with-publish`.
220
177
 
221
- `authorization_pending` during login is normal while the browser approval page is waiting for browser approval.
222
-
223
- `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`.
224
-
225
- If `npx @clickminded/coauthor-cli help` fails while you are inside the CLI package source directory, run it from another directory or use:
226
-
227
- ```sh
228
- npm exec --package=@clickminded/coauthor-cli@latest -- coauthor-cli help
229
- ```
178
+ `authorization_pending` during login is normal while the browser approval page is waiting for approval.
230
179
 
231
- ## For CoAuthor Maintainers
180
+ `requires_key` means included credits are exhausted and no usable provider key is configured for the requested capability. Open CoAuthor AI settings, add the required key, then run `coauthor workflow resume <project-id> --wait --json`.
232
181
 
233
- This README is written for public CLI users. Maintainer/deployment details such as database migrations, `COAUTHOR_API_TOKEN_PEPPER`, local monorepo development, and npm Trusted Publishing live in the CoAuthor repository docs:
182
+ `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.
234
183
 
235
- - `docs/agent-cli.md`
236
- - `docs/skills.md`
184
+ 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`.
package/dist/client.d.ts CHANGED
@@ -25,3 +25,4 @@ export declare class AgentClient {
25
25
  request(options: RequestOptions): Promise<JsonValue>;
26
26
  }
27
27
  export declare function isLiveAction(method: string): boolean;
28
+ export declare function normalizeBaseUrl(baseUrl: string): string;
package/dist/client.js CHANGED
@@ -23,7 +23,7 @@ export class AgentClient {
23
23
  token;
24
24
  fetchImpl;
25
25
  constructor(options) {
26
- this.baseUrl = new URL('/api/agent/v1/', normalizeBaseUrl(options.baseUrl));
26
+ this.baseUrl = new URL('api/agent/v1/', normalizeBaseUrl(options.baseUrl));
27
27
  this.token = options.token ?? '';
28
28
  this.fetchImpl = options.fetchImpl ?? fetch;
29
29
  }
@@ -74,7 +74,7 @@ async function readResponseBody(response) {
74
74
  return text;
75
75
  }
76
76
  }
77
- function normalizeBaseUrl(baseUrl) {
77
+ export function normalizeBaseUrl(baseUrl) {
78
78
  return baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
79
79
  }
80
80
  function trimLeadingSlash(path) {
@@ -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
@@ -5,7 +5,7 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises';
5
5
  import { homedir } from 'node:os';
6
6
  import { dirname, join, resolve } from 'node:path';
7
7
  import { fileURLToPath } from 'node:url';
8
- import { AgentHttpError } from './client.js';
8
+ import { AgentHttpError, normalizeBaseUrl } from './client.js';
9
9
  import { clearConfig, loadConfig, saveConfig } from './config.js';
10
10
  import { getBoolean, getString, parseJsonOption } from './parser.js';
11
11
  export async function runCommand(input, context) {
@@ -27,17 +27,19 @@ export async function runCommand(input, context) {
27
27
  if (scope === 'research-plan')
28
28
  return runArtifactCommand('research-plan', action, input, context.client);
29
29
  if (scope === 'research')
30
- return runResearchCommand(action, input, context.client);
30
+ return runResearchCommand(action, input, context);
31
31
  if (scope === 'draft')
32
- return runDraftCommand(action, input, context.client);
32
+ return runDraftCommand(action, input, context);
33
33
  if (scope === 'workflow')
34
- return runWorkflowCommand(action, input, context.client);
34
+ return runWorkflowCommand(action, input, context);
35
35
  if (scope === 'credits')
36
36
  return runCreditsCommand(input, context.client);
37
37
  if (scope === 'image')
38
38
  return runResourceCommand('images', action, input, context.client);
39
39
  if (scope === 'thread')
40
40
  return runResourceCommand('threads', action, input, context.client);
41
+ if (scope === 'slideshow')
42
+ return runResourceCommand('slideshows', action, input, context.client);
41
43
  if (scope === 'publish')
42
44
  return runResourceCommand('publish', action, input, context.client);
43
45
  if (scope === 'export')
@@ -197,7 +199,8 @@ async function runChatCommand(action, input, client) {
197
199
  data: enrichChatResult(data, projectId, stage),
198
200
  };
199
201
  }
200
- async function runWorkflowCommand(action, input, client) {
202
+ async function runWorkflowCommand(action, input, context) {
203
+ const { client } = context;
201
204
  const projectId = requireProjectId(input);
202
205
  const projectPath = `projects/${encodeURIComponent(projectId)}/workflow`;
203
206
  if (action === 'show' || action === 'status') {
@@ -208,20 +211,20 @@ async function runWorkflowCommand(action, input, client) {
208
211
  const target = normalizeWorkflowWaitTarget(getString(input.values, 'target') ?? getString(input.values, 'stage')) ?? 'draft';
209
212
  if (target === 'research') {
210
213
  const data = await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/research/run`, body: {} });
211
- return getBoolean(input.values, 'wait') ? waitForResearch(client, projectId, data) : { ok: true, data };
214
+ return getBoolean(input.values, 'wait') ? waitForResearch(client, projectId, data, context.baseUrl) : { ok: true, data };
212
215
  }
213
216
  const researchStatus = await client.request({ path: `projects/${encodeURIComponent(projectId)}/research/status` });
214
217
  if (extractNestedString(researchStatus, ['run', 'status']) === 'paused_requires_key') {
215
218
  const data = await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/research/run`, body: {} });
216
- return getBoolean(input.values, 'wait') ? waitForWorkflowDraft(client, projectId, data) : { ok: true, data };
219
+ return getBoolean(input.values, 'wait') ? waitForWorkflowDraft(client, projectId, data, context.baseUrl) : { ok: true, data };
217
220
  }
218
221
  const draftStatus = await client.request({ path: `projects/${encodeURIComponent(projectId)}/draft/status` });
219
222
  if (getResponseString(draftStatus, 'phase') === 'paused_requires_key') {
220
223
  const data = await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/draft/generate`, body: {} });
221
- return getBoolean(input.values, 'wait') ? waitForDraft(client, projectId, data) : { ok: true, data };
224
+ return getBoolean(input.values, 'wait') ? waitForDraft(client, projectId, data, context.baseUrl) : { ok: true, data };
222
225
  }
223
226
  const data = await client.request({ method: 'POST', path: `${projectPath}/run`, body: { target } });
224
- return getBoolean(input.values, 'wait') ? waitForWorkflowDraft(client, projectId, data) : { ok: true, data };
227
+ return getBoolean(input.values, 'wait') ? waitForWorkflowDraft(client, projectId, data, context.baseUrl) : { ok: true, data };
225
228
  }
226
229
  if (action === 'advance' || action === 'run' || action === 'rewind' || action === 'approve') {
227
230
  const body = withNamedOptions(parseJsonOption(input.values), input.values, [
@@ -247,9 +250,9 @@ async function runWorkflowCommand(action, input, client) {
247
250
  ?? getString(input.values, 'stage')
248
251
  ?? getResponseString(data, 'target'));
249
252
  if (target === 'research')
250
- return waitForResearch(client, projectId, data);
253
+ return waitForResearch(client, projectId, data, context.baseUrl);
251
254
  if (target === 'draft')
252
- return waitForWorkflowDraft(client, projectId, data);
255
+ return waitForWorkflowDraft(client, projectId, data, context.baseUrl);
253
256
  }
254
257
  return { ok: true, data };
255
258
  }
@@ -277,14 +280,15 @@ async function runArtifactCommand(artifact, action, input, client) {
277
280
  }
278
281
  throw new Error(`Usage: coauthor ${artifact} <show|generate|save|approve> <projectId>`);
279
282
  }
280
- async function runResearchCommand(action, input, client) {
283
+ async function runResearchCommand(action, input, context) {
284
+ const { client } = context;
281
285
  const projectId = requireProjectId(input);
282
286
  const basePath = `projects/${encodeURIComponent(projectId)}/research`;
283
287
  if (action === 'run') {
284
288
  const body = withNamedOptions(parseJsonOption(input.values), input.values, ['execution-token']);
285
289
  const data = await client.request({ method: 'POST', path: `${basePath}/run`, body });
286
290
  if (getBoolean(input.values, 'wait')) {
287
- return waitForResearch(client, projectId, data);
291
+ return waitForResearch(client, projectId, data, context.baseUrl);
288
292
  }
289
293
  return { ok: true, data };
290
294
  }
@@ -296,14 +300,15 @@ async function runResearchCommand(action, input, client) {
296
300
  }
297
301
  throw new Error('Usage: coauthor research <run|status|structured> <projectId>');
298
302
  }
299
- async function runDraftCommand(action, input, client) {
303
+ async function runDraftCommand(action, input, context) {
304
+ const { client } = context;
300
305
  const projectId = requireProjectId(input);
301
306
  const basePath = `projects/${encodeURIComponent(projectId)}/draft`;
302
307
  if (action === 'generate') {
303
308
  const body = withNamedOptions(parseJsonOption(input.values), input.values, ['execution-token']);
304
309
  const data = await client.request({ method: 'POST', path: `${basePath}/generate`, body });
305
310
  if (getBoolean(input.values, 'wait')) {
306
- return waitForDraft(client, projectId, data);
311
+ return waitForDraft(client, projectId, data, context.baseUrl);
307
312
  }
308
313
  return { ok: true, data };
309
314
  }
@@ -336,7 +341,7 @@ async function runResourceCommand(resource, action, input, client) {
336
341
  const data = await client.request({ path: `${basePath}/status` });
337
342
  return { ok: true, data };
338
343
  }
339
- if (resource === 'threads') {
344
+ if (resource === 'threads' || resource === 'slideshows') {
340
345
  const data = await client.request({ path: resourceId ? `${basePath}/${encodeURIComponent(resourceId)}` : basePath });
341
346
  return { ok: true, data };
342
347
  }
@@ -631,11 +636,12 @@ function openBrowser(url) {
631
636
  });
632
637
  child.unref();
633
638
  }
634
- async function waitForResearch(client, projectId, initialData) {
635
- const deadline = Date.now() + 20 * 60_000;
639
+ async function waitForResearch(client, projectId, initialData, baseUrl) {
640
+ const deadline = Date.now() + waitTimeoutMs(20 * 60_000);
641
+ const pollMs = waitPollMs();
636
642
  let latest = initialData;
637
643
  while (Date.now() < deadline) {
638
- await sleep(3000);
644
+ await sleep(pollMs);
639
645
  latest = await client.request({ path: `projects/${encodeURIComponent(projectId)}/research/status` });
640
646
  const status = extractNestedString(latest, ['run', 'status']);
641
647
  if (status === 'succeeded')
@@ -643,16 +649,20 @@ async function waitForResearch(client, projectId, initialData) {
643
649
  if (status === 'failed')
644
650
  throw new Error(extractNestedString(latest, ['run', 'error_message']) ?? 'Research failed');
645
651
  if (status === 'paused_requires_key') {
646
- return requiresKeyPauseResult(projectId, 'research', extractNestedString(latest, ['run', 'error_message']) ?? 'Research paused: add the required API key to continue.', latest);
652
+ return requiresKeyPauseResult(projectId, 'research', extractNestedString(latest, ['run', 'error_message']) ?? 'Research paused: add the required API key to continue.', latest, baseUrl);
647
653
  }
654
+ const stale = researchRunningStaleResult(projectId, latest, null, initialData);
655
+ if (stale)
656
+ return stale;
648
657
  }
649
- return { ok: true, message: 'Timed out waiting for research; check status with coauthor research status', data: latest };
658
+ return waitTimedOutResult(projectId, 'research', initialData, latest, null);
650
659
  }
651
- async function waitForDraft(client, projectId, initialData) {
652
- const deadline = Date.now() + 20 * 60_000;
660
+ async function waitForDraft(client, projectId, initialData, baseUrl) {
661
+ const deadline = Date.now() + waitTimeoutMs(20 * 60_000);
662
+ const pollMs = waitPollMs();
653
663
  let latest = initialData;
654
664
  while (Date.now() < deadline) {
655
- await sleep(3000);
665
+ await sleep(pollMs);
656
666
  latest = await client.request({ path: `projects/${encodeURIComponent(projectId)}/draft/status` });
657
667
  const state = getResponseString(latest, 'project_state');
658
668
  const phase = getResponseString(latest, 'phase');
@@ -660,23 +670,21 @@ async function waitForDraft(client, projectId, initialData) {
660
670
  return { ok: true, message: 'Draft completed', data: latest };
661
671
  }
662
672
  if (phase === 'paused_requires_key')
663
- return requiresKeyPauseResult(projectId, 'draft', getResponseString(latest, 'message') ?? 'Draft paused: add the required API key to continue.', latest);
673
+ return requiresKeyPauseResult(projectId, 'draft', getResponseString(latest, 'message') ?? 'Draft paused: add the required API key to continue.', latest, baseUrl);
664
674
  if (phase === 'failed')
665
675
  throw new Error(getResponseString(latest, 'message') ?? 'Draft generation failed');
666
676
  }
667
- return { ok: true, message: 'Timed out waiting for draft; check status with coauthor draft status', data: latest };
677
+ return waitTimedOutResult(projectId, 'draft', initialData, null, latest);
668
678
  }
669
- async function waitForWorkflowDraft(client, projectId, initialData) {
670
- const deadline = Date.now() + 40 * 60_000;
679
+ async function waitForWorkflowDraft(client, projectId, initialData, baseUrl) {
680
+ const deadline = Date.now() + waitTimeoutMs(40 * 60_000);
681
+ const pollMs = waitPollMs();
671
682
  let latestDraft = initialData;
672
683
  let latestResearch = null;
673
684
  let draftGenerate = null;
674
685
  let attemptedDraftStart = false;
675
- if (workflowIndicatesBackgroundResearch(initialData)) {
676
- return researchRunningWorkflowResult(projectId, initialData, null, null);
677
- }
678
686
  while (Date.now() < deadline) {
679
- await sleep(3000);
687
+ await sleep(pollMs);
680
688
  latestDraft = await client.request({ path: `projects/${encodeURIComponent(projectId)}/draft/status` });
681
689
  const draftState = getResponseString(latestDraft, 'project_state');
682
690
  const draftPhase = getResponseString(latestDraft, 'phase');
@@ -699,7 +707,7 @@ async function waitForWorkflowDraft(client, projectId, initialData) {
699
707
  workflow: initialData,
700
708
  research_status: latestResearch,
701
709
  draft_status: latestDraft,
702
- });
710
+ }, baseUrl);
703
711
  }
704
712
  latestResearch = await client.request({ path: `projects/${encodeURIComponent(projectId)}/research/status` });
705
713
  const researchStatus = extractNestedString(latestResearch, ['run', 'status']);
@@ -711,8 +719,11 @@ async function waitForWorkflowDraft(client, projectId, initialData) {
711
719
  workflow: initialData,
712
720
  research_status: latestResearch,
713
721
  draft_status: latestDraft,
714
- });
722
+ }, baseUrl);
715
723
  }
724
+ const stale = researchRunningStaleResult(projectId, latestResearch, latestDraft, initialData);
725
+ if (stale)
726
+ return stale;
716
727
  if (!attemptedDraftStart
717
728
  && (researchStatus === 'succeeded' || isResearchReadyForDraft(draftState))
718
729
  && draftPhase !== 'queued'
@@ -731,13 +742,73 @@ async function waitForWorkflowDraft(client, projectId, initialData) {
731
742
  }
732
743
  }
733
744
  }
745
+ return waitTimedOutResult(projectId, 'workflow draft target', initialData, latestResearch, latestDraft);
746
+ }
747
+ function waitPollMs() {
748
+ const raw = Number(process.env.COAUTHOR_CLI_WAIT_POLL_MS);
749
+ return Number.isFinite(raw) && raw >= 0 ? raw : 3000;
750
+ }
751
+ function waitTimeoutMs(defaultMs) {
752
+ const raw = Number(process.env.COAUTHOR_CLI_WAIT_TIMEOUT_MS);
753
+ return Number.isFinite(raw) && raw > 0 ? raw : defaultMs;
754
+ }
755
+ function researchStaleMs() {
756
+ const raw = Number(process.env.COAUTHOR_CLI_RESEARCH_STALE_MS);
757
+ return Number.isFinite(raw) && raw > 0 ? raw : 10 * 60_000;
758
+ }
759
+ function researchRunAgeMs(data) {
760
+ const timestamp = extractNestedString(data, ['run', 'updated_at'])
761
+ ?? extractNestedString(data, ['run', 'created_at']);
762
+ if (!timestamp)
763
+ return null;
764
+ const time = Date.parse(timestamp);
765
+ if (!Number.isFinite(time))
766
+ return null;
767
+ return Date.now() - time;
768
+ }
769
+ function isResearchRunningStale(data) {
770
+ if (extractNestedString(data, ['run', 'status']) !== 'running')
771
+ return false;
772
+ if (getResponseString(data, 'project_state') !== 'research_running')
773
+ return false;
774
+ const ageMs = researchRunAgeMs(data);
775
+ return typeof ageMs === 'number' && ageMs >= researchStaleMs();
776
+ }
777
+ function researchRunningStaleResult(projectId, researchStatus, draftStatus, workflow) {
778
+ if (!isResearchRunningStale(researchStatus))
779
+ return null;
734
780
  return {
735
- ok: true,
736
- message: 'Timed out waiting for workflow draft target; check status with coauthor draft status',
781
+ ok: false,
782
+ status: 'research_running_stale',
783
+ exitCode: 2,
784
+ message: 'Research is still marked running and has not reported a terminal state within the expected window.',
737
785
  data: {
738
- workflow: initialData,
739
- research_status: latestResearch,
740
- draft_status: latestDraft,
786
+ workflow,
787
+ research_status: enrichResearchStatus(researchStatus),
788
+ draft_status: draftStatus,
789
+ next_commands: [
790
+ `coauthor research status ${projectId} --json`,
791
+ `coauthor research structured ${projectId} --json`,
792
+ `coauthor workflow rewind ${projectId} --target research --json`,
793
+ ],
794
+ },
795
+ };
796
+ }
797
+ function waitTimedOutResult(projectId, target, workflow, researchStatus, draftStatus) {
798
+ return {
799
+ ok: false,
800
+ status: 'timed_out',
801
+ exitCode: 2,
802
+ message: `Timed out waiting for ${target}; check status before retrying.`,
803
+ data: {
804
+ workflow,
805
+ research_status: researchStatus,
806
+ draft_status: draftStatus,
807
+ next_commands: [
808
+ `coauthor research status ${projectId} --json`,
809
+ `coauthor draft status ${projectId} --json`,
810
+ `coauthor workflow resume ${projectId} --target draft --wait --json`,
811
+ ],
741
812
  },
742
813
  };
743
814
  }
@@ -790,7 +861,23 @@ function enrichResearchStatus(data) {
790
861
  return data;
791
862
  const runStatus = extractNestedString(data, ['run', 'status']);
792
863
  const projectState = getResponseString(data, 'project_state');
793
- if (runStatus !== 'running' || projectState === 'research_running')
864
+ if (runStatus !== 'running')
865
+ return data;
866
+ if (isResearchRunningStale(data)) {
867
+ return {
868
+ ...data,
869
+ diagnostic: {
870
+ code: 'research_running_stale',
871
+ 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.',
872
+ next_commands: [
873
+ 'coauthor research status <project-id> --json',
874
+ 'coauthor research structured <project-id> --json',
875
+ 'coauthor workflow rewind <project-id> --target research --json',
876
+ ],
877
+ },
878
+ };
879
+ }
880
+ if (projectState === 'research_running')
794
881
  return data;
795
882
  if (projectState === 'research_complete') {
796
883
  return {
@@ -819,37 +906,15 @@ function enrichResearchStatus(data) {
819
906
  },
820
907
  };
821
908
  }
822
- function workflowIndicatesBackgroundResearch(data) {
823
- if (!data || typeof data !== 'object' || Array.isArray(data))
824
- return false;
825
- return getResponseString(data, 'project_state') === 'research_running'
826
- || getResponseString(data, 'status') === 'research_running';
827
- }
828
- function researchRunningWorkflowResult(projectId, workflow, researchStatus, draftStatus) {
829
- return {
830
- ok: true,
831
- status: 'research_running',
832
- message: 'Research is running in the background. Draft generation has not started yet.',
833
- data: {
834
- workflow,
835
- research_status: researchStatus,
836
- draft_status: draftStatus,
837
- next_commands: [
838
- `coauthor research status ${projectId} --json`,
839
- `coauthor workflow resume ${projectId} --target draft --wait --json`,
840
- `coauthor workflow rewind ${projectId} --target research --json`,
841
- ],
842
- },
843
- };
844
- }
845
- function requiresKeyPauseResult(projectId, target, message, data) {
909
+ function requiresKeyPauseResult(projectId, target, message, data, baseUrl) {
846
910
  const resumeCommand = `coauthor workflow resume ${projectId} --target ${target} --wait --json`;
911
+ const settingsUrl = new URL('settings/ai', normalizeBaseUrl(baseUrl)).toString();
847
912
  return {
848
913
  ok: false,
849
914
  status: 'requires_key',
850
915
  exitCode: 2,
851
- message: `${message}\nOpen AI settings: /settings/ai\nResume: ${resumeCommand}`,
852
- settings_url: '/settings/ai',
916
+ message: `${message}\nOpen AI settings: ${settingsUrl}\nResume: ${resumeCommand}`,
917
+ settings_url: settingsUrl,
853
918
  resume_command: resumeCommand,
854
919
  data,
855
920
  };
@@ -903,16 +968,19 @@ function resourceCommandName(resource) {
903
968
  return 'image';
904
969
  if (resource === 'threads')
905
970
  return 'thread';
971
+ if (resource === 'slideshows')
972
+ return 'slideshow';
906
973
  if (resource === 'exports')
907
974
  return 'export';
908
975
  if (resource === 'operations')
909
976
  return 'operation';
910
977
  return resource;
911
978
  }
912
- export function helpResult() {
979
+ export function helpResult(command = []) {
980
+ const scoped = commandHelp(command);
913
981
  return {
914
982
  ok: true,
915
- message: [
983
+ message: scoped ?? [
916
984
  'Usage: coauthor <command> [options]',
917
985
  '',
918
986
  'Commands:',
@@ -930,6 +998,7 @@ export function helpResult() {
930
998
  ' workflow run/advance supports --briefing-mode auto|strict|off and --require-brief-review',
931
999
  ' image list|status|show|generate|edit',
932
1000
  ' thread list|show|create|generate|save',
1001
+ ' slideshow show|save',
933
1002
  ' publish thread',
934
1003
  ' export blog|clickminded',
935
1004
  ' operation list|show|status',
@@ -939,3 +1008,44 @@ export function helpResult() {
939
1008
  ].join('\n'),
940
1009
  };
941
1010
  }
1011
+ function commandHelp(command) {
1012
+ const key = command.join(' ');
1013
+ const help = {
1014
+ 'project create': [
1015
+ 'Usage: coauthor project create [--title <title>] [--topic <brief>] [--audience <audience>] [--json]',
1016
+ '',
1017
+ 'Creates a project. When --topic or --audience is provided, CoAuthor seeds the saved contract so workflow briefing review can use that context.',
1018
+ ].join('\n'),
1019
+ 'workflow run': [
1020
+ 'Usage: coauthor workflow run <project-id> --target <outline|research|draft> [--wait] [--briefing-mode auto|strict|off] [--json]',
1021
+ '',
1022
+ '--wait blocks until the requested target completes, pauses for a key, fails, reports stale research, or times out.',
1023
+ ].join('\n'),
1024
+ 'workflow resume': [
1025
+ 'Usage: coauthor workflow resume <project-id> [--target <research|draft>] [--wait] [--json]',
1026
+ '',
1027
+ 'Use after an interruption, timeout, or requires_key pause. For draft targets, --wait continues through research and draft generation.',
1028
+ ].join('\n'),
1029
+ 'draft generate': [
1030
+ 'Usage: coauthor draft generate <project-id> [--wait] [--json]',
1031
+ '',
1032
+ 'Requires project_state "research_structured". If research is still running or structuring, inspect the returned status and next commands.',
1033
+ ].join('\n'),
1034
+ 'draft get': [
1035
+ 'Usage: coauthor draft get <project-id> [--format json|markdown|html|text] [--json]',
1036
+ '',
1037
+ 'Retrieves a saved generated draft. Chat responses are available through coauthor chat show.',
1038
+ ].join('\n'),
1039
+ 'draft save': [
1040
+ 'Usage: coauthor draft save <project-id> --data \'<json>\' [--json]',
1041
+ '',
1042
+ 'Saves a draft document payload through the agent API.',
1043
+ ].join('\n'),
1044
+ 'image generate': [
1045
+ 'Usage: coauthor image generate <project-id> --placeholder-id <placeholder-id> [--prompt "..."] [--json]',
1046
+ '',
1047
+ 'Image generation requires an image placeholder from coauthor image list. Draft generation creates placeholders.',
1048
+ ].join('\n'),
1049
+ };
1050
+ return help[key] ?? null;
1051
+ }
package/dist/config.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import { z } from 'zod';
2
- export declare const DEFAULT_BASE_URL = "http://localhost:3000";
2
+ export declare const DEFAULT_BASE_URL = "https://tools.clickminded.com/coauthor";
3
3
  declare const configSchema: z.ZodObject<{
4
4
  baseUrl: z.ZodOptional<z.ZodString>;
5
5
  token: z.ZodOptional<z.ZodString>;
package/dist/config.js CHANGED
@@ -2,7 +2,7 @@ import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
2
2
  import { homedir } from 'node:os';
3
3
  import { dirname, join } from 'node:path';
4
4
  import { z } from 'zod';
5
- export const DEFAULT_BASE_URL = 'http://localhost:3000';
5
+ export const DEFAULT_BASE_URL = 'https://tools.clickminded.com/coauthor';
6
6
  const configSchema = z.object({
7
7
  baseUrl: z.string().url().optional(),
8
8
  token: z.string().min(1).optional(),
package/dist/index.js CHANGED
@@ -1,8 +1,8 @@
1
1
  #!/usr/bin/env node
2
2
  import { realpathSync } from 'node:fs';
3
3
  import { fileURLToPath } from 'node:url';
4
- import { AgentHttpError, AgentClient } from './client.js';
5
- import { resolveRuntimeConfig } from './config.js';
4
+ import { AgentHttpError, AgentClient, normalizeBaseUrl } from './client.js';
5
+ import { DEFAULT_BASE_URL, resolveRuntimeConfig } from './config.js';
6
6
  import { helpResult, runCommand } from './commands.js';
7
7
  import { renderError, renderResult } from './output.js';
8
8
  import { parseCliArgs } from './parser.js';
@@ -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({
@@ -146,7 +146,9 @@ function formatRequiresKeyResult(body, baseUrl) {
146
146
  const details = envelopeError.details && typeof envelopeError.details === 'object' && !Array.isArray(envelopeError.details)
147
147
  ? envelopeError.details
148
148
  : {};
149
- const settingsUrl = typeof details.settings_url === 'string' ? details.settings_url : new URL('/settings/ai', baseUrl).toString();
149
+ const settingsUrl = typeof details.settings_url === 'string'
150
+ ? details.settings_url
151
+ : new URL('settings/ai', normalizeBaseUrl(baseUrl)).toString();
150
152
  const resumeCommand = typeof details.resume_command === 'string' ? details.resume_command : undefined;
151
153
  return {
152
154
  ok: false,
@@ -181,7 +183,7 @@ function extractEnvelopeError(body) {
181
183
  function resolveBaseUrlFromArgv(argv) {
182
184
  const index = argv.indexOf('--base-url');
183
185
  const value = index >= 0 ? argv[index + 1] : undefined;
184
- return value || process.env.COAUTHOR_BASE_URL || 'http://localhost:3000';
186
+ return value || process.env.COAUTHOR_BASE_URL || DEFAULT_BASE_URL;
185
187
  }
186
188
  function isCliEntrypoint() {
187
189
  const argvPath = process.argv[1];
package/dist/parser.js CHANGED
@@ -108,7 +108,7 @@ function commandLength(positionals) {
108
108
  return second ? 2 : 1;
109
109
  if (first === 'credits')
110
110
  return 1;
111
- if (['contract', 'outline', 'research-plan', 'research', 'draft', 'image', 'thread', 'publish', 'export', 'operation'].includes(first ?? ''))
111
+ if (['contract', 'outline', 'research-plan', 'research', 'draft', 'image', 'thread', 'slideshow', 'publish', 'export', 'operation'].includes(first ?? ''))
112
112
  return second ? 2 : 1;
113
113
  return 1;
114
114
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.10",
3
+ "version": "0.0.12",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -8,8 +8,8 @@
8
8
  },
9
9
  "repository": {
10
10
  "type": "git",
11
- "url": "git+https://github.com/eduardoyi/coauthor.git",
12
- "directory": "packages/cli"
11
+ "url": "git+https://github.com/ClickMinded/newsletter-generator.git",
12
+ "directory": "coauthor/packages/cli"
13
13
  },
14
14
  "exports": {
15
15
  ".": {
@@ -9,15 +9,18 @@ This skill guides agent use of the CoAuthor CLI.
9
9
 
10
10
  - Prefer `coauthor` CLI commands for CoAuthor project and workflow work.
11
11
  - Do not drive browser routes, hand-written `curl`, or direct database edits when a CLI command covers the task.
12
- - Use the configured production base URL by default. Do not point the CLI at `localhost` or start a local dev server unless the user explicitly asks to test local changes.
13
- - For local development only, pass an explicit one-off override such as `--base-url http://localhost:3000` or `COAUTHOR_BASE_URL=http://localhost:3000`.
12
+ - Use the built-in production base URL (`https://tools.clickminded.com/coauthor`) by default. Do not point the CLI at `localhost` or start a local dev server unless the user explicitly asks to test local changes.
13
+ - For local development only, pass an explicit one-off override such as `--base-url http://localhost:3000/coauthor` or `COAUTHOR_BASE_URL=http://localhost:3000/coauthor` for mounted dev, or `--base-url http://localhost:3000` for a root-mounted app.
14
14
  - Use `--json` for machine-readable output and parse fields from that output.
15
15
  - Use `--wait` for commands that start asynchronous work when the user expects the operation to finish.
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.
19
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`.
20
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.
21
24
  - Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
22
25
  - After a timeout, interruption, network error, or unclear result, check operation status before retrying.
23
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.
@@ -9,15 +9,18 @@ This skill guides agent use of the CoAuthor CLI.
9
9
 
10
10
  - Prefer `coauthor` CLI commands for CoAuthor project and workflow work.
11
11
  - Do not drive browser routes, hand-written `curl`, or direct database edits when a CLI command covers the task.
12
- - Use the configured production base URL by default. Do not point the CLI at `localhost` or start a local dev server unless the user explicitly asks to test local changes.
13
- - For local development only, pass an explicit one-off override such as `--base-url http://localhost:3000` or `COAUTHOR_BASE_URL=http://localhost:3000`.
12
+ - Use the built-in production base URL (`https://tools.clickminded.com/coauthor`) by default. Do not point the CLI at `localhost` or start a local dev server unless the user explicitly asks to test local changes.
13
+ - For local development only, pass an explicit one-off override such as `--base-url http://localhost:3000/coauthor` or `COAUTHOR_BASE_URL=http://localhost:3000/coauthor` for mounted dev, or `--base-url http://localhost:3000` for a root-mounted app.
14
14
  - Use `--json` for machine-readable output and parse fields from that output.
15
15
  - Use `--wait` for commands that start asynchronous work when the user expects the operation to finish.
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.
19
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`.
20
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.
21
24
  - Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
22
25
  - After a timeout, interruption, network error, or unclear result, check operation status before retrying.
23
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.
@@ -9,15 +9,18 @@ This skill guides agent use of the CoAuthor CLI.
9
9
 
10
10
  - Prefer `coauthor` CLI commands for CoAuthor project and workflow work.
11
11
  - Do not drive browser routes, hand-written `curl`, or direct database edits when a CLI command covers the task.
12
- - Use the configured production base URL by default. Do not point the CLI at `localhost` or start a local dev server unless the user explicitly asks to test local changes.
13
- - For local development only, pass an explicit one-off override such as `--base-url http://localhost:3000` or `COAUTHOR_BASE_URL=http://localhost:3000`.
12
+ - Use the built-in production base URL (`https://tools.clickminded.com/coauthor`) by default. Do not point the CLI at `localhost` or start a local dev server unless the user explicitly asks to test local changes.
13
+ - For local development only, pass an explicit one-off override such as `--base-url http://localhost:3000/coauthor` or `COAUTHOR_BASE_URL=http://localhost:3000/coauthor` for mounted dev, or `--base-url http://localhost:3000` for a root-mounted app.
14
14
  - Use `--json` for machine-readable output and parse fields from that output.
15
15
  - Use `--wait` for commands that start asynchronous work when the user expects the operation to finish.
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.
19
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`.
20
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.
21
24
  - Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
22
25
  - After a timeout, interruption, network error, or unclear result, check operation status before retrying.
23
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.
@@ -6,15 +6,18 @@ alwaysApply: true
6
6
  # CoAuthor CLI
7
7
 
8
8
  - Prefer the `coauthor` CLI for CoAuthor project/workflow operations instead of browser routes, hand-written `curl`, or direct database access.
9
- - Use the configured production base URL by default. Do not point the CLI at `localhost` or start a local dev server unless the user explicitly asks to test local changes.
10
- - For local development only, pass an explicit one-off override such as `--base-url http://localhost:3000` or `COAUTHOR_BASE_URL=http://localhost:3000`.
9
+ - Use the built-in production base URL (`https://tools.clickminded.com/coauthor`) by default. Do not point the CLI at `localhost` or start a local dev server unless the user explicitly asks to test local changes.
10
+ - For local development only, pass an explicit one-off override such as `--base-url http://localhost:3000/coauthor` or `COAUTHOR_BASE_URL=http://localhost:3000/coauthor` for mounted dev, or `--base-url http://localhost:3000` for a root-mounted app.
11
11
  - Use `--json` for agent-readable command output.
12
12
  - Use `--wait` when starting asynchronous work and the user expects a completed result.
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.
16
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`.
17
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.
18
21
  - Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
19
22
  - After timeout, interruption, network error, or ambiguous output, check operation status before retrying or reporting success.
20
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.