@clickminded/coauthor-cli 0.0.12 → 0.0.14

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
@@ -81,6 +81,7 @@ Create and inspect projects:
81
81
 
82
82
  ```sh
83
83
  coauthor project create --title "Post title" --topic "Post brief" --audience "Target reader" --json
84
+ coauthor project create --contract '{"topic":"Post topic","angle":"Specific angle","target_audience":"Target reader","must_include":["Point to cover"]}' --json
84
85
  coauthor project list --json
85
86
  coauthor project show <project-id> --json
86
87
  coauthor workspace show <project-id> --json
@@ -92,18 +93,27 @@ Work with the project:
92
93
  coauthor chat <project-id> --message "Refine the angle for this post" --json
93
94
  coauthor workflow status <project-id> --json
94
95
  coauthor workflow run <project-id> --target draft --wait --json
96
+ coauthor workflow run <project-id> --target draft --planning-model gpt-5.5 --writing-model gpt-5.4 --wait --json
95
97
  coauthor workflow resume <project-id> --target draft --wait --json
96
98
  coauthor credits <project-id> --json
97
99
  ```
98
100
 
101
+ List and save text model preferences:
102
+
103
+ ```sh
104
+ coauthor models list
105
+ coauthor models preferences show --json
106
+ coauthor models preferences set --planning-model gpt-5.5 --writing-model gpt-5.4 --json
107
+ ```
108
+
99
109
  Read or generate artifacts:
100
110
 
101
111
  ```sh
102
112
  coauthor contract show <project-id> --json
103
- coauthor outline generate <project-id> --json
104
- coauthor research-plan generate <project-id> --json
113
+ coauthor outline generate <project-id> --planning-model claude-opus-4-8 --json
114
+ coauthor research-plan generate <project-id> --planning-model gpt-5.5 --json
105
115
  coauthor research run <project-id> --wait --json
106
- coauthor draft generate <project-id> --wait --json
116
+ coauthor draft generate <project-id> --writing-model gpt-5.4 --wait --json
107
117
  coauthor draft get <project-id> --format markdown --json
108
118
  ```
109
119
 
@@ -112,7 +122,7 @@ Images and social content:
112
122
  ```sh
113
123
  coauthor image list <project-id> --json
114
124
  coauthor image generate <project-id> --placeholder-id <placeholder-id> --prompt "Image direction" --json
115
- coauthor thread generate <project-id> --json
125
+ coauthor thread generate <project-id> --writing-model gpt-5.4 --json
116
126
  ```
117
127
 
118
128
  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.
@@ -144,9 +154,12 @@ Then run live actions only when you mean to publish or export:
144
154
  coauthor publish thread <project-id> --yes --json
145
155
  coauthor export blog <project-id> --yes --slug "post-slug" --json
146
156
  coauthor export clickminded <project-id> --yes --json
157
+ coauthor export wordpress <project-id> --yes --slug "post-slug" --json
147
158
  coauthor operation status <operation-key> --json
