@clickminded/coauthor-cli 0.0.11 → 0.0.13

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,100 +71,104 @@ 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
95
+ coauthor workflow run <project-id> --target draft --planning-model gpt-5.5 --writing-model gpt-5.4 --wait --json
125
96
  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
97
  coauthor credits <project-id> --json
129
98
  ```
130
99
 
131
- Artifacts:
100
+ List and save text model preferences:
101
+
102
+ ```sh
103
+ coauthor models list
104
+ coauthor models preferences show --json
105
+ coauthor models preferences set --planning-model gpt-5.5 --writing-model gpt-5.4 --json
106
+ ```
107
+
108
+ Read or generate artifacts:
132
109
 
133
110
  ```sh
134
111
  coauthor contract show <project-id> --json
135
- coauthor outline generate <project-id> --json
136
- coauthor research-plan generate <project-id> --json
112
+ coauthor outline generate <project-id> --planning-model claude-opus-4-8 --json
113
+ coauthor research-plan generate <project-id> --planning-model gpt-5.5 --json
137
114
  coauthor research run <project-id> --wait --json
138
- coauthor draft generate <project-id> --wait --json
115
+ coauthor draft generate <project-id> --writing-model gpt-5.4 --wait --json
139
116
  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
117
  ```
144
118
 
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:
119
+ Images and social content:
148
120
 
149
121
  ```sh
150
122
  coauthor image list <project-id> --json
151
- coauthor image generate <project-id> --placeholder-id <placeholder-id> --prompt "..." --json
152
- coauthor thread generate <project-id> --json
153
- coauthor thread save <project-id> --data '{"posts":[]}' --json
123
+ coauthor image generate <project-id> --placeholder-id <placeholder-id> --prompt "Image direction" --json
124
+ coauthor thread generate <project-id> --writing-model gpt-5.4 --json
154
125
  ```
155
126
 
156
- Live publish/export actions:
127
+ 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.
128
+
129
+ ## Draft Export
130
+
131
+ Export a finished draft in the format you need:
157
132
 
158
133
  ```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
134
+ coauthor draft get <project-id> --format markdown --json
135
+ coauthor draft get <project-id> --format html --json
136
+ coauthor draft get <project-id> --format text --json
137
+ coauthor draft get <project-id> --format json --json
163
138
  ```
164
139
 
165
- Live actions require both token scope and `--yes`.
140
+ 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
141
 
167
- ## Briefing Review
142
+ ## Live Actions
168
143
 
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.
144
+ 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
145
 
171
146
  ```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
147
+ coauthor auth login --with-publish
174
148
  ```
175
149
 
176
- `--briefing-mode` options:
150
+ Then run live actions only when you mean to publish or export:
177
151
 
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.
152
+ ```sh
153
+ coauthor publish thread <project-id> --yes --json
154
+ coauthor export blog <project-id> --yes --slug "post-slug" --json
155
+ coauthor export clickminded <project-id> --yes --json
156
+ coauthor operation status <operation-key> --json
157
+ ```
181
158
 
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.
159
+ Live actions require both publish scope and `--yes`.
183
160
 
184
161
  ## Agent Usage Rules
185
162
 
186
163
  Agents should:
187
164
 
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_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.
194
- - Use `coauthor credits <project-id> --json` to inspect credit allowance, pending holds, and remaining credits.
195
- - Avoid retrying publish/export after uncertain network failures.
196
- - Use `coauthor operation status <operation-key>` after uncertainty.
197
- - Never print tokens, cookies, service-role keys, provider API keys, or authorization headers.
165
+ - Prefer `coauthor` commands over browser automation, hand-written HTTP requests, or direct database access.
166
+ - Use `--json` for machine-readable output.
167
+ - Use `--wait` when starting asynchronous work and the user expects the result.
168
+ - 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`.
169
+ - Treat `status: "research_running_stale"` as a stale research run and inspect `coauthor research structured <project-id> --json` before retrying.
170
+ - Check operation status after timeouts, interruptions, network errors, or uncertain live-action results.
171
+ - Never print tokens, cookies, provider keys, service-role keys, or authorization headers.
198
172
 
