@clickminded/coauthor-cli 0.0.16 → 0.0.18
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 +33 -8
- package/dist/commands.d.ts +2 -1
- package/dist/commands.js +139 -10
- package/dist/index.js +31 -0
- package/dist/parser.js +1 -0
- package/package.json +3 -2
- package/scripts/verify-skill-sync.mjs +59 -0
- package/skills/agents/SKILL.md +18 -1
- package/skills/claude/SKILL.md +18 -1
- package/skills/codex/SKILL.md +18 -1
- package/skills/cursor/coauthor-cli.mdc +13 -1
package/README.md
CHANGED
|
@@ -45,6 +45,16 @@ Log out and revoke the local token:
|
|
|
45
45
|
coauthor auth logout
|
|
46
46
|
```
|
|
47
47
|
|
|
48
|
+
Normal logout removes the local credential only after remote revocation succeeds or the server confirms the token was already revoked or expired. If the server cannot confirm revocation, the CLI keeps the credential so you can retry safely.
|
|
49
|
+
|
|
50
|
+
To deliberately remove only the local credential while leaving the remote token potentially active:
|
|
51
|
+
|
|
52
|
+
```sh
|
|
53
|
+
coauthor auth logout --local-only
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Use `--local-only` only when you explicitly accept that the remote token may remain usable until it expires or is revoked elsewhere.
|
|
57
|
+
|
|
48
58
|
Local credentials are stored at `~/.coauthor/config.json` with best-effort `0600` permissions. Do not print, paste, or commit this file.
|
|
49
59
|
|
|
50
60
|
## Agent Skills
|
|
@@ -93,9 +103,10 @@ Work with the project:
|
|
|
93
103
|
coauthor chat <project-id> --message "Refine the angle for this post" --json
|
|
94
104
|
coauthor workflow status <project-id> --json
|
|
95
105
|
coauthor workflow run <project-id> --target draft --wait --json
|
|
96
|
-
coauthor workflow run <project-id> --target draft --planning-model gpt-5.
|
|
106
|
+
coauthor workflow run <project-id> --target draft --planning-model gpt-5.6-sol --writing-model gpt-5.6-terra --wait --json
|
|
97
107
|
coauthor workflow resume <project-id> --target draft --wait --json
|
|
98
108
|
coauthor credits <project-id> --json
|
|
109
|
+
coauthor share <project-id> --json
|
|
99
110
|
```
|
|
100
111
|
|
|
101
112
|
List and save text model preferences:
|
|
@@ -103,17 +114,19 @@ List and save text model preferences:
|
|
|
103
114
|
```sh
|
|
104
115
|
coauthor models list
|
|
105
116
|
coauthor models preferences show --json
|
|
106
|
-
coauthor models preferences set --planning-model gpt-5.
|
|
117
|
+
coauthor models preferences set --planning-model gpt-5.6-sol --writing-model gpt-5.6-terra --json
|
|
107
118
|
```
|
|
108
119
|
|
|
120
|
+
Both plans can select any supported user-visible model. Starter includes 2,500 credits per monthly subscription-anniversary period and cannot use customer API keys. Pro includes 6,000 credits and uses included credits first, then a compatible configured provider key. A provider key is never required merely to select a model while included credits remain. Drip tags alone determine customer access and plan; subscription observations are diagnostic and set anniversary timing only. All statuses are retained, only `active` observations can promote an anchor, and renewal observations do not reset credits. The Supabase `admins` table is the canonical cross-surface admin bypass source.
|
|
121
|
+
|
|
109
122
|
Read or generate artifacts:
|
|
110
123
|
|
|
111
124
|
```sh
|
|
112
125
|
coauthor contract show <project-id> --json
|
|
113
126
|
coauthor outline generate <project-id> --planning-model claude-opus-4-8 --json
|
|
114
|
-
coauthor research-plan generate <project-id> --planning-model gpt-5.
|
|
127
|
+
coauthor research-plan generate <project-id> --planning-model gpt-5.6-sol --json
|
|
115
128
|
coauthor research run <project-id> --wait --json
|
|
116
|
-
coauthor draft generate <project-id> --writing-model gpt-5.
|
|
129
|
+
coauthor draft generate <project-id> --writing-model gpt-5.6-terra --wait --json
|
|
117
130
|
coauthor draft get <project-id> --format markdown --json
|
|
118
131
|
```
|
|
119
132
|
|
|
@@ -122,7 +135,7 @@ Images and social content:
|
|
|
122
135
|
```sh
|
|
123
136
|
coauthor image list <project-id> --json
|
|
124
137
|
coauthor image generate <project-id> --placeholder-id <placeholder-id> --prompt "Image direction" --json
|
|
125
|
-
coauthor thread generate <project-id> --writing-model gpt-5.
|
|
138
|
+
coauthor thread generate <project-id> --writing-model gpt-5.6-terra --json
|
|
126
139
|
```
|
|
127
140
|
|
|
128
141
|
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.
|
|
@@ -169,7 +182,9 @@ Agents should:
|
|
|
169
182
|
- Prefer `coauthor` commands over browser automation, hand-written HTTP requests, or direct database access.
|
|
170
183
|
- Use `--json` for machine-readable output.
|
|
171
184
|
- Use `--wait` when starting asynchronous work and the user expects the result.
|
|
172
|
-
- Treat `status: "
|
|
185
|
+
- Treat `status: "credits_exhausted"` or `paused_credits_exhausted` as a recoverable Starter pause. Report the supplied `reset_at`, `allowance`, `used`, `held`, and `remaining`, then resume after credits reset; do not tell a Starter user to add an API key.
|
|
186
|
+
- Treat `status: "requires_key"` or `paused_requires_key` as a recoverable Pro pause. Report the compatible required provider, ask the user to add that key in CoAuthor AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
|
|
187
|
+
- Treat `coauthor_access_required` as an access failure and `entitlement_sync_unavailable` as a temporary verification outage. Do not retry blocked credit-spending commands in a loop.
|
|
173
188
|
- Treat `status: "research_running_stale"` as a stale research run and inspect `coauthor research structured <project-id> --json` before retrying.
|
|
174
189
|
- Check operation status after timeouts, interruptions, network errors, or uncertain live-action results.
|
|
175
190
|
- Never print tokens, cookies, provider keys, service-role keys, or authorization headers.
|
|
@@ -180,7 +195,7 @@ Agents should:
|
|
|
180
195
|
- Default login grants workflow/project scopes only.
|
|
181
196
|
- Publish/export scope is granted only when login is started with `--with-publish`.
|
|
182
197
|
- Tokens are stored locally at `~/.coauthor/config.json`.
|
|
183
|
-
- Run `coauthor auth logout` to revoke the current token and remove local credentials.
|
|
198
|
+
- Run `coauthor auth logout` to revoke the current token and then remove local credentials. A failed revoke preserves the local credential for retry; `--local-only` explicitly skips remote revocation.
|
|
184
199
|
|
|
185
200
|
## Troubleshooting
|
|
186
201
|
|
|
@@ -190,7 +205,17 @@ Agents should:
|
|
|
190
205
|
|
|
191
206
|
`authorization_pending` during login is normal while the browser approval page is waiting for approval.
|
|
192
207
|
|
|
193
|
-
`
|
|
208
|
+
If `auth logout` cannot confirm remote revocation, it leaves `~/.coauthor/config.json` intact and exits with an error. Retry normal logout when connectivity recovers. Use `auth logout --local-only` only to abandon remote revocation and remove the local credential anyway.
|
|
209
|
+
|
|
210
|
+
`coauthor_access_required` means the signed-in account no longer has verified CoAuthor access. A device token does not grant product access by itself. `auth status` and `auth logout` remain available, and an unexpired token works again if access is restored.
|
|
211
|
+
|
|
212
|
+
`entitlement_sync_unavailable` means Drip verification is temporarily degraded. Read-only inspection may remain available, but new credit-spending work is blocked until synchronization recovers. Login retries verification immediately, and scheduled reconciliation continues retrying with backoff; do not loop write commands while degraded.
|
|
213
|
+
|
|
214
|
+
`credits_exhausted` or `paused_credits_exhausted` means a Starter workflow is safely paused until the response's `reset_at`. Report its `allowance`, `used`, `held`, and `remaining` so the pause can be explained without guessing. Starter does not support BYOK.
|
|
215
|
+
|
|
216
|
+
`requires_key` or `paused_requires_key` means Pro included credits are exhausted and no usable compatible provider key is configured. Open CoAuthor AI settings, add one of the response's `required_providers`, then run `coauthor workflow resume <project-id> --wait --json`.
|
|
217
|
+
|
|
218
|
+
`byok_not_allowed` means the current plan cannot create, validate, or use provider keys. Starter users can delete a retained key from an earlier Pro period, but it remains inactive unless Pro access returns.
|
|
194
219
|
|
|
195
220
|
`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.
|
|
196
221
|
|
package/dist/commands.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { AgentClient } from './client.js';
|
|
1
|
+
import { AgentClient, type JsonValue } from './client.js';
|
|
2
2
|
import { type ConfigPaths } from './config.js';
|
|
3
3
|
import type { CommandResult } from './output.js';
|
|
4
4
|
import { type ParsedCommand } from './parser.js';
|
|
@@ -9,4 +9,5 @@ export type CommandContext = {
|
|
|
9
9
|
token: string;
|
|
10
10
|
};
|
|
11
11
|
export declare function runCommand(input: ParsedCommand, context: CommandContext): Promise<CommandResult>;
|
|
12
|
+
export declare function creditsExhaustedPauseResult(projectId: string, target: 'research' | 'draft', message: string, data: JsonValue): CommandResult;
|
|
12
13
|
export declare function helpResult(command?: string[]): CommandResult;
|
package/dist/commands.js
CHANGED
|
@@ -34,6 +34,8 @@ export async function runCommand(input, context) {
|
|
|
34
34
|
return runWorkflowCommand(action, input, context);
|
|
35
35
|
if (scope === 'credits')
|
|
36
36
|
return runCreditsCommand(input, context.client);
|
|
37
|
+
if (scope === 'share')
|
|
38
|
+
return runShareCommand(input, context.client);
|
|
37
39
|
if (scope === 'image')
|
|
38
40
|
return runResourceCommand('images', action, input, context.client);
|
|
39
41
|
if (scope === 'thread')
|
|
@@ -132,19 +134,71 @@ async function runAuthCommand(action, input, context) {
|
|
|
132
134
|
};
|
|
133
135
|
}
|
|
134
136
|
if (action === 'logout') {
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
137
|
+
const localOnly = getBoolean(input.values, 'local-only');
|
|
138
|
+
if (!context.token) {
|
|
139
|
+
await clearConfig(context.paths);
|
|
140
|
+
return {
|
|
141
|
+
ok: true,
|
|
142
|
+
message: 'No local token configured.',
|
|
143
|
+
data: { authenticated: false, remoteRevoked: null, localOnly },
|
|
144
|
+
};
|
|
145
|
+
}
|
|
146
|
+
if (localOnly) {
|
|
147
|
+
await clearConfig(context.paths);
|
|
148
|
+
return {
|
|
149
|
+
ok: true,
|
|
150
|
+
message: 'Local credentials removed without revoking the remote token.',
|
|
151
|
+
data: {
|
|
152
|
+
authenticated: false,
|
|
153
|
+
remoteRevoked: false,
|
|
154
|
+
localOnly: true,
|
|
155
|
+
remoteTokenMayRemainActive: true,
|
|
156
|
+
},
|
|
157
|
+
};
|
|
158
|
+
}
|
|
159
|
+
try {
|
|
160
|
+
await context.client.request({ method: 'POST', path: 'auth/logout', body: {} });
|
|
161
|
+
}
|
|
162
|
+
catch (error) {
|
|
163
|
+
const inactiveCode = inactiveAgentTokenCode(error);
|
|
164
|
+
if (!inactiveCode) {
|
|
165
|
+
throw new Error('Could not confirm remote token revocation. Local credentials were kept so you can retry `coauthor auth logout`. Use `coauthor auth logout --local-only` only to remove the local token without revoking it remotely.');
|
|
141
166
|
}
|
|
167
|
+
await clearConfig(context.paths);
|
|
168
|
+
return {
|
|
169
|
+
ok: true,
|
|
170
|
+
message: inactiveCode === 'token_revoked'
|
|
171
|
+
? 'Logged out; the remote token was already revoked and local credentials were removed.'
|
|
172
|
+
: 'Logged out; the remote token was already expired and local credentials were removed.',
|
|
173
|
+
data: {
|
|
174
|
+
authenticated: false,
|
|
175
|
+
remoteRevoked: true,
|
|
176
|
+
localOnly: false,
|
|
177
|
+
alreadyInactive: true,
|
|
178
|
+
},
|
|
179
|
+
};
|
|
142
180
|
}
|
|
143
181
|
await clearConfig(context.paths);
|
|
144
|
-
return {
|
|
182
|
+
return {
|
|
183
|
+
ok: true,
|
|
184
|
+
message: 'Logged out; remote token revoked and local credentials removed.',
|
|
185
|
+
data: { authenticated: false, remoteRevoked: true, localOnly: false },
|
|
186
|
+
};
|
|
145
187
|
}
|
|
146
188
|
throw new Error('Usage: coauthor auth <login|status|logout>');
|
|
147
189
|
}
|
|
190
|
+
function inactiveAgentTokenCode(error) {
|
|
191
|
+
if (!(error instanceof AgentHttpError))
|
|
192
|
+
return null;
|
|
193
|
+
const body = error.responseBody;
|
|
194
|
+
if (!body || typeof body !== 'object' || Array.isArray(body))
|
|
195
|
+
return null;
|
|
196
|
+
const envelope = body.error;
|
|
197
|
+
if (!envelope || typeof envelope !== 'object' || Array.isArray(envelope))
|
|
198
|
+
return null;
|
|
199
|
+
const code = envelope.code;
|
|
200
|
+
return code === 'token_revoked' || code === 'token_expired' ? code : null;
|
|
201
|
+
}
|
|
148
202
|
async function runProjectCommand(action, input, client) {
|
|
149
203
|
if (action === 'create') {
|
|
150
204
|
const body = withNamedOptions(parseJsonOption(input.values), input.values, ['title', 'topic', 'audience']);
|
|
@@ -226,7 +280,7 @@ async function runWorkflowCommand(action, input, context) {
|
|
|
226
280
|
return getBoolean(input.values, 'wait') ? waitForResearch(client, projectId, data, context.baseUrl) : { ok: true, data };
|
|
227
281
|
}
|
|
228
282
|
const researchStatus = await client.request({ path: `projects/${encodeURIComponent(projectId)}/research/status` });
|
|
229
|
-
if (extractNestedString(researchStatus, ['run', 'status'])
|
|
283
|
+
if (['paused_requires_key', 'paused_credits_exhausted'].includes(extractNestedString(researchStatus, ['run', 'status']) ?? '')) {
|
|
230
284
|
if (modelOverrides.writingModel && !getBoolean(input.values, 'wait')) {
|
|
231
285
|
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
286
|
}
|
|
@@ -234,7 +288,7 @@ async function runWorkflowCommand(action, input, context) {
|
|
|
234
288
|
return getBoolean(input.values, 'wait') ? waitForWorkflowDraft(client, projectId, data, context.baseUrl, modelOverrides) : { ok: true, data };
|
|
235
289
|
}
|
|
236
290
|
const draftStatus = await client.request({ path: `projects/${encodeURIComponent(projectId)}/draft/status` });
|
|
237
|
-
if (getResponseString(draftStatus, 'phase')
|
|
291
|
+
if (['paused_requires_key', 'paused_credits_exhausted'].includes(getResponseString(draftStatus, 'phase') ?? '')) {
|
|
238
292
|
const data = await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/draft/generate`, body: modelOverrides });
|
|
239
293
|
return getBoolean(input.values, 'wait') ? waitForDraft(client, projectId, data, context.baseUrl) : { ok: true, data };
|
|
240
294
|
}
|
|
@@ -279,6 +333,12 @@ async function runCreditsCommand(input, client) {
|
|
|
279
333
|
const data = await client.request({ path: `projects/${encodeURIComponent(projectId)}/credits` });
|
|
280
334
|
return { ok: true, data };
|
|
281
335
|
}
|
|
336
|
+
async function runShareCommand(input, client) {
|
|
337
|
+
const projectId = requireProjectId(input);
|
|
338
|
+
const data = await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/share` });
|
|
339
|
+
const shareUrl = getResponseString(data, 'share_url');
|
|
340
|
+
return { ok: true, message: shareUrl, data };
|
|
341
|
+
}
|
|
282
342
|
async function runModelsCommand(action, input, client) {
|
|
283
343
|
if (!action || action === 'list') {
|
|
284
344
|
const data = await client.request({ path: 'models' });
|
|
@@ -735,6 +795,9 @@ async function waitForResearch(client, projectId, initialData, baseUrl) {
|
|
|
735
795
|
if (status === 'paused_requires_key') {
|
|
736
796
|
return requiresKeyPauseResult(projectId, 'research', extractNestedString(latest, ['run', 'error_message']) ?? 'Research paused: add the required API key to continue.', latest, baseUrl);
|
|
737
797
|
}
|
|
798
|
+
if (status === 'paused_credits_exhausted') {
|
|
799
|
+
return creditsExhaustedPauseResult(projectId, 'research', extractNestedString(latest, ['run', 'error_message']) ?? 'Research paused until included credits reset.', latest);
|
|
800
|
+
}
|
|
738
801
|
const stale = researchRunningStaleResult(projectId, latest, null, initialData);
|
|
739
802
|
if (stale)
|
|
740
803
|
return stale;
|
|
@@ -755,6 +818,8 @@ async function waitForDraft(client, projectId, initialData, baseUrl) {
|
|
|
755
818
|
}
|
|
756
819
|
if (phase === 'paused_requires_key')
|
|
757
820
|
return requiresKeyPauseResult(projectId, 'draft', getResponseString(latest, 'message') ?? 'Draft paused: add the required API key to continue.', latest, baseUrl);
|
|
821
|
+
if (phase === 'paused_credits_exhausted')
|
|
822
|
+
return creditsExhaustedPauseResult(projectId, 'draft', getResponseString(latest, 'message') ?? 'Draft paused until included credits reset.', latest);
|
|
758
823
|
if (phase === 'failed')
|
|
759
824
|
throw new Error(getResponseString(latest, 'message') ?? 'Draft generation failed');
|
|
760
825
|
}
|
|
@@ -793,6 +858,13 @@ async function waitForWorkflowDraft(client, projectId, initialData, baseUrl, mod
|
|
|
793
858
|
draft_status: latestDraft,
|
|
794
859
|
}, baseUrl);
|
|
795
860
|
}
|
|
861
|
+
if (draftPhase === 'paused_credits_exhausted') {
|
|
862
|
+
return creditsExhaustedPauseResult(projectId, 'draft', getResponseString(latestDraft, 'message') ?? 'Draft paused until included credits reset.', {
|
|
863
|
+
workflow: initialData,
|
|
864
|
+
research_status: latestResearch,
|
|
865
|
+
draft_status: latestDraft,
|
|
866
|
+
});
|
|
867
|
+
}
|
|
796
868
|
latestResearch = await client.request({ path: `projects/${encodeURIComponent(projectId)}/research/status` });
|
|
797
869
|
const researchStatus = extractNestedString(latestResearch, ['run', 'status']);
|
|
798
870
|
if (researchStatus === 'failed') {
|
|
@@ -805,6 +877,13 @@ async function waitForWorkflowDraft(client, projectId, initialData, baseUrl, mod
|
|
|
805
877
|
draft_status: latestDraft,
|
|
806
878
|
}, baseUrl);
|
|
807
879
|
}
|
|
880
|
+
if (researchStatus === 'paused_credits_exhausted') {
|
|
881
|
+
return creditsExhaustedPauseResult(projectId, 'research', extractNestedString(latestResearch, ['run', 'error_message']) ?? 'Research paused until included credits reset.', {
|
|
882
|
+
workflow: initialData,
|
|
883
|
+
research_status: latestResearch,
|
|
884
|
+
draft_status: latestDraft,
|
|
885
|
+
});
|
|
886
|
+
}
|
|
808
887
|
const stale = researchRunningStaleResult(projectId, latestResearch, latestDraft, initialData);
|
|
809
888
|
if (stale)
|
|
810
889
|
return stale;
|
|
@@ -1003,6 +1082,49 @@ function requiresKeyPauseResult(projectId, target, message, data, baseUrl) {
|
|
|
1003
1082
|
data,
|
|
1004
1083
|
};
|
|
1005
1084
|
}
|
|
1085
|
+
export function creditsExhaustedPauseResult(projectId, target, message, data) {
|
|
1086
|
+
const resumeCommand = `coauthor workflow resume ${projectId} --target ${target} --wait --json`;
|
|
1087
|
+
const resetAt = extractCreditPauseString(data, 'reset_at');
|
|
1088
|
+
const allowance = extractCreditPauseNumber(data, 'allowance');
|
|
1089
|
+
const used = extractCreditPauseNumber(data, 'used');
|
|
1090
|
+
const held = extractCreditPauseNumber(data, 'held');
|
|
1091
|
+
const remaining = extractCreditPauseNumber(data, 'remaining');
|
|
1092
|
+
return {
|
|
1093
|
+
ok: false,
|
|
1094
|
+
status: 'credits_exhausted',
|
|
1095
|
+
exitCode: 2,
|
|
1096
|
+
message: `${message}\nResume after reset: ${resumeCommand}`,
|
|
1097
|
+
resume_command: resumeCommand,
|
|
1098
|
+
...(typeof resetAt === 'string' ? { reset_at: resetAt } : {}),
|
|
1099
|
+
...(allowance !== undefined ? { allowance } : {}),
|
|
1100
|
+
...(used !== undefined ? { used } : {}),
|
|
1101
|
+
...(held !== undefined ? { held } : {}),
|
|
1102
|
+
...(remaining !== undefined ? { remaining } : {}),
|
|
1103
|
+
data,
|
|
1104
|
+
};
|
|
1105
|
+
}
|
|
1106
|
+
const CREDIT_PAUSE_DETAIL_PREFIXES = [
|
|
1107
|
+
['run', 'pause_metadata'],
|
|
1108
|
+
['detail'],
|
|
1109
|
+
['draft_status', 'detail'],
|
|
1110
|
+
['research_status', 'run', 'pause_metadata'],
|
|
1111
|
+
];
|
|
1112
|
+
function extractCreditPauseString(data, key) {
|
|
1113
|
+
for (const prefix of CREDIT_PAUSE_DETAIL_PREFIXES) {
|
|
1114
|
+
const value = extractNestedString(data, [...prefix, key]);
|
|
1115
|
+
if (value !== undefined)
|
|
1116
|
+
return value;
|
|
1117
|
+
}
|
|
1118
|
+
return undefined;
|
|
1119
|
+
}
|
|
1120
|
+
function extractCreditPauseNumber(data, key) {
|
|
1121
|
+
for (const prefix of CREDIT_PAUSE_DETAIL_PREFIXES) {
|
|
1122
|
+
const value = extractNestedValue(data, [...prefix, key]);
|
|
1123
|
+
if (typeof value === 'number' && Number.isFinite(value))
|
|
1124
|
+
return value;
|
|
1125
|
+
}
|
|
1126
|
+
return undefined;
|
|
1127
|
+
}
|
|
1006
1128
|
function extractNestedString(value, path) {
|
|
1007
1129
|
const current = extractNestedValue(value, path);
|
|
1008
1130
|
return typeof current === 'string' ? current : undefined;
|
|
@@ -1068,7 +1190,7 @@ export function helpResult(command = []) {
|
|
|
1068
1190
|
'Usage: coauthor <command> [options]',
|
|
1069
1191
|
'',
|
|
1070
1192
|
'Commands:',
|
|
1071
|
-
' auth login|status|logout',
|
|
1193
|
+
' auth login|status|logout (logout supports --local-only)',
|
|
1072
1194
|
' project create|list|show',
|
|
1073
1195
|
' workspace show',
|
|
1074
1196
|
' chat [show|list]',
|
|
@@ -1087,6 +1209,7 @@ export function helpResult(command = []) {
|
|
|
1087
1209
|
' export blog|clickminded|wordpress',
|
|
1088
1210
|
' operation list|show|status',
|
|
1089
1211
|
' credits',
|
|
1212
|
+
' share <project-id>',
|
|
1090
1213
|
' models list|preferences show|preferences set',
|
|
1091
1214
|
' skills list|install',
|
|
1092
1215
|
' skills install supports codex|claude|cursor|agents|all',
|
|
@@ -1096,6 +1219,12 @@ export function helpResult(command = []) {
|
|
|
1096
1219
|
function commandHelp(command) {
|
|
1097
1220
|
const key = command.join(' ');
|
|
1098
1221
|
const help = {
|
|
1222
|
+
'auth logout': [
|
|
1223
|
+
'Usage: coauthor auth logout [--local-only] [--json]',
|
|
1224
|
+
'',
|
|
1225
|
+
'Revokes the remote token before removing local credentials. If revocation cannot be confirmed, the token is kept locally so the command can be retried.',
|
|
1226
|
+
'--local-only removes the local credential without revoking the remote token. Use it only when explicitly abandoning remote revocation.',
|
|
1227
|
+
].join('\n'),
|
|
1099
1228
|
'project create': [
|
|
1100
1229
|
'Usage: coauthor project create [--title <title>] [--topic <brief>] [--audience <audience>] [--contract <json>] [--json]',
|
|
1101
1230
|
'',
|
package/dist/index.js
CHANGED
|
@@ -37,6 +37,9 @@ export async function main(argv = process.argv.slice(2)) {
|
|
|
37
37
|
}
|
|
38
38
|
function formatCliError(error, baseUrl, argv = []) {
|
|
39
39
|
if (error instanceof AgentHttpError) {
|
|
40
|
+
const entitlement = formatEntitlementResult(error.responseBody);
|
|
41
|
+
if (entitlement)
|
|
42
|
+
return { error: new Error(entitlement.message), result: entitlement, exitCode: 2 };
|
|
40
43
|
const requiresKey = formatRequiresKeyResult(error.responseBody, baseUrl);
|
|
41
44
|
if (requiresKey)
|
|
42
45
|
return { error: new Error(requiresKey.message), result: requiresKey, exitCode: 2 };
|
|
@@ -48,6 +51,34 @@ function formatCliError(error, baseUrl, argv = []) {
|
|
|
48
51
|
}
|
|
49
52
|
return { error: error instanceof Error ? error : new Error(String(error)), exitCode: 1 };
|
|
50
53
|
}
|
|
54
|
+
function formatEntitlementResult(body) {
|
|
55
|
+
const envelopeError = extractEnvelopeError(body);
|
|
56
|
+
if (!envelopeError || ![
|
|
57
|
+
'credits_exhausted',
|
|
58
|
+
'coauthor_access_required',
|
|
59
|
+
'entitlement_sync_unavailable',
|
|
60
|
+
'byok_not_allowed',
|
|
61
|
+
].includes(envelopeError.code ?? ''))
|
|
62
|
+
return null;
|
|
63
|
+
const details = envelopeError.details && typeof envelopeError.details === 'object' && !Array.isArray(envelopeError.details)
|
|
64
|
+
? envelopeError.details
|
|
65
|
+
: {};
|
|
66
|
+
return {
|
|
67
|
+
ok: false,
|
|
68
|
+
status: envelopeError.code,
|
|
69
|
+
message: envelopeError.message,
|
|
70
|
+
reset_at: typeof details.reset_at === 'string' ? details.reset_at : undefined,
|
|
71
|
+
allowance: finiteDetailNumber(details.allowance),
|
|
72
|
+
used: finiteDetailNumber(details.used),
|
|
73
|
+
held: finiteDetailNumber(details.held),
|
|
74
|
+
remaining: finiteDetailNumber(details.remaining),
|
|
75
|
+
data: details,
|
|
76
|
+
exitCode: 2,
|
|
77
|
+
};
|
|
78
|
+
}
|
|
79
|
+
function finiteDetailNumber(value) {
|
|
80
|
+
return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
|
|
81
|
+
}
|
|
51
82
|
function formatResearchDraftBlock(message, argv) {
|
|
52
83
|
const stateMatch = /Cannot generate draft in state "(research_running|research_complete)"/i.exec(message);
|
|
53
84
|
if (!stateMatch)
|
package/dist/parser.js
CHANGED
|
@@ -25,6 +25,7 @@ export function parseCliArgs(argv) {
|
|
|
25
25
|
password: { type: 'string' },
|
|
26
26
|
'with-publish': { type: 'boolean', default: false },
|
|
27
27
|
'no-browser': { type: 'boolean', default: false },
|
|
28
|
+
'local-only': { type: 'boolean', default: false },
|
|
28
29
|
yes: { type: 'boolean', default: false },
|
|
29
30
|
wait: { type: 'boolean', default: false },
|
|
30
31
|
force: { type: 'boolean', default: false },
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@clickminded/coauthor-cli",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.18",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"bin": {
|
|
6
6
|
"coauthor": "dist/index.js",
|
|
@@ -26,7 +26,8 @@
|
|
|
26
26
|
"scripts": {
|
|
27
27
|
"build": "tsc",
|
|
28
28
|
"postinstall": "node scripts/postinstall.mjs",
|
|
29
|
-
"test": "node --import tsx --test test/*.test.ts",
|
|
29
|
+
"test": "node scripts/verify-skill-sync.mjs && node --import tsx --test test/*.test.ts",
|
|
30
|
+
"verify:skill-sync": "node scripts/verify-skill-sync.mjs",
|
|
30
31
|
"typecheck": "tsc --noEmit"
|
|
31
32
|
},
|
|
32
33
|
"dependencies": {
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
import { readFile } from 'node:fs/promises'
|
|
4
|
+
import { dirname, resolve } from 'node:path'
|
|
5
|
+
import { fileURLToPath } from 'node:url'
|
|
6
|
+
|
|
7
|
+
const scriptDir = dirname(fileURLToPath(import.meta.url))
|
|
8
|
+
const repoRoot = resolve(scriptDir, '../../../..')
|
|
9
|
+
|
|
10
|
+
const groups = [
|
|
11
|
+
{
|
|
12
|
+
canonical: 'coauthor/packages/cli/skills/agents/SKILL.md',
|
|
13
|
+
copies: [
|
|
14
|
+
'coauthor/packages/cli/skills/codex/SKILL.md',
|
|
15
|
+
'coauthor/packages/cli/skills/claude/SKILL.md',
|
|
16
|
+
'coauthor/.agents/skills/coauthor/SKILL.md',
|
|
17
|
+
'coauthor/.claude/skills/coauthor/SKILL.md',
|
|
18
|
+
],
|
|
19
|
+
optionalCopies: ['.agents/skills/coauthor/SKILL.md'],
|
|
20
|
+
},
|
|
21
|
+
{
|
|
22
|
+
canonical: 'coauthor/packages/cli/skills/cursor/coauthor-cli.mdc',
|
|
23
|
+
copies: ['coauthor/.cursor/rules/coauthor-cli.mdc'],
|
|
24
|
+
},
|
|
25
|
+
]
|
|
26
|
+
|
|
27
|
+
const mismatches = []
|
|
28
|
+
|
|
29
|
+
for (const group of groups) {
|
|
30
|
+
const canonical = await read(group.canonical)
|
|
31
|
+
for (const copyPath of group.copies) {
|
|
32
|
+
const copy = await read(copyPath)
|
|
33
|
+
if (copy !== canonical) {
|
|
34
|
+
mismatches.push(`${copyPath} differs from ${group.canonical}`)
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
for (const copyPath of group.optionalCopies ?? []) {
|
|
38
|
+
const copy = await read(copyPath, { optional: true })
|
|
39
|
+
if (copy !== null && copy !== canonical) {
|
|
40
|
+
mismatches.push(`${copyPath} differs from ${group.canonical}`)
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
if (mismatches.length > 0) {
|
|
46
|
+
process.stderr.write(`CoAuthor skill synchronization failed:\n- ${mismatches.join('\n- ')}\n`)
|
|
47
|
+
process.exitCode = 1
|
|
48
|
+
} else {
|
|
49
|
+
process.stdout.write('CoAuthor skill copies are synchronized.\n')
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
async function read(relativePath, options = {}) {
|
|
53
|
+
try {
|
|
54
|
+
return await readFile(resolve(repoRoot, relativePath), 'utf8')
|
|
55
|
+
} catch (error) {
|
|
56
|
+
if (options.optional && error.code === 'ENOENT') return null
|
|
57
|
+
throw new Error(`Could not read ${relativePath}: ${error.message}`)
|
|
58
|
+
}
|
|
59
|
+
}
|
package/skills/agents/SKILL.md
CHANGED
|
@@ -14,7 +14,11 @@ 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: "
|
|
17
|
+
- Treat `status: "credits_exhausted"` or `paused_credits_exhausted` as a saved, recoverable Starter pause. Do not ask a Starter user to add an API key: Starter cannot use BYOK. Report `reset_at`, `allowance`, `used`, `held`, and `remaining` from the response, then resume with `coauthor workflow resume <project-id> --wait --json` after credits reset.
|
|
18
|
+
- Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable Pro pause. Tell the user which `required_providers` are compatible, have them add the key in CoAuthor AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`. Never ask them to paste a key into chat or the terminal.
|
|
19
|
+
- Treat `coauthor_access_required` as an entitlement failure. Project and workflow commands remain blocked until CoAuthor access is restored; `coauthor auth status` and `coauthor auth logout` remain safe recovery commands.
|
|
20
|
+
- Use normal `coauthor auth logout` so remote revocation is confirmed before local credentials are removed. If it fails, report that the credential was preserved for retry; never use `--local-only` unless the user explicitly accepts leaving the remote token potentially active.
|
|
21
|
+
- Treat `entitlement_sync_unavailable` as a temporary Drip verification failure. Do not retry writes or credit-spending work in a loop. Read-only inspection may remain available while login and scheduled reconciliation retry verification.
|
|
18
22
|
- Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
|
|
19
23
|
- Treat `status: "research_running_stale"` or `data.diagnostic.code: "research_running_stale"` as a stale research run. Inspect `coauthor research structured <project-id> --json` and use the returned next commands instead of retrying blindly.
|
|
20
24
|
- Treat `status: "research_structuring"` or `data.diagnostic.code: "research_structuring"` as a normal transition after raw research completes. Keep waiting or resume toward draft; do not rewind or generate a draft until project state reaches `research_structured`.
|
|
@@ -22,11 +26,24 @@ This skill guides agent use of the CoAuthor CLI.
|
|
|
22
26
|
- `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
27
|
- 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
28
|
- Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
|
|
29
|
+
- Use `coauthor share <project-id> --json` to mint or fetch the project's public share URL (`share_url`). Safe to call repeatedly: it returns the existing token instead of minting a new one.
|
|
25
30
|
- 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
31
|
- Use `coauthor models preferences show|set` to inspect or update saved planning/writing preferences. Internal structuring models are not exposed through the CLI.
|
|
27
32
|
- After a timeout, interruption, network error, or unclear result, check operation status before retrying.
|
|
28
33
|
- `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.
|
|
29
34
|
|
|
35
|
+
## Plans, Models, And Credits
|
|
36
|
+
|
|
37
|
+
- Starter includes 2,500 credits per monthly subscription-anniversary period. It supports the full user-visible model list, but it cannot store or use customer provider keys. When its credits reach zero, work pauses until the next reset.
|
|
38
|
+
- Pro includes 6,000 credits per monthly subscription-anniversary period. It also supports the full model list. CoAuthor uses included credits first, then can continue with a compatible configured provider key.
|
|
39
|
+
- Model selection and BYOK are separate. A missing user key must never disable a supported model while included credits remain.
|
|
40
|
+
- `coauthor credits <project-id> --json` reports the current plan, included allowance, used and held credits, remaining credits, and reset time. Do not infer a reset from a WooCommerce renewal event; periods derive from the original subscription start.
|
|
41
|
+
- `byok_not_allowed` means the current plan cannot create, validate, or use provider keys. Starter users may delete keys retained from a previous Pro subscription, but those keys stay inactive until Pro access returns.
|
|
42
|
+
- Device tokens do not grant CoAuthor access by themselves. A previously issued token can remain valid while project commands return `coauthor_access_required`; it becomes usable again if access is restored before the token expires or is revoked.
|
|
43
|
+
- Drip tags alone determine customer access and plan. Subscription observations are diagnostic and set anniversary timing only: every status is retained, only an `active` observation can promote an anchor, and renewals do not reset credits.
|
|
44
|
+
- A genuine later active resubscription starts new anniversary periods for work authorized on or after its start; historical periods and earlier work remain attached to the previous subscription.
|
|
45
|
+
- The Supabase `admins` table is the canonical admin source. Admins bypass customer access and quota checks across web, billing, workers, and the agent API.
|
|
46
|
+
|
|
30
47
|
## Project Briefing
|
|
31
48
|
|
|
32
49
|
- For simple starts, use `coauthor project create --title "..." --topic "prose brief" --audience "target reader" --json`.
|
package/skills/claude/SKILL.md
CHANGED
|
@@ -14,7 +14,11 @@ 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: "
|
|
17
|
+
- Treat `status: "credits_exhausted"` or `paused_credits_exhausted` as a saved, recoverable Starter pause. Do not ask a Starter user to add an API key: Starter cannot use BYOK. Report `reset_at`, `allowance`, `used`, `held`, and `remaining` from the response, then resume with `coauthor workflow resume <project-id> --wait --json` after credits reset.
|
|
18
|
+
- Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable Pro pause. Tell the user which `required_providers` are compatible, have them add the key in CoAuthor AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`. Never ask them to paste a key into chat or the terminal.
|
|
19
|
+
- Treat `coauthor_access_required` as an entitlement failure. Project and workflow commands remain blocked until CoAuthor access is restored; `coauthor auth status` and `coauthor auth logout` remain safe recovery commands.
|
|
20
|
+
- Use normal `coauthor auth logout` so remote revocation is confirmed before local credentials are removed. If it fails, report that the credential was preserved for retry; never use `--local-only` unless the user explicitly accepts leaving the remote token potentially active.
|
|
21
|
+
- Treat `entitlement_sync_unavailable` as a temporary Drip verification failure. Do not retry writes or credit-spending work in a loop. Read-only inspection may remain available while login and scheduled reconciliation retry verification.
|
|
18
22
|
- Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
|
|
19
23
|
- Treat `status: "research_running_stale"` or `data.diagnostic.code: "research_running_stale"` as a stale research run. Inspect `coauthor research structured <project-id> --json` and use the returned next commands instead of retrying blindly.
|
|
20
24
|
- Treat `status: "research_structuring"` or `data.diagnostic.code: "research_structuring"` as a normal transition after raw research completes. Keep waiting or resume toward draft; do not rewind or generate a draft until project state reaches `research_structured`.
|
|
@@ -22,11 +26,24 @@ This skill guides agent use of the CoAuthor CLI.
|
|
|
22
26
|
- `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
27
|
- 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
28
|
- Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
|
|
29
|
+
- Use `coauthor share <project-id> --json` to mint or fetch the project's public share URL (`share_url`). Safe to call repeatedly: it returns the existing token instead of minting a new one.
|
|
25
30
|
- 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
31
|
- Use `coauthor models preferences show|set` to inspect or update saved planning/writing preferences. Internal structuring models are not exposed through the CLI.
|
|
27
32
|
- After a timeout, interruption, network error, or unclear result, check operation status before retrying.
|
|
28
33
|
- `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.
|
|
29
34
|
|
|
35
|
+
## Plans, Models, And Credits
|
|
36
|
+
|
|
37
|
+
- Starter includes 2,500 credits per monthly subscription-anniversary period. It supports the full user-visible model list, but it cannot store or use customer provider keys. When its credits reach zero, work pauses until the next reset.
|
|
38
|
+
- Pro includes 6,000 credits per monthly subscription-anniversary period. It also supports the full model list. CoAuthor uses included credits first, then can continue with a compatible configured provider key.
|
|
39
|
+
- Model selection and BYOK are separate. A missing user key must never disable a supported model while included credits remain.
|
|
40
|
+
- `coauthor credits <project-id> --json` reports the current plan, included allowance, used and held credits, remaining credits, and reset time. Do not infer a reset from a WooCommerce renewal event; periods derive from the original subscription start.
|
|
41
|
+
- `byok_not_allowed` means the current plan cannot create, validate, or use provider keys. Starter users may delete keys retained from a previous Pro subscription, but those keys stay inactive until Pro access returns.
|
|
42
|
+
- Device tokens do not grant CoAuthor access by themselves. A previously issued token can remain valid while project commands return `coauthor_access_required`; it becomes usable again if access is restored before the token expires or is revoked.
|
|
43
|
+
- Drip tags alone determine customer access and plan. Subscription observations are diagnostic and set anniversary timing only: every status is retained, only an `active` observation can promote an anchor, and renewals do not reset credits.
|
|
44
|
+
- A genuine later active resubscription starts new anniversary periods for work authorized on or after its start; historical periods and earlier work remain attached to the previous subscription.
|
|
45
|
+
- The Supabase `admins` table is the canonical admin source. Admins bypass customer access and quota checks across web, billing, workers, and the agent API.
|
|
46
|
+
|
|
30
47
|
## Project Briefing
|
|
31
48
|
|
|
32
49
|
- For simple starts, use `coauthor project create --title "..." --topic "prose brief" --audience "target reader" --json`.
|
package/skills/codex/SKILL.md
CHANGED
|
@@ -14,7 +14,11 @@ 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: "
|
|
17
|
+
- Treat `status: "credits_exhausted"` or `paused_credits_exhausted` as a saved, recoverable Starter pause. Do not ask a Starter user to add an API key: Starter cannot use BYOK. Report `reset_at`, `allowance`, `used`, `held`, and `remaining` from the response, then resume with `coauthor workflow resume <project-id> --wait --json` after credits reset.
|
|
18
|
+
- Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable Pro pause. Tell the user which `required_providers` are compatible, have them add the key in CoAuthor AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`. Never ask them to paste a key into chat or the terminal.
|
|
19
|
+
- Treat `coauthor_access_required` as an entitlement failure. Project and workflow commands remain blocked until CoAuthor access is restored; `coauthor auth status` and `coauthor auth logout` remain safe recovery commands.
|
|
20
|
+
- Use normal `coauthor auth logout` so remote revocation is confirmed before local credentials are removed. If it fails, report that the credential was preserved for retry; never use `--local-only` unless the user explicitly accepts leaving the remote token potentially active.
|
|
21
|
+
- Treat `entitlement_sync_unavailable` as a temporary Drip verification failure. Do not retry writes or credit-spending work in a loop. Read-only inspection may remain available while login and scheduled reconciliation retry verification.
|
|
18
22
|
- Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
|
|
19
23
|
- Treat `status: "research_running_stale"` or `data.diagnostic.code: "research_running_stale"` as a stale research run. Inspect `coauthor research structured <project-id> --json` and use the returned next commands instead of retrying blindly.
|
|
20
24
|
- Treat `status: "research_structuring"` or `data.diagnostic.code: "research_structuring"` as a normal transition after raw research completes. Keep waiting or resume toward draft; do not rewind or generate a draft until project state reaches `research_structured`.
|
|
@@ -22,11 +26,24 @@ This skill guides agent use of the CoAuthor CLI.
|
|
|
22
26
|
- `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
27
|
- 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
28
|
- Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
|
|
29
|
+
- Use `coauthor share <project-id> --json` to mint or fetch the project's public share URL (`share_url`). Safe to call repeatedly: it returns the existing token instead of minting a new one.
|
|
25
30
|
- 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
31
|
- Use `coauthor models preferences show|set` to inspect or update saved planning/writing preferences. Internal structuring models are not exposed through the CLI.
|
|
27
32
|
- After a timeout, interruption, network error, or unclear result, check operation status before retrying.
|
|
28
33
|
- `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.
|
|
29
34
|
|
|
35
|
+
## Plans, Models, And Credits
|
|
36
|
+
|
|
37
|
+
- Starter includes 2,500 credits per monthly subscription-anniversary period. It supports the full user-visible model list, but it cannot store or use customer provider keys. When its credits reach zero, work pauses until the next reset.
|
|
38
|
+
- Pro includes 6,000 credits per monthly subscription-anniversary period. It also supports the full model list. CoAuthor uses included credits first, then can continue with a compatible configured provider key.
|
|
39
|
+
- Model selection and BYOK are separate. A missing user key must never disable a supported model while included credits remain.
|
|
40
|
+
- `coauthor credits <project-id> --json` reports the current plan, included allowance, used and held credits, remaining credits, and reset time. Do not infer a reset from a WooCommerce renewal event; periods derive from the original subscription start.
|
|
41
|
+
- `byok_not_allowed` means the current plan cannot create, validate, or use provider keys. Starter users may delete keys retained from a previous Pro subscription, but those keys stay inactive until Pro access returns.
|
|
42
|
+
- Device tokens do not grant CoAuthor access by themselves. A previously issued token can remain valid while project commands return `coauthor_access_required`; it becomes usable again if access is restored before the token expires or is revoked.
|
|
43
|
+
- Drip tags alone determine customer access and plan. Subscription observations are diagnostic and set anniversary timing only: every status is retained, only an `active` observation can promote an anchor, and renewals do not reset credits.
|
|
44
|
+
- A genuine later active resubscription starts new anniversary periods for work authorized on or after its start; historical periods and earlier work remain attached to the previous subscription.
|
|
45
|
+
- The Supabase `admins` table is the canonical admin source. Admins bypass customer access and quota checks across web, billing, workers, and the agent API.
|
|
46
|
+
|
|
30
47
|
## Project Briefing
|
|
31
48
|
|
|
32
49
|
- For simple starts, use `coauthor project create --title "..." --topic "prose brief" --audience "target reader" --json`.
|
|
@@ -11,7 +11,11 @@ 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: "
|
|
14
|
+
- Treat `status: "credits_exhausted"` or `paused_credits_exhausted` as a saved, recoverable Starter pause. Do not ask a Starter user to add a key; report `reset_at`, `allowance`, `used`, `held`, and `remaining`, then resume after the credit reset.
|
|
15
|
+
- Treat `status: "requires_key"` or `paused_requires_key` as a saved, recoverable Pro pause. Report compatible `required_providers`, have the user add a key in CoAuthor AI settings, then resume. Never ask them to paste a key into chat or the terminal.
|
|
16
|
+
- Treat `coauthor_access_required` as an entitlement failure. Project and workflow commands remain blocked until access returns; auth status/logout remain available.
|
|
17
|
+
- Use normal `coauthor auth logout` so remote revocation is confirmed before local credentials are removed. If it fails, report that the credential was preserved for retry; never use `--local-only` unless the user explicitly accepts leaving the remote token potentially active.
|
|
18
|
+
- Treat `entitlement_sync_unavailable` as a temporary Drip verification failure. Do not retry writes or credit-spending work in a loop; read-only inspection may remain available while login and scheduled reconciliation retry.
|
|
15
19
|
- Treat `status: "blocked_by_research"` as an actionable blocked state. Use the returned `recovery_commands` instead of retrying blindly.
|
|
16
20
|
- Treat `status: "research_running_stale"` or `data.diagnostic.code: "research_running_stale"` as a stale research run. Inspect `coauthor research structured <project-id> --json` and use the returned next commands instead of retrying blindly.
|
|
17
21
|
- Treat `status: "research_structuring"` or `data.diagnostic.code: "research_structuring"` as a normal transition after raw research completes. Keep waiting or resume toward draft; do not rewind or generate a draft until project state reaches `research_structured`.
|
|
@@ -19,8 +23,16 @@ alwaysApply: true
|
|
|
19
23
|
- `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
24
|
- 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
25
|
- Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
|
|
26
|
+
- Use `coauthor share <project-id> --json` to mint or fetch the project's public share URL (`share_url`). Safe to call repeatedly: it returns the existing token instead of minting a new one.
|
|
22
27
|
- 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
28
|
- Use `coauthor models preferences show|set` to inspect or update saved planning/writing preferences. Internal structuring models are not exposed through the CLI.
|
|
29
|
+
- Starter includes 2,500 credits per monthly subscription-anniversary period, can select any supported user-visible model, cannot use BYOK, and waits for reset after `credits_exhausted`.
|
|
30
|
+
- Pro includes 6,000 credits per monthly subscription-anniversary period and uses included credits before a compatible configured provider key. Model selection does not depend on key presence while credits remain.
|
|
31
|
+
- `byok_not_allowed` means the current plan cannot create, validate, or use provider keys. Starter may delete retained keys, but they remain inactive until Pro access returns.
|
|
32
|
+
- Device tokens do not grant access by themselves. A valid token can return `coauthor_access_required` and work again after access is restored.
|
|
33
|
+
- Drip tags alone determine customer access/plan. Subscription observations are diagnostic and set anniversary timing only; all statuses persist, only active observations promote anchors, and renewals do not reset credits.
|
|
34
|
+
- A genuine later active resubscription moves only work authorized on or after its start to new periods; historical periods remain intact.
|
|
35
|
+
- The Supabase `admins` table is the canonical admin source and grants the cross-surface access/quota bypass.
|
|
24
36
|
- After timeout, interruption, network error, or ambiguous output, check operation status before retrying or reporting success.
|
|
25
37
|
- `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
38
|
- For simple starts, use `coauthor project create --title "..." --topic "prose brief" --audience "target reader" --json`.
|