@clickminded/coauthor-cli 0.0.5 → 0.0.7
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 +12 -1
- package/dist/commands.js +64 -2
- package/dist/index.js +56 -6
- package/dist/output.d.ts +4 -0
- package/dist/output.js +8 -1
- package/dist/parser.js +2 -0
- package/package.json +1 -1
- package/skills/claude/SKILL.md +13 -0
- package/skills/codex/SKILL.md +13 -0
- package/skills/cursor/coauthor-cli.mdc +10 -0
package/README.md
CHANGED
|
@@ -118,8 +118,10 @@ Chat and workflow:
|
|
|
118
118
|
coauthor chat <project-id> --message "..." --json
|
|
119
119
|
coauthor workflow status <project-id> --json
|
|
120
120
|
coauthor workflow run <project-id> --target draft --wait --json
|
|
121
|
+
coauthor workflow resume <project-id> --target draft --wait --json
|
|
121
122
|
coauthor workflow rewind <project-id> --stage outline --reason "..." --json
|
|
122
123
|
coauthor workflow approve <project-id> --stage research_plan --json
|
|
124
|
+
coauthor credits <project-id> --json
|
|
123
125
|
```
|
|
124
126
|
|
|
125
127
|
Artifacts:
|
|
@@ -131,8 +133,13 @@ coauthor research-plan generate <project-id> --json
|
|
|
131
133
|
coauthor research run <project-id> --wait --json
|
|
132
134
|
coauthor draft generate <project-id> --wait --json
|
|
133
135
|
coauthor draft get <project-id> --format markdown --json
|
|
136
|
+
coauthor draft get <project-id> --format html --json
|
|
137
|
+
coauthor draft get <project-id> --format text --json
|
|
138
|
+
coauthor draft get <project-id> --format json --json
|
|
134
139
|
```
|
|
135
140
|
|
|
141
|
+
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.
|
|
142
|
+
|
|
136
143
|
Images and threads:
|
|
137
144
|
|
|
138
145
|
```sh
|
|
@@ -177,9 +184,11 @@ Agents should:
|
|
|
177
184
|
- Prefer `coauthor` over browser automation, `curl` to session APIs, or direct database access.
|
|
178
185
|
- Use `--json` on every command they need to parse.
|
|
179
186
|
- Use `--wait` when starting long-running research or draft jobs and the user expects completion.
|
|
187
|
+
- 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`.
|
|
188
|
+
- Use `coauthor credits <project-id> --json` to inspect credit allowance, pending holds, and remaining credits.
|
|
180
189
|
- Avoid retrying publish/export after uncertain network failures.
|
|
181
190
|
- Use `coauthor operation status <operation-key>` after uncertainty.
|
|
182
|
-
- Never print tokens, cookies, service-role keys, or authorization headers.
|
|
191
|
+
- Never print tokens, cookies, service-role keys, provider API keys, or authorization headers.
|
|
183
192
|
|
|
184
193
|
## Security
|
|
185
194
|
|
|
@@ -206,6 +215,8 @@ The CLI talks to `/api/agent/v1/*`. Treat this as a public beta API surface:
|
|
|
206
215
|
|
|
207
216
|
`authorization_pending` during login is normal while the browser approval page is waiting for browser approval.
|
|
208
217
|
|
|
218
|
+
`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`.
|
|
219
|
+
|
|
209
220
|
If `npx @clickminded/coauthor-cli help` fails while you are inside the CLI package source directory, run it from another directory or use:
|
|
210
221
|
|
|
211
222
|
```sh
|
package/dist/commands.js
CHANGED
|
@@ -31,6 +31,8 @@ export async function runCommand(input, context) {
|
|
|
31
31
|
return runDraftCommand(action, input, context.client);
|
|
32
32
|
if (scope === 'workflow')
|
|
33
33
|
return runWorkflowCommand(action, input, context.client);
|
|
34
|
+
if (scope === 'credits')
|
|
35
|
+
return runCreditsCommand(input, context.client);
|
|
34
36
|
if (scope === 'image')
|
|
35
37
|
return runResourceCommand('images', action, input, context.client);
|
|
36
38
|
if (scope === 'thread')
|
|
@@ -183,6 +185,25 @@ async function runWorkflowCommand(action, input, client) {
|
|
|
183
185
|
const data = await client.request({ path: projectPath });
|
|
184
186
|
return { ok: true, data };
|
|
185
187
|
}
|
|
188
|
+
if (action === 'resume') {
|
|
189
|
+
const target = normalizeWorkflowWaitTarget(getString(input.values, 'target') ?? getString(input.values, 'stage')) ?? 'draft';
|
|
190
|
+
if (target === 'research') {
|
|
191
|
+
const data = await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/research/run`, body: {} });
|
|
192
|
+
return getBoolean(input.values, 'wait') ? waitForResearch(client, projectId, data) : { ok: true, data };
|
|
193
|
+
}
|
|
194
|
+
const researchStatus = await client.request({ path: `projects/${encodeURIComponent(projectId)}/research/status` });
|
|
195
|
+
if (extractNestedString(researchStatus, ['run', 'status']) === 'paused_requires_key') {
|
|
196
|
+
const data = await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/research/run`, body: {} });
|
|
197
|
+
return getBoolean(input.values, 'wait') ? waitForWorkflowDraft(client, projectId, data) : { ok: true, data };
|
|
198
|
+
}
|
|
199
|
+
const draftStatus = await client.request({ path: `projects/${encodeURIComponent(projectId)}/draft/status` });
|
|
200
|
+
if (getResponseString(draftStatus, 'phase') === 'paused_requires_key') {
|
|
201
|
+
const data = await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/draft/generate`, body: {} });
|
|
202
|
+
return getBoolean(input.values, 'wait') ? waitForDraft(client, projectId, data) : { ok: true, data };
|
|
203
|
+
}
|
|
204
|
+
const data = await client.request({ method: 'POST', path: `${projectPath}/run`, body: { target } });
|
|
205
|
+
return getBoolean(input.values, 'wait') ? waitForWorkflowDraft(client, projectId, data) : { ok: true, data };
|
|
206
|
+
}
|
|
186
207
|
if (action === 'advance' || action === 'run' || action === 'rewind' || action === 'approve') {
|
|
187
208
|
const body = withNamedOptions(parseJsonOption(input.values), input.values, [
|
|
188
209
|
'stage',
|
|
@@ -213,7 +234,12 @@ async function runWorkflowCommand(action, input, client) {
|
|
|
213
234
|
}
|
|
214
235
|
return { ok: true, data };
|
|
215
236
|
}
|
|
216
|
-
throw new Error('Usage: coauthor workflow <show|status|advance|run|rewind|approve> <projectId>');
|
|
237
|
+
throw new Error('Usage: coauthor workflow <show|status|advance|run|rewind|approve|resume> <projectId>');
|
|
238
|
+
}
|
|
239
|
+
async function runCreditsCommand(input, client) {
|
|
240
|
+
const projectId = requireProjectId(input);
|
|
241
|
+
const data = await client.request({ path: `projects/${encodeURIComponent(projectId)}/credits` });
|
|
242
|
+
return { ok: true, data };
|
|
217
243
|
}
|
|
218
244
|
async function runArtifactCommand(artifact, action, input, client) {
|
|
219
245
|
const projectId = requireProjectId(input);
|
|
@@ -332,6 +358,9 @@ async function runResourceCommand(resource, action, input, client) {
|
|
|
332
358
|
'id',
|
|
333
359
|
'placeholder-id',
|
|
334
360
|
'execution-token',
|
|
361
|
+
'grounding-mode',
|
|
362
|
+
'image-generation-model',
|
|
363
|
+
'edit-prompt',
|
|
335
364
|
]);
|
|
336
365
|
const path = action === 'create' && resource !== 'threads' ? basePath : `${basePath}/${action}`;
|
|
337
366
|
const data = await client.request({ method: 'POST', path, body });
|
|
@@ -520,6 +549,9 @@ async function waitForResearch(client, projectId, initialData) {
|
|
|
520
549
|
return { ok: true, message: 'Research completed', data: latest };
|
|
521
550
|
if (status === 'failed')
|
|
522
551
|
throw new Error(extractNestedString(latest, ['run', 'error_message']) ?? 'Research failed');
|
|
552
|
+
if (status === 'paused_requires_key') {
|
|
553
|
+
return requiresKeyPauseResult(projectId, 'research', extractNestedString(latest, ['run', 'error_message']) ?? 'Research paused: add the required API key to continue.', latest);
|
|
554
|
+
}
|
|
523
555
|
}
|
|
524
556
|
return { ok: true, message: 'Timed out waiting for research; check status with coauthor research status', data: latest };
|
|
525
557
|
}
|
|
@@ -534,6 +566,8 @@ async function waitForDraft(client, projectId, initialData) {
|
|
|
534
566
|
if (state === 'draft_generated' || state === 'editing' || phase === 'complete') {
|
|
535
567
|
return { ok: true, message: 'Draft completed', data: latest };
|
|
536
568
|
}
|
|
569
|
+
if (phase === 'paused_requires_key')
|
|
570
|
+
return requiresKeyPauseResult(projectId, 'draft', getResponseString(latest, 'message') ?? 'Draft paused: add the required API key to continue.', latest);
|
|
537
571
|
if (phase === 'failed')
|
|
538
572
|
throw new Error(getResponseString(latest, 'message') ?? 'Draft generation failed');
|
|
539
573
|
}
|
|
@@ -564,11 +598,25 @@ async function waitForWorkflowDraft(client, projectId, initialData) {
|
|
|
564
598
|
}
|
|
565
599
|
if (draftPhase === 'failed')
|
|
566
600
|
throw new Error(getResponseString(latestDraft, 'message') ?? 'Draft generation failed');
|
|
601
|
+
if (draftPhase === 'paused_requires_key') {
|
|
602
|
+
return requiresKeyPauseResult(projectId, 'draft', getResponseString(latestDraft, 'message') ?? 'Draft paused: add the required API key to continue.', {
|
|
603
|
+
workflow: initialData,
|
|
604
|
+
research_status: latestResearch,
|
|
605
|
+
draft_status: latestDraft,
|
|
606
|
+
});
|
|
607
|
+
}
|
|
567
608
|
latestResearch = await client.request({ path: `projects/${encodeURIComponent(projectId)}/research/status` });
|
|
568
609
|
const researchStatus = extractNestedString(latestResearch, ['run', 'status']);
|
|
569
610
|
if (researchStatus === 'failed') {
|
|
570
611
|
throw new Error(extractNestedString(latestResearch, ['run', 'error_message']) ?? 'Research failed');
|
|
571
612
|
}
|
|
613
|
+
if (researchStatus === 'paused_requires_key') {
|
|
614
|
+
return requiresKeyPauseResult(projectId, 'research', extractNestedString(latestResearch, ['run', 'error_message']) ?? 'Research paused: add the required API key to continue.', {
|
|
615
|
+
workflow: initialData,
|
|
616
|
+
research_status: latestResearch,
|
|
617
|
+
draft_status: latestDraft,
|
|
618
|
+
});
|
|
619
|
+
}
|
|
572
620
|
if (!attemptedDraftStart
|
|
573
621
|
&& (researchStatus === 'succeeded' || isResearchReadyForDraft(draftState))
|
|
574
622
|
&& draftPhase !== 'queued'
|
|
@@ -597,6 +645,18 @@ async function waitForWorkflowDraft(client, projectId, initialData) {
|
|
|
597
645
|
},
|
|
598
646
|
};
|
|
599
647
|
}
|
|
648
|
+
function requiresKeyPauseResult(projectId, target, message, data) {
|
|
649
|
+
const resumeCommand = `coauthor workflow resume ${projectId} --target ${target} --wait --json`;
|
|
650
|
+
return {
|
|
651
|
+
ok: false,
|
|
652
|
+
status: 'requires_key',
|
|
653
|
+
exitCode: 2,
|
|
654
|
+
message: `${message}\nOpen AI settings: /settings/ai\nResume: ${resumeCommand}`,
|
|
655
|
+
settings_url: '/settings/ai',
|
|
656
|
+
resume_command: resumeCommand,
|
|
657
|
+
data,
|
|
658
|
+
};
|
|
659
|
+
}
|
|
600
660
|
function extractNestedString(value, path) {
|
|
601
661
|
let current = value;
|
|
602
662
|
for (const key of path) {
|
|
@@ -664,13 +724,15 @@ export function helpResult() {
|
|
|
664
724
|
' research-plan show|generate|save|approve',
|
|
665
725
|
' research run|status|structured',
|
|
666
726
|
' draft generate|status|get|save',
|
|
667
|
-
'
|
|
727
|
+
' draft get supports --format json|markdown|html|text',
|
|
728
|
+
' workflow show|status|advance|run|rewind|approve|resume',
|
|
668
729
|
' workflow run/advance supports --briefing-mode auto|strict|off and --require-brief-review',
|
|
669
730
|
' image list|status|show|generate|edit',
|
|
670
731
|
' thread list|show|create|generate|save',
|
|
671
732
|
' publish thread',
|
|
672
733
|
' export blog|clickminded',
|
|
673
734
|
' operation list|show|status',
|
|
735
|
+
' credits',
|
|
674
736
|
' skills list|install',
|
|
675
737
|
].join('\n'),
|
|
676
738
|
};
|
package/dist/index.js
CHANGED
|
@@ -7,6 +7,7 @@ import { helpResult, runCommand } from './commands.js';
|
|
|
7
7
|
import { renderError, renderResult } from './output.js';
|
|
8
8
|
import { parseCliArgs } from './parser.js';
|
|
9
9
|
export async function main(argv = process.argv.slice(2)) {
|
|
10
|
+
let resolvedBaseUrl = resolveBaseUrlFromArgv(argv);
|
|
10
11
|
try {
|
|
11
12
|
const parsed = parseCliArgs(argv);
|
|
12
13
|
if (parsed.globals.help) {
|
|
@@ -17,6 +18,7 @@ export async function main(argv = process.argv.slice(2)) {
|
|
|
17
18
|
baseUrlOverride: parsed.globals.baseUrl,
|
|
18
19
|
tokenOverride: parsed.globals.token,
|
|
19
20
|
});
|
|
21
|
+
resolvedBaseUrl = runtimeConfig.baseUrl;
|
|
20
22
|
const client = new AgentClient(runtimeConfig);
|
|
21
23
|
const result = await runCommand(parsed, {
|
|
22
24
|
client,
|
|
@@ -24,20 +26,24 @@ export async function main(argv = process.argv.slice(2)) {
|
|
|
24
26
|
token: runtimeConfig.token,
|
|
25
27
|
});
|
|
26
28
|
process.stdout.write(renderResult(result, parsed.globals.json));
|
|
27
|
-
return 0;
|
|
29
|
+
return result.exitCode ?? (result.ok ? 0 : 1);
|
|
28
30
|
}
|
|
29
31
|
catch (error) {
|
|
30
32
|
const wantsJson = argv.includes('--json');
|
|
31
|
-
|
|
32
|
-
|
|
33
|
+
const formatted = formatCliError(error, resolvedBaseUrl);
|
|
34
|
+
process.stderr.write(renderError(formatted.result ?? formatted.error, wantsJson));
|
|
35
|
+
return formatted.exitCode;
|
|
33
36
|
}
|
|
34
37
|
}
|
|
35
|
-
function formatCliError(error) {
|
|
38
|
+
function formatCliError(error, baseUrl) {
|
|
36
39
|
if (error instanceof AgentHttpError) {
|
|
40
|
+
const requiresKey = formatRequiresKeyResult(error.responseBody, baseUrl);
|
|
41
|
+
if (requiresKey)
|
|
42
|
+
return { error: new Error(requiresKey.message), result: requiresKey, exitCode: 2 };
|
|
37
43
|
const message = extractErrorMessage(error.responseBody) ?? error.message;
|
|
38
|
-
return new Error(message);
|
|
44
|
+
return { error: new Error(message), exitCode: 1 };
|
|
39
45
|
}
|
|
40
|
-
return error instanceof Error ? error : new Error(String(error));
|
|
46
|
+
return { error: error instanceof Error ? error : new Error(String(error)), exitCode: 1 };
|
|
41
47
|
}
|
|
42
48
|
function extractErrorMessage(body) {
|
|
43
49
|
if (!body || typeof body !== 'object' || Array.isArray(body) || !('error' in body))
|
|
@@ -50,6 +56,50 @@ function extractErrorMessage(body) {
|
|
|
50
56
|
const message = error.message;
|
|
51
57
|
return typeof message === 'string' ? message : null;
|
|
52
58
|
}
|
|
59
|
+
function formatRequiresKeyResult(body, baseUrl) {
|
|
60
|
+
const envelopeError = extractEnvelopeError(body);
|
|
61
|
+
if (!envelopeError || envelopeError.code !== 'requires_key')
|
|
62
|
+
return null;
|
|
63
|
+
const details = envelopeError.details && typeof envelopeError.details === 'object' && !Array.isArray(envelopeError.details)
|
|
64
|
+
? envelopeError.details
|
|
65
|
+
: {};
|
|
66
|
+
const settingsUrl = typeof details.settings_url === 'string' ? details.settings_url : new URL('/settings/ai', baseUrl).toString();
|
|
67
|
+
const resumeCommand = typeof details.resume_command === 'string' ? details.resume_command : undefined;
|
|
68
|
+
return {
|
|
69
|
+
ok: false,
|
|
70
|
+
status: 'requires_key',
|
|
71
|
+
message: [
|
|
72
|
+
envelopeError.message,
|
|
73
|
+
`Open AI settings: ${settingsUrl}`,
|
|
74
|
+
resumeCommand ? `Resume: ${resumeCommand}` : null,
|
|
75
|
+
].filter(Boolean).join('\n'),
|
|
76
|
+
settings_url: settingsUrl,
|
|
77
|
+
resume_command: resumeCommand,
|
|
78
|
+
data: details,
|
|
79
|
+
exitCode: 2,
|
|
80
|
+
};
|
|
81
|
+
}
|
|
82
|
+
function extractEnvelopeError(body) {
|
|
83
|
+
if (!body || typeof body !== 'object' || Array.isArray(body) || !('error' in body))
|
|
84
|
+
return null;
|
|
85
|
+
const error = body.error;
|
|
86
|
+
if (!error || typeof error !== 'object' || Array.isArray(error))
|
|
87
|
+
return null;
|
|
88
|
+
const message = error.message;
|
|
89
|
+
if (typeof message !== 'string')
|
|
90
|
+
return null;
|
|
91
|
+
const code = error.code;
|
|
92
|
+
return {
|
|
93
|
+
code: typeof code === 'string' ? code : undefined,
|
|
94
|
+
message,
|
|
95
|
+
details: error.details,
|
|
96
|
+
};
|
|
97
|
+
}
|
|
98
|
+
function resolveBaseUrlFromArgv(argv) {
|
|
99
|
+
const index = argv.indexOf('--base-url');
|
|
100
|
+
const value = index >= 0 ? argv[index + 1] : undefined;
|
|
101
|
+
return value || process.env.COAUTHOR_BASE_URL || 'http://localhost:3000';
|
|
102
|
+
}
|
|
53
103
|
function isCliEntrypoint() {
|
|
54
104
|
const argvPath = process.argv[1];
|
|
55
105
|
if (!argvPath)
|
package/dist/output.d.ts
CHANGED
|
@@ -1,8 +1,12 @@
|
|
|
1
1
|
import type { JsonValue } from './client.js';
|
|
2
2
|
export type CommandResult = {
|
|
3
3
|
ok: boolean;
|
|
4
|
+
status?: string;
|
|
4
5
|
message?: string;
|
|
5
6
|
data?: JsonValue;
|
|
7
|
+
exitCode?: number;
|
|
8
|
+
settings_url?: string;
|
|
9
|
+
resume_command?: string;
|
|
6
10
|
};
|
|
7
11
|
export declare function renderResult(result: CommandResult, json: boolean): string;
|
|
8
12
|
export declare function renderError(error: unknown, json: boolean): string;
|
package/dist/output.js
CHANGED
|
@@ -8,7 +8,14 @@ export function renderResult(result, json) {
|
|
|
8
8
|
return `${JSON.stringify(result.data, null, 2)}\n`;
|
|
9
9
|
}
|
|
10
10
|
export function renderError(error, json) {
|
|
11
|
-
|
|
11
|
+
if (json && error && typeof error === 'object' && !Array.isArray(error) && 'ok' in error) {
|
|
12
|
+
return `${JSON.stringify(error, null, 2)}\n`;
|
|
13
|
+
}
|
|
14
|
+
const message = error instanceof Error
|
|
15
|
+
? error.message
|
|
16
|
+
: error && typeof error === 'object' && !Array.isArray(error) && typeof error.message === 'string'
|
|
17
|
+
? error.message
|
|
18
|
+
: String(error);
|
|
12
19
|
if (json)
|
|
13
20
|
return `${JSON.stringify({ ok: false, error: message }, null, 2)}\n`;
|
|
14
21
|
return `Error: ${message}\n`;
|
package/dist/parser.js
CHANGED
|
@@ -104,6 +104,8 @@ function commandLength(positionals) {
|
|
|
104
104
|
return second && ['list', 'install'].includes(second) ? 2 : 1;
|
|
105
105
|
if (first === 'workflow')
|
|
106
106
|
return second ? 2 : 1;
|
|
107
|
+
if (first === 'credits')
|
|
108
|
+
return 1;
|
|
107
109
|
if (['contract', 'outline', 'research-plan', 'research', 'draft', 'image', 'thread', 'publish', 'export', 'operation'].includes(first ?? ''))
|
|
108
110
|
return second ? 2 : 1;
|
|
109
111
|
return 1;
|
package/package.json
CHANGED
package/skills/claude/SKILL.md
CHANGED
|
@@ -14,11 +14,14 @@ This skill guides agent use of the CoAuthor CLI.
|
|
|
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
|
+
- 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
|
+
- Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
|
|
17
19
|
- After a timeout, interruption, network error, or unclear result, check operation status before retrying.
|
|
18
20
|
|
|
19
21
|
## Safety
|
|
20
22
|
|
|
21
23
|
- Never print access tokens, publish tokens, service-role keys, cookies, or authorization headers.
|
|
24
|
+
- 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.
|
|
22
25
|
- Pass tokens through environment variables or secret-backed CLI options only; do not paste them into prompts, logs, or shell history.
|
|
23
26
|
- Treat publish/export operations as live side effects.
|
|
24
27
|
- Require explicit user intent before live publish/export.
|
|
@@ -31,3 +34,13 @@ This skill guides agent use of the CoAuthor CLI.
|
|
|
31
34
|
3. Add `--wait` when starting or advancing asynchronous work.
|
|
32
35
|
4. If anything is uncertain, query operation status and report the current state.
|
|
33
36
|
5. For live publish/export, confirm explicit user intent, then run with `--yes`.
|
|
37
|
+
|
|
38
|
+
## Draft Export
|
|
39
|
+
|
|
40
|
+
Use `coauthor draft get <project-id> --format markdown --json` when the user needs a finished draft in Markdown. Generated images are resolved into Markdown image URLs when available.
|
|
41
|
+
|
|
42
|
+
Use `coauthor draft get <project-id> --format html --json` when the user needs HTML with resolved image tags.
|
|
43
|
+
|
|
44
|
+
Use `coauthor draft get <project-id> --format text --json` when the user needs plain text with image URL references.
|
|
45
|
+
|
|
46
|
+
Use `coauthor draft get <project-id> --format json --json` or omit `--format` when the user needs the raw editor document JSON.
|
package/skills/codex/SKILL.md
CHANGED
|
@@ -14,11 +14,14 @@ This skill guides agent use of the CoAuthor CLI.
|
|
|
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
|
+
- 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
|
+
- Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
|
|
17
19
|
- After a timeout, interruption, network error, or unclear result, check operation status before retrying.
|
|
18
20
|
|
|
19
21
|
## Safety
|
|
20
22
|
|
|
21
23
|
- Never print access tokens, publish tokens, service-role keys, cookies, or authorization headers.
|
|
24
|
+
- 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.
|
|
22
25
|
- Pass tokens through environment variables or secret-backed CLI options only; do not paste them into prompts, logs, or shell history.
|
|
23
26
|
- Treat publish/export operations as live side effects.
|
|
24
27
|
- Require explicit user intent before live publish/export.
|
|
@@ -31,3 +34,13 @@ This skill guides agent use of the CoAuthor CLI.
|
|
|
31
34
|
3. Add `--wait` when starting or advancing asynchronous work.
|
|
32
35
|
4. If anything is uncertain, query operation status and report the current state.
|
|
33
36
|
5. For live publish/export, confirm explicit user intent, then run with `--yes`.
|
|
37
|
+
|
|
38
|
+
## Draft Export
|
|
39
|
+
|
|
40
|
+
Use `coauthor draft get <project-id> --format markdown --json` when the user needs a finished draft in Markdown. Generated images are resolved into Markdown image URLs when available.
|
|
41
|
+
|
|
42
|
+
Use `coauthor draft get <project-id> --format html --json` when the user needs HTML with resolved image tags.
|
|
43
|
+
|
|
44
|
+
Use `coauthor draft get <project-id> --format text --json` when the user needs plain text with image URL references.
|
|
45
|
+
|
|
46
|
+
Use `coauthor draft get <project-id> --format json --json` or omit `--format` when the user needs the raw editor document JSON.
|
|
@@ -11,9 +11,19 @@ alwaysApply: true
|
|
|
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
|
+
- 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
|
+
- Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
|
|
14
16
|
- After timeout, interruption, network error, or ambiguous output, check operation status before retrying or reporting success.
|
|
15
17
|
- Never print tokens, service-role keys, cookies, or authorization headers.
|
|
18
|
+
- 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.
|
|
16
19
|
- Pass tokens through environment variables or secret-backed CLI options only.
|
|
17
20
|
- Treat publish/export commands as live side effects.
|
|
18
21
|
- Require explicit user intent before live publish/export.
|
|
19
22
|
- Use `--yes` only after the user has clearly approved the live publish/export action.
|
|
23
|
+
|
|
24
|
+
## Draft Export
|
|
25
|
+
|
|
26
|
+
- Use `coauthor draft get <project-id> --format markdown --json` for finished draft Markdown. Generated images resolve into Markdown image URLs when available.
|
|
27
|
+
- Use `coauthor draft get <project-id> --format html --json` for HTML with resolved image tags.
|
|
28
|
+
- Use `coauthor draft get <project-id> --format text --json` for plain text with image URL references.
|
|
29
|
+
- Use `coauthor draft get <project-id> --format json --json` or omit `--format` for the raw editor document JSON.
|