199
173
  ## Security
200
174
 
@@ -204,38 +178,16 @@ Agents should:
204
178
  - Tokens are stored locally at `~/.coauthor/config.json`.
205
179
  - Run `coauthor auth logout` to revoke the current token and remove local credentials.
206
180
 
207
- ## Public API Stability
208
-
209
- The CLI talks to `/api/agent/v1/*`. Treat this as a public beta API surface:
210
-
211
- - Existing commands should keep stable JSON envelopes.
212
- - New behavior should be additive when possible.
213
- - Errors should stay structured and machine-readable with `--json`.
214
- - Server-side auth, ownership checks, scopes, and rate limits remain mandatory.
215
-
216
181
  ## Troubleshooting
217
182
 
218
- `No token configured` means the CLI has no credential for the selected base URL. Run `coauthor auth login --base-url <url>`.
183
+ `No token configured` means the CLI has no saved CoAuthor credential. Run `coauthor auth login`.
219
184
 
220
- `insufficient_scope` means the token does not include the required scope. For publish/export, log in again with `--with-publish`.
185
+ `insufficient_scope` means the token does not include the required scope. For publish/export, log in again with `coauthor auth login --with-publish`.
221
186
 
222
- `authorization_pending` during login is normal while the browser approval page is waiting for browser approval.
187
+ `authorization_pending` during login is normal while the browser approval page is waiting for approval.
223
188
 
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`.
189
+ `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`.
225
190
 
226
191
  `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
192
 
228
193
  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
-
230
- If `npx @clickminded/coauthor-cli help` fails while you are inside the CLI package source directory, run it from another directory or use:
231
-
232
- ```sh
233
- npm exec --package=@clickminded/coauthor-cli@latest -- coauthor-cli help
234
- ```
235
-
236
- ## For CoAuthor Maintainers
237
-
238
- 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:
239
-
240
- - `docs/agent-cli.md`
241
- - `docs/skills.md`
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) {
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,23 +27,27 @@ 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')
44
46
  return runResourceCommand('exports', action, input, context.client);
45
47
  if (scope === 'operation')
46
48
  return runOperationCommand(action, input, context.client);
49
+ if (scope === 'models')
50
+ return runModelsCommand(action, input, context.client);
47
51
  if (scope === 'skills')
48
52
  return runSkillsCommand(action, input);
49
53
  if (scope === 'help')
@@ -197,7 +201,8 @@ async function runChatCommand(action, input, client) {
197
201
  data: enrichChatResult(data, projectId, stage),
198
202
  };
199
203
  }