148
159
  ```
149
160
 
161
+ For multiple WordPress connections, include `--connection-id <id>`.
162
+
150
163
  Live actions require both publish scope and `--yes`.
151
164
 
152
165
  ## Agent Usage Rules
package/dist/commands.js CHANGED
@@ -46,6 +46,8 @@ export async function runCommand(input, context) {
46
46
  return runResourceCommand('exports', action, input, context.client);
47
47
  if (scope === 'operation')
48
48
  return runOperationCommand(action, input, context.client);
49
+ if (scope === 'models')
50
+ return runModelsCommand(action, input, context.client);
49
51
  if (scope === 'skills')
50
52
  return runSkillsCommand(action, input);
51
53
  if (scope === 'help')
@@ -146,6 +148,12 @@ async function runAuthCommand(action, input, context) {
146
148
  async function runProjectCommand(action, input, client) {
147
149
  if (action === 'create') {
148
150
  const body = withNamedOptions(parseJsonOption(input.values), input.values, ['title', 'topic', 'audience']);
151
+ const rawContract = getString(input.values, 'contract');
152
+ if (rawContract !== undefined) {
153
+ if (!rawContract.trim())
154
+ throw new Error('--contract must be a JSON object');
155
+ body.contract = parseJsonOption(input.values, 'contract');
156
+ }
149
157
  const data = await client.request({ method: 'POST', path: 'projects', body });
150
158
  return { ok: true, message: 'Project created', data };
151
159
  }
@@ -209,22 +217,29 @@ async function runWorkflowCommand(action, input, context) {
209
217
  }
210
218
  if (action === 'resume') {
211
219
  const target = normalizeWorkflowWaitTarget(getString(input.values, 'target') ?? getString(input.values, 'stage')) ?? 'draft';
220
+ if (target === 'research' && (getString(input.values, 'planning-model') || getString(input.values, 'writing-model'))) {
221
+ throw new Error('workflow resume --target research does not support --planning-model or --writing-model.');
222
+ }
223
+ const modelOverrides = modelOverrideBody(input);
212
224
  if (target === 'research') {
213
225
  const data = await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/research/run`, body: {} });
214
226
  return getBoolean(input.values, 'wait') ? waitForResearch(client, projectId, data, context.baseUrl) : { ok: true, data };
215
227
  }
216
228
  const researchStatus = await client.request({ path: `projects/${encodeURIComponent(projectId)}/research/status` });