200
- async function runWorkflowCommand(action, input, client) {
204
+ async function runWorkflowCommand(action, input, context) {
205
+ const { client } = context;
201
206
  const projectId = requireProjectId(input);
202
207
  const projectPath = `projects/${encodeURIComponent(projectId)}/workflow`;
203
208
  if (action === 'show' || action === 'status') {
@@ -206,22 +211,29 @@ async function runWorkflowCommand(action, input, client) {
206
211
  }
207
212
  if (action === 'resume') {
208
213
  const target = normalizeWorkflowWaitTarget(getString(input.values, 'target') ?? getString(input.values, 'stage')) ?? 'draft';
214
+ if (target === 'research' && (getString(input.values, 'planning-model') || getString(input.values, 'writing-model'))) {
215
+ throw new Error('workflow resume --target research does not support --planning-model or --writing-model.');
216
+ }
217
+ const modelOverrides = modelOverrideBody(input);
209
218
  if (target === 'research') {
210
219
  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 };
220
+ return getBoolean(input.values, 'wait') ? waitForResearch(client, projectId, data, context.baseUrl) : { ok: true, data };
212
221
  }
213
222
  const researchStatus = await client.request({ path: `projects/${encodeURIComponent(projectId)}/research/status` });
214
223
  if (extractNestedString(researchStatus, ['run', 'status']) === 'paused_requires_key') {
224
+ if (modelOverrides.writingModel && !getBoolean(input.values, 'wait')) {
225
+ throw new Error('workflow resume --writing-model after a paused research run requires --wait so the writing model can be applied when draft starts.');
226
+ }
215
227
  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 };
228
+ return getBoolean(input.values, 'wait') ? waitForWorkflowDraft(client, projectId, data, context.baseUrl, modelOverrides) : { ok: true, data };
217
229
  }
218
230
  const draftStatus = await client.request({ path: `projects/${encodeURIComponent(projectId)}/draft/status` });
219
231
  if (getResponseString(draftStatus, 'phase') === 'paused_requires_key') {
220
- 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 };
232
+ const data = await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/draft/generate`, body: modelOverrides });
233
+ return getBoolean(input.values, 'wait') ? waitForDraft(client, projectId, data, context.baseUrl) : { ok: true, data };
222
234
  }
223
- 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 };
235
+ const data = await client.request({ method: 'POST', path: `${projectPath}/run`, body: { target, ...modelOverrides } });
236
+ return getBoolean(input.values, 'wait') ? waitForWorkflowDraft(client, projectId, data, context.baseUrl, modelOverrides) : { ok: true, data };
225
237
  }
226
238
  if (action === 'advance' || action === 'run' || action === 'rewind' || action === 'approve') {
227
239
  const body = withNamedOptions(parseJsonOption(input.values), input.values, [
@@ -231,6 +243,7 @@ async function runWorkflowCommand(action, input, client) {
231
243
  'reason',
232
244
  'briefing-mode',
233
245
  'max-brief-questions',
246
+ ...(action === 'advance' || action === 'run' ? ['planning-model', 'writing-model'] : []),
234
247
  ]);
235
248
  if (getBoolean(input.values, 'require-brief-review'))
236
249
  body.requireBriefReview = true;
@@ -247,9 +260,9 @@ async function runWorkflowCommand(action, input, client) {
247
260
  ?? getString(input.values, 'stage')
248
261
  ?? getResponseString(data, 'target'));
249
262
  if (target === 'research')
250
- return waitForResearch(client, projectId, data);
263
+ return waitForResearch(client, projectId, data, context.baseUrl);
251
264
  if (target === 'draft')
252
- return waitForWorkflowDraft(client, projectId, data);
265
+ return waitForWorkflowDraft(client, projectId, data, context.baseUrl, modelOverrideBody(input));
253
266
  }
254
267
  return { ok: true, data };
255
268
  }
@@ -260,6 +273,65 @@ async function runCreditsCommand(input, client) {
260
273
  const data = await client.request({ path: `projects/${encodeURIComponent(projectId)}/credits` });
261
274
  return { ok: true, data };
262
275
  }
276
+ async function runModelsCommand(action, input, client) {
277
+ if (!action || action === 'list') {
278
+ const data = await client.request({ path: 'models' });
279
+ return { ok: true, message: formatModelsList(data), data };
280
+ }
281
+ if (action === 'preferences') {
282
+ const subaction = input.command[2] ?? 'show';
283
+ if (subaction === 'show') {
284
+ const data = await client.request({ path: 'models/preferences' });
285
+ return { ok: true, data };
286
+ }
287
+ if (subaction === 'set') {
288
+ const body = modelOverrideBody(input);
289
+ if (!body.planningModel && !body.writingModel) {
290
+ throw new Error('Usage: coauthor models preferences set [--planning-model <id>] [--writing-model <id>]');
291
+ }
292
+ const data = await client.request({ method: 'POST', path: 'models/preferences', body });
293
+ return { ok: true, message: 'Model preferences updated', data };
294
+ }
295
+ }
296
+ throw new Error('Usage: coauthor models <list|preferences show|preferences set>');
297
+ }
298
+ function modelOverrideBody(input) {
299
+ const body = {};
300
+ const planningModel = getString(input.values, 'planning-model');
301
+ const writingModel = getString(input.values, 'writing-model');
302
+ if (planningModel)
303
+ body.planningModel = planningModel;
304
+ if (writingModel)
305
+ body.writingModel = writingModel;
306
+ return body;
307
+ }
308
+ function formatModelsList(data) {
309
+ if (!data || typeof data !== 'object' || Array.isArray(data))
310
+ return '';
311
+ const models = data.models;
312
+ if (!models || typeof models !== 'object' || Array.isArray(models))
313
+ return '';
314
+ const formatGroup = (label, value) => {
315
+ const entries = Array.isArray(value) ? value : [];
316
+ return [
317
+ label,
318
+ ...entries.map((entry) => {
319
+ if (!entry || typeof entry !== 'object' || Array.isArray(entry))
320
+ return null;
321
+ const id = entry.id;
322
+ const name = entry.label;
323
+ if (typeof id !== 'string')
324
+ return null;
325
+ return `- ${id}${typeof name === 'string' ? ` ${name}` : ''}`;
326
+ }).filter((line) => Boolean(line)),
327
+ ].join('\n');
328
+ };
329
+ return [
330
+ formatGroup('Planning models (--planning-model)', models.planning),
331
+ '',
332
+ formatGroup('Writing models (--writing-model)', models.writing),
333
+ ].join('\n');
334
+ }
263
335
  async function runArtifactCommand(artifact, action, input, client) {
264
336
  const projectId = requireProjectId(input);
265
337
  const basePath = `projects/${encodeURIComponent(projectId)}/${artifact}`;
@@ -270,21 +342,25 @@ async function runArtifactCommand(artifact, action, input, client) {
270
342
  if (action === 'generate' || action === 'save' || action === 'approve') {
271
343
  const body = action === 'approve'
272
344
  ? await buildArtifactApproveBody(artifact, input, client, basePath)
273
- : withNamedOptions(parseJsonOption(input.values), input.values, ['execution-token']);
345
+ : withNamedOptions(parseJsonOption(input.values), input.values, [
346
+ 'execution-token',
347
+ ...(action === 'generate' && (artifact === 'outline' || artifact === 'research-plan') ? ['planning-model'] : []),
348
+ ]);
274
349
  const path = action === 'save' ? basePath : `${basePath}/${action}`;
275
350
  const data = await client.request({ method: 'POST', path, body });
276
351
  return { ok: true, data };
277
352
  }
278
353
  throw new Error(`Usage: coauthor ${artifact} <show|generate|save|approve> <projectId>`);
279
354
  }
280
- async function runResearchCommand(action, input, client) {
355
+ async function runResearchCommand(action, input, context) {
356
+ const { client } = context;
281
357
  const projectId = requireProjectId(input);
282
358
  const basePath = `projects/${encodeURIComponent(projectId)}/research`;
283
359
  if (action === 'run') {
284
360
  const body = withNamedOptions(parseJsonOption(input.values), input.values, ['execution-token']);
285
361
  const data = await client.request({ method: 'POST', path: `${basePath}/run`, body });
286
362
  if (getBoolean(input.values, 'wait')) {
287
- return waitForResearch(client, projectId, data);
363
+ return waitForResearch(client, projectId, data, context.baseUrl);
288
364
  }
289
365
  return { ok: true, data };
290
366
  }
@@ -296,14 +372,15 @@ async function runResearchCommand(action, input, client) {
296
372
  }
297
373
  throw new Error('Usage: coauthor research <run|status|structured> <projectId>');
298
374
  }
299
- async function runDraftCommand(action, input, client) {
375
+ async function runDraftCommand(action, input, context) {
376
+ const { client } = context;
300
377
  const projectId = requireProjectId(input);
301
378
  const basePath = `projects/${encodeURIComponent(projectId)}/draft`;
302
379
  if (action === 'generate') {
303
- const body = withNamedOptions(parseJsonOption(input.values), input.values, ['execution-token']);
380
+ const body = withNamedOptions(parseJsonOption(input.values), input.values, ['execution-token', 'writing-model']);
304
381
  const data = await client.request({ method: 'POST', path: `${basePath}/generate`, body });
305
382
  if (getBoolean(input.values, 'wait')) {
306
- return waitForDraft(client, projectId, data);
383
+ return waitForDraft(client, projectId, data, context.baseUrl);
307
384
  }
308
385
  return { ok: true, data };
309
386
  }
@@ -336,7 +413,7 @@ async function runResourceCommand(resource, action, input, client) {
336
413
  const data = await client.request({ path: `${basePath}/status` });
337
414
  return { ok: true, data };
338
415
  }
339
- if (resource === 'threads') {
416
+ if (resource === 'threads' || resource === 'slideshows') {
340
417
  const data = await client.request({ path: resourceId ? `${basePath}/${encodeURIComponent(resourceId)}` : basePath });
341
418
  return { ok: true, data };
342
419
  }
@@ -381,6 +458,7 @@ async function runResourceCommand(resource, action, input, client) {
381
458
  'execution-token',
382
459
  'grounding-mode',
383
460
  'image-generation-model',
461
+ ...(resource === 'threads' && action === 'generate' ? ['writing-model'] : []),
384
462
  'edit-prompt',
385
463
  ]);
386
464
  const path = action === 'create' && resource !== 'threads' ? basePath : `${basePath}/${action}`;
@@ -631,7 +709,7 @@ function openBrowser(url) {
631
709
  });
632
710
  child.unref();
633
711
  }
634
- async function waitForResearch(client, projectId, initialData) {
712
+ async function waitForResearch(client, projectId, initialData, baseUrl) {
635
713
  const deadline = Date.now() + waitTimeoutMs(20 * 60_000);
636
714
  const pollMs = waitPollMs();
637
715
  let latest = initialData;
@@ -644,7 +722,7 @@ async function waitForResearch(client, projectId, initialData) {
644
722
  if (status === 'failed')
645
723
  throw new Error(extractNestedString(latest, ['run', 'error_message']) ?? 'Research failed');
646
724
  if (status === 'paused_requires_key') {
647
- return requiresKeyPauseResult(projectId, 'research', extractNestedString(latest, ['run', 'error_message']) ?? 'Research paused: add the required API key to continue.', latest);
725
+ return requiresKeyPauseResult(projectId, 'research', extractNestedString(latest, ['run', 'error_message']) ?? 'Research paused: add the required API key to continue.', latest, baseUrl);
648
726
  }
649
727
  const stale = researchRunningStaleResult(projectId, latest, null, initialData);
650
728
  if (stale)
@@ -652,7 +730,7 @@ async function waitForResearch(client, projectId, initialData) {
652
730
  }
653
731
  return waitTimedOutResult(projectId, 'research', initialData, latest, null);
654
732
  }
655
- async function waitForDraft(client, projectId, initialData) {
733
+ async function waitForDraft(client, projectId, initialData, baseUrl) {
656
734
  const deadline = Date.now() + waitTimeoutMs(20 * 60_000);
657
735
  const pollMs = waitPollMs();
658
736
  let latest = initialData;
@@ -665,13 +743,13 @@ async function waitForDraft(client, projectId, initialData) {
665
743
  return { ok: true, message: 'Draft completed', data: latest };
666
744
  }
667
745
  if (phase === 'paused_requires_key')
668
- return requiresKeyPauseResult(projectId, 'draft', getResponseString(latest, 'message') ?? 'Draft paused: add the required API key to continue.', latest);
746
+ return requiresKeyPauseResult(projectId, 'draft', getResponseString(latest, 'message') ?? 'Draft paused: add the required API key to continue.', latest, baseUrl);
669
747
  if (phase === 'failed')
670
748
  throw new Error(getResponseString(latest, 'message') ?? 'Draft generation failed');
671
749
  }
672
750
  return waitTimedOutResult(projectId, 'draft', initialData, null, latest);
673
751
  }
674
- async function waitForWorkflowDraft(client, projectId, initialData) {
752
+ async function waitForWorkflowDraft(client, projectId, initialData, baseUrl, modelOverrides = {}) {
675
753
  const deadline = Date.now() + waitTimeoutMs(40 * 60_000);
676
754
  const pollMs = waitPollMs();
677
755
  let latestDraft = initialData;
@@ -702,7 +780,7 @@ async function waitForWorkflowDraft(client, projectId, initialData) {
702
780
  workflow: initialData,
703
781
  research_status: latestResearch,
704
782
  draft_status: latestDraft,
705
- });
783
+ }, baseUrl);
706
784
  }
707
785
  latestResearch = await client.request({ path: `projects/${encodeURIComponent(projectId)}/research/status` });
708
786
  const researchStatus = extractNestedString(latestResearch, ['run', 'status']);
@@ -714,7 +792,7 @@ async function waitForWorkflowDraft(client, projectId, initialData) {
714
792
  workflow: initialData,
715
793
  research_status: latestResearch,
716
794
  draft_status: latestDraft,
717
- });
795
+ }, baseUrl);
718
796
  }
719
797
  const stale = researchRunningStaleResult(projectId, latestResearch, latestDraft, initialData);
720
798
  if (stale)
@@ -728,7 +806,7 @@ async function waitForWorkflowDraft(client, projectId, initialData) {
728
806
  draftGenerate = await client.request({
729
807
  method: 'POST',
730
808
  path: `projects/${encodeURIComponent(projectId)}/draft/generate`,
731
- body: {},
809
+ body: modelOverrides.writingModel ? { writingModel: modelOverrides.writingModel } : {},
732
810
  });
733
811
  }
734
812
  catch (error) {
@@ -901,14 +979,15 @@ function enrichResearchStatus(data) {
901
979
  },
902
980
  };
903
981
  }
904
- function requiresKeyPauseResult(projectId, target, message, data) {
982
+ function requiresKeyPauseResult(projectId, target, message, data, baseUrl) {
905
983
  const resumeCommand = `coauthor workflow resume ${projectId} --target ${target} --wait --json`;
984
+ const settingsUrl = new URL('settings/ai', normalizeBaseUrl(baseUrl)).toString();
906
985
  return {
907
986
  ok: false,
908
987
  status: 'requires_key',
909
988
  exitCode: 2,
910
- message: `${message}\nOpen AI settings: /settings/ai\nResume: ${resumeCommand}`,
911
- settings_url: '/settings/ai',
989
+ message: `${message}\nOpen AI settings: ${settingsUrl}\nResume: ${resumeCommand}`,
990
+ settings_url: settingsUrl,
912
991
  resume_command: resumeCommand,
913
992
  data,
914
993
  };
@@ -962,6 +1041,8 @@ function resourceCommandName(resource) {
962
1041
  return 'image';
963
1042
  if (resource === 'threads')
964
1043
  return 'thread';
1044
+ if (resource === 'slideshows')
1045
+ return 'slideshow';
965
1046
  if (resource === 'exports')
966
1047
  return 'export';
967
1048
  if (resource === 'operations')
@@ -990,10 +1071,12 @@ export function helpResult(command = []) {
990
1071
  ' workflow run/advance supports --briefing-mode auto|strict|off and --require-brief-review',
991
1072
  ' image list|status|show|generate|edit',
992
1073
  ' thread list|show|create|generate|save',
1074
+ ' slideshow show|save',
993
1075
  ' publish thread',
994
1076
  ' export blog|clickminded',
995
1077
  ' operation list|show|status',
996
1078
  ' credits',
1079
+ ' models list|preferences show|preferences set',
997
1080
  ' skills list|install',
998
1081
  ' skills install supports codex|claude|cursor|agents|all',
999
1082
  ].join('\n'),
@@ -1008,20 +1091,30 @@ function commandHelp(command) {
1008
1091
  'Creates a project. When --topic or --audience is provided, CoAuthor seeds the saved contract so workflow briefing review can use that context.',
1009
1092
  ].join('\n'),
1010
1093
  'workflow run': [
1011
- 'Usage: coauthor workflow run <project-id> --target <outline|research|draft> [--wait] [--briefing-mode auto|strict|off] [--json]',
1094
+ 'Usage: coauthor workflow run <project-id> --target <outline|research|draft> [--planning-model <id>] [--writing-model <id>] [--wait] [--briefing-mode auto|strict|off] [--json]',
1012
1095
  '',
1013
1096
  '--wait blocks until the requested target completes, pauses for a key, fails, reports stale research, or times out.',
1014
1097
  ].join('\n'),
1015
1098
  'workflow resume': [
1016
- 'Usage: coauthor workflow resume <project-id> [--target <research|draft>] [--wait] [--json]',
1099
+ 'Usage: coauthor workflow resume <project-id> [--target <research|draft>] [--planning-model <id>] [--writing-model <id>] [--wait] [--json]',
1017
1100
  '',
1018
1101
  'Use after an interruption, timeout, or requires_key pause. For draft targets, --wait continues through research and draft generation.',
1019
1102
  ].join('\n'),
1020
1103
  'draft generate': [
1021
- 'Usage: coauthor draft generate <project-id> [--wait] [--json]',
1104
+ 'Usage: coauthor draft generate <project-id> [--writing-model <id>] [--wait] [--json]',
1022
1105
  '',
1023
1106
  'Requires project_state "research_structured". If research is still running or structuring, inspect the returned status and next commands.',
1024
1107
  ].join('\n'),
1108
+ 'models list': [
1109
+ 'Usage: coauthor models list [--json]',
1110
+ '',
1111
+ 'Lists user-visible planning and writing model IDs for --planning-model and --writing-model.',
1112
+ ].join('\n'),
1113
+ 'models preferences': [
1114
+ 'Usage: coauthor models preferences <show|set> [--planning-model <id>] [--writing-model <id>] [--json]',
1115
+ '',
1116
+ 'Shows or updates saved primary planning/writing model preferences while preserving fallback order.',
1117
+ ].join('\n'),
1025
1118
  'draft get': [
1026
1119
  'Usage: coauthor draft get <project-id> [--format json|markdown|html|text] [--json]',
1027
1120
  '',
@@ -1037,6 +1130,11 @@ function commandHelp(command) {
1037
1130
  '',
1038
1131
  'Image generation requires an image placeholder from coauthor image list. Draft generation creates placeholders.',
1039
1132
  ].join('\n'),
1133
+ 'thread generate': [
1134
+ 'Usage: coauthor thread generate <project-id> [--writing-model <id>] [--json]',
1135
+ '',
1136
+ 'Generates a social thread from the saved draft.',
1137
+ ].join('\n'),
1040
1138
  };
1041
1139
  return help[key] ?? null;
1042
1140
  }
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';
@@ -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
@@ -54,6 +54,8 @@ export function parseCliArgs(argv) {
54
54
  limit: { type: 'string' },
55
55
  cursor: { type: 'string' },
56
56
  'execution-token': { type: 'string' },
57
+ 'planning-model': { type: 'string' },
58
+ 'writing-model': { type: 'string' },
57
59
  },
58
60
  });
59
61
  const positionals = parsed.positionals;
@@ -104,11 +106,15 @@ function commandLength(positionals) {
104
106
  return second && ['show', 'list'].includes(second) ? 2 : 1;
105
107
  if (first === 'skills')
106
108
  return second && ['list', 'install'].includes(second) ? 2 : 1;
109
+ if (first === 'models')
110
+ return second && ['list', 'preferences'].includes(second)
111
+ ? (second === 'preferences' && positionals[2] && ['show', 'set'].includes(positionals[2]) ? 3 : 2)
112
+ : 1;
107
113
  if (first === 'workflow')
108
114
  return second ? 2 : 1;
109
115
  if (first === 'credits')
110
116
  return 1;
111
- if (['contract', 'outline', 'research-plan', 'research', 'draft', 'image', 'thread', 'publish', 'export', 'operation'].includes(first ?? ''))
117
+ if (['contract', 'outline', 'research-plan', 'research', 'draft', 'image', 'thread', 'slideshow', 'publish', 'export', 'operation'].includes(first ?? ''))
112
118
  return second ? 2 : 1;
113
119
  return 1;
114
120
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.11",
3
+ "version": "0.0.13",
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,8 +9,8 @@ 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"`.
@@ -22,6 +22,8 @@ This skill guides agent use of the CoAuthor CLI.
22
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
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.
24
24
  - Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
25
+ - Use `coauthor models list` to see user-visible planning and writing models. Use `--planning-model <id>` for outline/research-plan/workflow planning overrides and `--writing-model <id>` for draft/thread/workflow writing overrides; do not use a global `--model`.
26
+ - Use `coauthor models preferences show|set` to inspect or update saved planning/writing preferences. Internal structuring models are not exposed through the CLI.
25
27
  - After a timeout, interruption, network error, or unclear result, check operation status before retrying.
26
28
  - `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.
27
29
 
@@ -9,8 +9,8 @@ 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"`.
@@ -22,6 +22,8 @@ This skill guides agent use of the CoAuthor CLI.
22
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
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.
24
24
  - Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
25
+ - Use `coauthor models list` to see user-visible planning and writing models. Use `--planning-model <id>` for outline/research-plan/workflow planning overrides and `--writing-model <id>` for draft/thread/workflow writing overrides; do not use a global `--model`.
26
+ - Use `coauthor models preferences show|set` to inspect or update saved planning/writing preferences. Internal structuring models are not exposed through the CLI.
25
27
  - After a timeout, interruption, network error, or unclear result, check operation status before retrying.
26
28
  - `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.
27
29
 
@@ -9,8 +9,8 @@ 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"`.
@@ -22,6 +22,8 @@ This skill guides agent use of the CoAuthor CLI.
22
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
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.
24
24
  - Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
25
+ - Use `coauthor models list` to see user-visible planning and writing models. Use `--planning-model <id>` for outline/research-plan/workflow planning overrides and `--writing-model <id>` for draft/thread/workflow writing overrides; do not use a global `--model`.
26
+ - Use `coauthor models preferences show|set` to inspect or update saved planning/writing preferences. Internal structuring models are not exposed through the CLI.
25
27
  - After a timeout, interruption, network error, or unclear result, check operation status before retrying.
26
28
  - `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.
27
29
 
@@ -6,8 +6,8 @@ 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"`.
@@ -19,6 +19,8 @@ alwaysApply: true
19
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
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.
21
21
  - Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
22
+ - Use `coauthor models list` to see user-visible planning and writing models. Use `--planning-model <id>` for outline/research-plan/workflow planning overrides and `--writing-model <id>` for draft/thread/workflow writing overrides; do not use a global `--model`.
23
+ - Use `coauthor models preferences show|set` to inspect or update saved planning/writing preferences. Internal structuring models are not exposed through the CLI.
22
24
  - After timeout, interruption, network error, or ambiguous output, check operation status before retrying or reporting success.
23
25
  - `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.
24
26
  - Never print tokens, service-role keys, cookies, or authorization headers.