217
229
  if (extractNestedString(researchStatus, ['run', 'status']) === 'paused_requires_key') {
230
+ if (modelOverrides.writingModel && !getBoolean(input.values, 'wait')) {
231
+ throw new Error('workflow resume --writing-model after a paused research run requires --wait so the writing model can be applied when draft starts.');
232
+ }
218
233
  const data = await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/research/run`, body: {} });
219
- return getBoolean(input.values, 'wait') ? waitForWorkflowDraft(client, projectId, data, context.baseUrl) : { ok: true, data };
234
+ return getBoolean(input.values, 'wait') ? waitForWorkflowDraft(client, projectId, data, context.baseUrl, modelOverrides) : { ok: true, data };
220
235
  }
221
236
  const draftStatus = await client.request({ path: `projects/${encodeURIComponent(projectId)}/draft/status` });
222
237
  if (getResponseString(draftStatus, 'phase') === 'paused_requires_key') {
223
- const data = await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/draft/generate`, body: {} });
238
+ const data = await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/draft/generate`, body: modelOverrides });
224
239
  return getBoolean(input.values, 'wait') ? waitForDraft(client, projectId, data, context.baseUrl) : { ok: true, data };
225
240
  }
226
- const data = await client.request({ method: 'POST', path: `${projectPath}/run`, body: { target } });
227
- return getBoolean(input.values, 'wait') ? waitForWorkflowDraft(client, projectId, data, context.baseUrl) : { ok: true, data };
241
+ const data = await client.request({ method: 'POST', path: `${projectPath}/run`, body: { target, ...modelOverrides } });
242
+ return getBoolean(input.values, 'wait') ? waitForWorkflowDraft(client, projectId, data, context.baseUrl, modelOverrides) : { ok: true, data };
228
243
  }
229
244
  if (action === 'advance' || action === 'run' || action === 'rewind' || action === 'approve') {
230
245
  const body = withNamedOptions(parseJsonOption(input.values), input.values, [
@@ -234,6 +249,7 @@ async function runWorkflowCommand(action, input, context) {
234
249
  'reason',
235
250
  'briefing-mode',
236
251
  'max-brief-questions',
252
+ ...(action === 'advance' || action === 'run' ? ['planning-model', 'writing-model'] : []),
237
253
  ]);
238
254
  if (getBoolean(input.values, 'require-brief-review'))
239
255
  body.requireBriefReview = true;
@@ -252,7 +268,7 @@ async function runWorkflowCommand(action, input, context) {
252
268
  if (target === 'research')
253
269
  return waitForResearch(client, projectId, data, context.baseUrl);
254
270
  if (target === 'draft')
255
- return waitForWorkflowDraft(client, projectId, data, context.baseUrl);
271
+ return waitForWorkflowDraft(client, projectId, data, context.baseUrl, modelOverrideBody(input));
256
272
  }
257
273
  return { ok: true, data };
258
274
  }
@@ -263,6 +279,65 @@ async function runCreditsCommand(input, client) {
263
279
  const data = await client.request({ path: `projects/${encodeURIComponent(projectId)}/credits` });
264
280
  return { ok: true, data };
265
281
  }
282
+ async function runModelsCommand(action, input, client) {
283
+ if (!action || action === 'list') {
284
+ const data = await client.request({ path: 'models' });
285
+ return { ok: true, message: formatModelsList(data), data };
286
+ }
287
+ if (action === 'preferences') {
288
+ const subaction = input.command[2] ?? 'show';
289
+ if (subaction === 'show') {
290
+ const data = await client.request({ path: 'models/preferences' });
291
+ return { ok: true, data };
292
+ }
293
+ if (subaction === 'set') {
294
+ const body = modelOverrideBody(input);
295
+ if (!body.planningModel && !body.writingModel) {
296
+ throw new Error('Usage: coauthor models preferences set [--planning-model <id>] [--writing-model <id>]');
297
+ }
298
+ const data = await client.request({ method: 'POST', path: 'models/preferences', body });
299
+ return { ok: true, message: 'Model preferences updated', data };
300
+ }
301
+ }
302
+ throw new Error('Usage: coauthor models <list|preferences show|preferences set>');
303
+ }
304
+ function modelOverrideBody(input) {
305
+ const body = {};
306
+ const planningModel = getString(input.values, 'planning-model');
307
+ const writingModel = getString(input.values, 'writing-model');
308
+ if (planningModel)
309
+ body.planningModel = planningModel;
310
+ if (writingModel)
311
+ body.writingModel = writingModel;
312
+ return body;
313
+ }
314
+ function formatModelsList(data) {
315
+ if (!data || typeof data !== 'object' || Array.isArray(data))
316
+ return '';
317
+ const models = data.models;
318
+ if (!models || typeof models !== 'object' || Array.isArray(models))
319
+ return '';
320
+ const formatGroup = (label, value) => {
321
+ const entries = Array.isArray(value) ? value : [];
322
+ return [
323
+ label,
324
+ ...entries.map((entry) => {
325
+ if (!entry || typeof entry !== 'object' || Array.isArray(entry))
326
+ return null;
327
+ const id = entry.id;
328
+ const name = entry.label;
329
+ if (typeof id !== 'string')
330
+ return null;
331
+ return `- ${id}${typeof name === 'string' ? ` ${name}` : ''}`;
332
+ }).filter((line) => Boolean(line)),
333
+ ].join('\n');
334
+ };
335
+ return [
336
+ formatGroup('Planning models (--planning-model)', models.planning),
337
+ '',
338
+ formatGroup('Writing models (--writing-model)', models.writing),
339
+ ].join('\n');
340
+ }
266
341
  async function runArtifactCommand(artifact, action, input, client) {
267
342
  const projectId = requireProjectId(input);
268
343
  const basePath = `projects/${encodeURIComponent(projectId)}/${artifact}`;
@@ -273,7 +348,10 @@ async function runArtifactCommand(artifact, action, input, client) {
273
348
  if (action === 'generate' || action === 'save' || action === 'approve') {
274
349
  const body = action === 'approve'
275
350
  ? await buildArtifactApproveBody(artifact, input, client, basePath)
276
- : withNamedOptions(parseJsonOption(input.values), input.values, ['execution-token']);
351
+ : withNamedOptions(parseJsonOption(input.values), input.values, [
352
+ 'execution-token',
353
+ ...(action === 'generate' && (artifact === 'outline' || artifact === 'research-plan') ? ['planning-model'] : []),
354
+ ]);
277
355
  const path = action === 'save' ? basePath : `${basePath}/${action}`;
278
356
  const data = await client.request({ method: 'POST', path, body });
279
357
  return { ok: true, data };
@@ -305,7 +383,7 @@ async function runDraftCommand(action, input, context) {
305
383
  const projectId = requireProjectId(input);
306
384
  const basePath = `projects/${encodeURIComponent(projectId)}/draft`;
307
385
  if (action === 'generate') {
308
- const body = withNamedOptions(parseJsonOption(input.values), input.values, ['execution-token']);
386
+ const body = withNamedOptions(parseJsonOption(input.values), input.values, ['execution-token', 'writing-model']);
309
387
  const data = await client.request({ method: 'POST', path: `${basePath}/generate`, body });
310
388
  if (getBoolean(input.values, 'wait')) {
311
389
  return waitForDraft(client, projectId, data, context.baseUrl);
@@ -358,7 +436,7 @@ async function runResourceCommand(resource, action, input, client) {
358
436
  const data = await client.request({ method: 'POST', path: `${basePath}/thread`, body: parseJsonOption(input.values) });
359
437
  return { ok: true, data };
360
438
  }
361
- if (resource === 'exports' && (action === 'blog' || action === 'clickminded')) {
439
+ if (resource === 'exports' && (action === 'blog' || action === 'clickminded' || action === 'wordpress')) {
362
440
  if (!projectId)
363
441
  throw new Error(`Missing project id for export ${action}`);
364
442
  if (!getBoolean(input.values, 'yes'))
@@ -367,8 +445,13 @@ async function runResourceCommand(resource, action, input, client) {
367
445
  'slug',
368
446
  'status',
369
447
  'permalink',
448
+ 'connection-id',
370
449
  'format',
371
450
  ]);
451
+ if (typeof body.connectionId === 'string') {
452
+ body.integration_id = body.connectionId;
453
+ delete body.connectionId;
454
+ }
372
455
  const data = await client.request({ method: 'POST', path: `${basePath}/${action}`, body });
373
456
  return { ok: true, data };
374
457
  }
@@ -386,6 +469,7 @@ async function runResourceCommand(resource, action, input, client) {
386
469
  'execution-token',
387
470
  'grounding-mode',
388
471
  'image-generation-model',
472
+ ...(resource === 'threads' && action === 'generate' ? ['writing-model'] : []),
389
473
  'edit-prompt',
390
474
  ]);
391
475
  const path = action === 'create' && resource !== 'threads' ? basePath : `${basePath}/${action}`;
@@ -676,7 +760,7 @@ async function waitForDraft(client, projectId, initialData, baseUrl) {
676
760
  }
677
761
  return waitTimedOutResult(projectId, 'draft', initialData, null, latest);
678
762
  }
679
- async function waitForWorkflowDraft(client, projectId, initialData, baseUrl) {
763
+ async function waitForWorkflowDraft(client, projectId, initialData, baseUrl, modelOverrides = {}) {
680
764
  const deadline = Date.now() + waitTimeoutMs(40 * 60_000);
681
765
  const pollMs = waitPollMs();
682
766
  let latestDraft = initialData;
@@ -733,7 +817,7 @@ async function waitForWorkflowDraft(client, projectId, initialData, baseUrl) {
733
817
  draftGenerate = await client.request({
734
818
  method: 'POST',
735
819
  path: `projects/${encodeURIComponent(projectId)}/draft/generate`,
736
- body: {},
820
+ body: modelOverrides.writingModel ? { writingModel: modelOverrides.writingModel } : {},
737
821
  });
738
822
  }
739
823
  catch (error) {
@@ -1000,9 +1084,10 @@ export function helpResult(command = []) {
1000
1084
  ' thread list|show|create|generate|save',
1001
1085
  ' slideshow show|save',
1002
1086
  ' publish thread',
1003
- ' export blog|clickminded',
1087
+ ' export blog|clickminded|wordpress',
1004
1088
  ' operation list|show|status',
1005
1089
  ' credits',
1090
+ ' models list|preferences show|preferences set',
1006
1091
  ' skills list|install',
1007
1092
  ' skills install supports codex|claude|cursor|agents|all',
1008
1093
  ].join('\n'),
@@ -1012,25 +1097,36 @@ function commandHelp(command) {
1012
1097
  const key = command.join(' ');
1013
1098
  const help = {
1014
1099
  'project create': [
1015
- 'Usage: coauthor project create [--title <title>] [--topic <brief>] [--audience <audience>] [--json]',
1100
+ 'Usage: coauthor project create [--title <title>] [--topic <brief>] [--audience <audience>] [--contract <json>] [--json]',
1016
1101
  '',
1017
1102
  'Creates a project. When --topic or --audience is provided, CoAuthor seeds the saved contract so workflow briefing review can use that context.',
1103
+ '--contract accepts a JSON editorial contract object. Top-level --topic and --audience fill missing contract topic/audience fields.',
1018
1104
  ].join('\n'),
1019
1105
  'workflow run': [
1020
- 'Usage: coauthor workflow run <project-id> --target <outline|research|draft> [--wait] [--briefing-mode auto|strict|off] [--json]',
1106
+ 'Usage: coauthor workflow run <project-id> --target <outline|research|draft> [--planning-model <id>] [--writing-model <id>] [--wait] [--briefing-mode auto|strict|off] [--json]',
1021
1107
  '',
1022
1108
  '--wait blocks until the requested target completes, pauses for a key, fails, reports stale research, or times out.',
1023
1109
  ].join('\n'),
1024
1110
  'workflow resume': [
1025
- 'Usage: coauthor workflow resume <project-id> [--target <research|draft>] [--wait] [--json]',
1111
+ 'Usage: coauthor workflow resume <project-id> [--target <research|draft>] [--planning-model <id>] [--writing-model <id>] [--wait] [--json]',
1026
1112
  '',
1027
1113
  'Use after an interruption, timeout, or requires_key pause. For draft targets, --wait continues through research and draft generation.',
1028
1114
  ].join('\n'),
1029
1115
  'draft generate': [
1030
- 'Usage: coauthor draft generate <project-id> [--wait] [--json]',
1116
+ 'Usage: coauthor draft generate <project-id> [--writing-model <id>] [--wait] [--json]',
1031
1117
  '',
1032
1118
  'Requires project_state "research_structured". If research is still running or structuring, inspect the returned status and next commands.',
1033
1119
  ].join('\n'),
1120
+ 'models list': [
1121
+ 'Usage: coauthor models list [--json]',
1122
+ '',
1123
+ 'Lists user-visible planning and writing model IDs for --planning-model and --writing-model.',
1124
+ ].join('\n'),
1125
+ 'models preferences': [
1126
+ 'Usage: coauthor models preferences <show|set> [--planning-model <id>] [--writing-model <id>] [--json]',
1127
+ '',
1128
+ 'Shows or updates saved primary planning/writing model preferences while preserving fallback order.',
1129
+ ].join('\n'),
1034
1130
  'draft get': [
1035
1131
  'Usage: coauthor draft get <project-id> [--format json|markdown|html|text] [--json]',
1036
1132
  '',
@@ -1046,6 +1142,11 @@ function commandHelp(command) {
1046
1142
  '',
1047
1143
  'Image generation requires an image placeholder from coauthor image list. Draft generation creates placeholders.',
1048
1144
  ].join('\n'),
1145
+ 'thread generate': [
1146
+ 'Usage: coauthor thread generate <project-id> [--writing-model <id>] [--json]',
1147
+ '',
1148
+ 'Generates a social thread from the saved draft.',
1149
+ ].join('\n'),
1049
1150
  };
1050
1151
  return help[key] ?? null;
1051
1152
  }
package/dist/parser.js CHANGED
@@ -34,6 +34,7 @@ export function parseCliArgs(argv) {
34
34
  title: { type: 'string' },
35
35
  topic: { type: 'string' },
36
36
  audience: { type: 'string' },
37
+ contract: { type: 'string' },
37
38
  project: { type: 'string' },
38
39
  id: { type: 'string' },
39
40
  'placeholder-id': { type: 'string' },
@@ -50,10 +51,13 @@ export function parseCliArgs(argv) {
50
51
  image: { type: 'string' },
51
52
  slug: { type: 'string' },
52
53
  permalink: { type: 'string' },
54
+ 'connection-id': { type: 'string' },
53
55
  status: { type: 'string' },
54
56
  limit: { type: 'string' },
55
57
  cursor: { type: 'string' },
56
58
  'execution-token': { type: 'string' },
59
+ 'planning-model': { type: 'string' },
60
+ 'writing-model': { type: 'string' },
57
61
  },
58
62
  });
59
63
  const positionals = parsed.positionals;
@@ -104,6 +108,10 @@ function commandLength(positionals) {
104
108
  return second && ['show', 'list'].includes(second) ? 2 : 1;
105
109
  if (first === 'skills')
106
110
  return second && ['list', 'install'].includes(second) ? 2 : 1;
111
+ if (first === 'models')
112
+ return second && ['list', 'preferences'].includes(second)
113
+ ? (second === 'preferences' && positionals[2] && ['show', 'set'].includes(positionals[2]) ? 3 : 2)
114
+ : 1;
107
115
  if (first === 'workflow')
108
116
  return second ? 2 : 1;
109
117
  if (first === 'credits')
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.12",
3
+ "version": "0.0.14",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -22,9 +22,24 @@ 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
 
30
+ ## Project Briefing
31
+
32
+ - For simple starts, use `coauthor project create --title "..." --topic "prose brief" --audience "target reader" --json`.
33
+ - When you know the editorial contract fields, prefer `coauthor project create --contract '<json>' --json` instead of cramming structured data into `--topic`.
34
+ - Keep `--topic` as a plain prose brief. Do not pass JSON through `--topic`.
35
+ - `--contract` accepts a JSON object with editorial contract fields such as `topic`, `angle`, `target_audience`, `core_promise`, `format`, `reading_commitment`, `length_guidance`, `audience_knowledge_assumptions`, `desired_reader_experience`, `structure_preferences`, `must_include`, `must_avoid`, `non_negotiables`, `evidence_expectations`, `citation_expectations`, `liked_examples`, `rejected_examples`, `additional_editorial_guidance`, `editorial_profile`, `style_rules`, `must_not_change`, `structure_preference`, and `confidence_notes`.
36
+ - Top-level `--title`, `--topic`, and `--audience` can still be used with `--contract`; they fill missing project title, contract topic, or contract audience fields.
37
+ - Example:
38
+
39
+ ```bash
40
+ coauthor project create --title "AI search attribution" --contract '{"topic":"AI search attribution","angle":"How marketing teams should measure source visibility across AI answer engines","target_audience":"B2B marketing leaders","core_promise":"Give readers a practical measurement framework they can use this quarter.","must_include":["source provenance","measurement tradeoffs","examples of query-level visibility checks"],"must_avoid":["generic SEO advice","unsupported vendor claims"],"evidence_expectations":["Use current platform documentation or credible examples for factual claims."],"editorial_profile":{"tone":"serious","form":"guide","depth":"deep","cadence":"moderate"}}' --json
41
+ ```
42
+
28
43
  ## Safety
29
44
 
30
45
  - Never print access tokens, publish tokens, service-role keys, cookies, or authorization headers.
@@ -57,3 +72,5 @@ Use `coauthor draft get <project-id> --format html --json` when the user needs H
57
72
  Use `coauthor draft get <project-id> --format text --json` when the user needs plain text with image URL references.
58
73
 
59
74
  Use `coauthor draft get <project-id> --format json --json` or omit `--format` when the user needs the raw editor document JSON.
75
+
76
+ Use `coauthor export wordpress <project-id> --yes --slug <slug> --json` to export a saved draft to WordPress. If more than one WordPress connection exists, pass `--connection-id <id>`.
@@ -22,9 +22,24 @@ 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
 
30
+ ## Project Briefing
31
+
32
+ - For simple starts, use `coauthor project create --title "..." --topic "prose brief" --audience "target reader" --json`.
33
+ - When you know the editorial contract fields, prefer `coauthor project create --contract '<json>' --json` instead of cramming structured data into `--topic`.
34
+ - Keep `--topic` as a plain prose brief. Do not pass JSON through `--topic`.
35
+ - `--contract` accepts a JSON object with editorial contract fields such as `topic`, `angle`, `target_audience`, `core_promise`, `format`, `reading_commitment`, `length_guidance`, `audience_knowledge_assumptions`, `desired_reader_experience`, `structure_preferences`, `must_include`, `must_avoid`, `non_negotiables`, `evidence_expectations`, `citation_expectations`, `liked_examples`, `rejected_examples`, `additional_editorial_guidance`, `editorial_profile`, `style_rules`, `must_not_change`, `structure_preference`, and `confidence_notes`.
36
+ - Top-level `--title`, `--topic`, and `--audience` can still be used with `--contract`; they fill missing project title, contract topic, or contract audience fields.
37
+ - Example:
38
+
39
+ ```bash
40
+ coauthor project create --title "AI search attribution" --contract '{"topic":"AI search attribution","angle":"How marketing teams should measure source visibility across AI answer engines","target_audience":"B2B marketing leaders","core_promise":"Give readers a practical measurement framework they can use this quarter.","must_include":["source provenance","measurement tradeoffs","examples of query-level visibility checks"],"must_avoid":["generic SEO advice","unsupported vendor claims"],"evidence_expectations":["Use current platform documentation or credible examples for factual claims."],"editorial_profile":{"tone":"serious","form":"guide","depth":"deep","cadence":"moderate"}}' --json
41
+ ```
42
+
28
43
  ## Safety
29
44
 
30
45
  - Never print access tokens, publish tokens, service-role keys, cookies, or authorization headers.
@@ -57,3 +72,5 @@ Use `coauthor draft get <project-id> --format html --json` when the user needs H
57
72
  Use `coauthor draft get <project-id> --format text --json` when the user needs plain text with image URL references.
58
73
 
59
74
  Use `coauthor draft get <project-id> --format json --json` or omit `--format` when the user needs the raw editor document JSON.
75
+
76
+ Use `coauthor export wordpress <project-id> --yes --slug <slug> --json` to export a saved draft to WordPress. If more than one WordPress connection exists, pass `--connection-id <id>`.
@@ -22,9 +22,24 @@ 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
 
30
+ ## Project Briefing
31
+
32
+ - For simple starts, use `coauthor project create --title "..." --topic "prose brief" --audience "target reader" --json`.
33
+ - When you know the editorial contract fields, prefer `coauthor project create --contract '<json>' --json` instead of cramming structured data into `--topic`.
34
+ - Keep `--topic` as a plain prose brief. Do not pass JSON through `--topic`.
35
+ - `--contract` accepts a JSON object with editorial contract fields such as `topic`, `angle`, `target_audience`, `core_promise`, `format`, `reading_commitment`, `length_guidance`, `audience_knowledge_assumptions`, `desired_reader_experience`, `structure_preferences`, `must_include`, `must_avoid`, `non_negotiables`, `evidence_expectations`, `citation_expectations`, `liked_examples`, `rejected_examples`, `additional_editorial_guidance`, `editorial_profile`, `style_rules`, `must_not_change`, `structure_preference`, and `confidence_notes`.
36
+ - Top-level `--title`, `--topic`, and `--audience` can still be used with `--contract`; they fill missing project title, contract topic, or contract audience fields.
37
+ - Example:
38
+
39
+ ```bash
40
+ coauthor project create --title "AI search attribution" --contract '{"topic":"AI search attribution","angle":"How marketing teams should measure source visibility across AI answer engines","target_audience":"B2B marketing leaders","core_promise":"Give readers a practical measurement framework they can use this quarter.","must_include":["source provenance","measurement tradeoffs","examples of query-level visibility checks"],"must_avoid":["generic SEO advice","unsupported vendor claims"],"evidence_expectations":["Use current platform documentation or credible examples for factual claims."],"editorial_profile":{"tone":"serious","form":"guide","depth":"deep","cadence":"moderate"}}' --json
41
+ ```
42
+
28
43
  ## Safety
29
44
 
30
45
  - Never print access tokens, publish tokens, service-role keys, cookies, or authorization headers.
@@ -57,3 +72,5 @@ Use `coauthor draft get <project-id> --format html --json` when the user needs H
57
72
  Use `coauthor draft get <project-id> --format text --json` when the user needs plain text with image URL references.
58
73
 
59
74
  Use `coauthor draft get <project-id> --format json --json` or omit `--format` when the user needs the raw editor document JSON.
75
+
76
+ Use `coauthor export wordpress <project-id> --yes --slug <slug> --json` to export a saved draft to WordPress. If more than one WordPress connection exists, pass `--connection-id <id>`.
@@ -19,8 +19,15 @@ 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.
26
+ - For simple starts, use `coauthor project create --title "..." --topic "prose brief" --audience "target reader" --json`.
27
+ - When you know the editorial contract fields, prefer `coauthor project create --contract '<json>' --json` instead of cramming structured data into `--topic`.
28
+ - Keep `--topic` as a plain prose brief. Do not pass JSON through `--topic`.
29
+ - `--contract` accepts a JSON object with editorial contract fields such as `topic`, `angle`, `target_audience`, `core_promise`, `format`, `reading_commitment`, `length_guidance`, `audience_knowledge_assumptions`, `desired_reader_experience`, `structure_preferences`, `must_include`, `must_avoid`, `non_negotiables`, `evidence_expectations`, `citation_expectations`, `liked_examples`, `rejected_examples`, `additional_editorial_guidance`, `editorial_profile`, `style_rules`, `must_not_change`, `structure_preference`, and `confidence_notes`.
30
+ - Top-level `--title`, `--topic`, and `--audience` can still be used with `--contract`; they fill missing project title, contract topic, or contract audience fields.
24
31
  - Never print tokens, service-role keys, cookies, or authorization headers.
25
32
  - Never ask the user to paste Anthropic, OpenAI, or Gemini provider API keys into chat or the terminal; key entry belongs in CoAuthor AI settings.
26
33
  - Pass tokens through environment variables or secret-backed CLI options only.
@@ -36,3 +43,4 @@ alwaysApply: true
36
43
  - Use `coauthor draft get <project-id> --format html --json` for HTML with resolved image tags.
37
44
  - Use `coauthor draft get <project-id> --format text --json` for plain text with image URL references.
38
45
  - Use `coauthor draft get <project-id> --format json --json` or omit `--format` for the raw editor document JSON.
46
+ - Use `coauthor export wordpress <project-id> --yes --slug <slug> --json` to export a saved draft to WordPress. If more than one WordPress connection exists, pass `--connection-id <id>`.