@clickminded/coauthor-cli 0.0.16 → 0.0.17

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
@@ -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,7 +103,7 @@ 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.5 --writing-model gpt-5.4 --wait --json
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
99
109
  ```
@@ -103,17 +113,19 @@ List and save text model preferences:
103
113
  ```sh
104
114
  coauthor models list
105
115
  coauthor models preferences show --json
106
- coauthor models preferences set --planning-model gpt-5.5 --writing-model gpt-5.4 --json
116
+ coauthor models preferences set --planning-model gpt-5.6-sol --writing-model gpt-5.6-terra --json
107
117
  ```
108
118
 
119
+ 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.
120
+
109
121
  Read or generate artifacts:
110
122
 
111
123
  ```sh
112
124
  coauthor contract show <project-id> --json
113
125
  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
126
+ coauthor research-plan generate <project-id> --planning-model gpt-5.6-sol --json
115
127
  coauthor research run <project-id> --wait --json
116
- coauthor draft generate <project-id> --writing-model gpt-5.4 --wait --json
128
+ coauthor draft generate <project-id> --writing-model gpt-5.6-terra --wait --json
117
129
  coauthor draft get <project-id> --format markdown --json
118
130
  ```
119
131
 
@@ -122,7 +134,7 @@ Images and social content:
122
134
  ```sh
123
135
  coauthor image list <project-id> --json
124
136
  coauthor image generate <project-id> --placeholder-id <placeholder-id> --prompt "Image direction" --json
125
- coauthor thread generate <project-id> --writing-model gpt-5.4 --json
137
+ coauthor thread generate <project-id> --writing-model gpt-5.6-terra --json
126
138
  ```
127
139
 
128
140
  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 +181,9 @@ Agents should:
169
181
  - Prefer `coauthor` commands over browser automation, hand-written HTTP requests, or direct database access.
170
182
  - Use `--json` for machine-readable output.
171
183
  - Use `--wait` when starting asynchronous work and the user expects the result.
172
- - Treat `status: "requires_key"` or `paused_requires_key` as a recoverable pause. Ask the user to add the required provider key in CoAuthor AI settings, then resume with `coauthor workflow resume <project-id> --wait --json`.
184
+ - 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.
185
+ - 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`.
186
+ - 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
187
  - Treat `status: "research_running_stale"` as a stale research run and inspect `coauthor research structured <project-id> --json` before retrying.
174
188
  - Check operation status after timeouts, interruptions, network errors, or uncertain live-action results.
175
189
  - Never print tokens, cookies, provider keys, service-role keys, or authorization headers.
@@ -180,7 +194,7 @@ Agents should:
180
194
  - Default login grants workflow/project scopes only.
181
195
  - Publish/export scope is granted only when login is started with `--with-publish`.
182
196
  - Tokens are stored locally at `~/.coauthor/config.json`.
183
- - Run `coauthor auth logout` to revoke the current token and remove local credentials.
197
+ - 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
198
 
185
199
  ## Troubleshooting
186
200
 
@@ -190,7 +204,17 @@ Agents should:
190
204
 
191
205
  `authorization_pending` during login is normal while the browser approval page is waiting for approval.
192
206
 
193
- `requires_key` means included credits are exhausted and no usable provider key is configured for the requested capability. Open CoAuthor AI settings, add the required key, then run `coauthor workflow resume <project-id> --wait --json`.
207
+ 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.
208
+
209
+ `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.
210
+
211
+ `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.
212
+
213
+ `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.
214
+
215
+ `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`.
216
+
217
+ `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
218
 
195
219
  `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
220
 
@@ -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
@@ -132,19 +132,71 @@ async function runAuthCommand(action, input, context) {
132
132
  };
133
133
  }
134
134
  if (action === 'logout') {
135
- if (context.token) {
136
- try {
137
- await context.client.request({ method: 'POST', path: 'auth/logout', body: {} });
138
- }
139
- catch {
140
- // Local logout should still clear credentials if the server is unavailable.
135
+ const localOnly = getBoolean(input.values, 'local-only');
136
+ if (!context.token) {
137
+ await clearConfig(context.paths);
138
+ return {
139
+ ok: true,
140
+ message: 'No local token configured.',
141
+ data: { authenticated: false, remoteRevoked: null, localOnly },
142
+ };
143
+ }
144
+ if (localOnly) {
145
+ await clearConfig(context.paths);
146
+ return {
147
+ ok: true,
148
+ message: 'Local credentials removed without revoking the remote token.',
149
+ data: {
150
+ authenticated: false,
151
+ remoteRevoked: false,
152
+ localOnly: true,
153
+ remoteTokenMayRemainActive: true,
154
+ },
155
+ };
156
+ }
157
+ try {
158
+ await context.client.request({ method: 'POST', path: 'auth/logout', body: {} });
159
+ }
160
+ catch (error) {
161
+ const inactiveCode = inactiveAgentTokenCode(error);
162
+ if (!inactiveCode) {
163
+ 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
164
  }
165
+ await clearConfig(context.paths);
166
+ return {
167
+ ok: true,
168
+ message: inactiveCode === 'token_revoked'
169
+ ? 'Logged out; the remote token was already revoked and local credentials were removed.'
170
+ : 'Logged out; the remote token was already expired and local credentials were removed.',
171
+ data: {
172
+ authenticated: false,
173
+ remoteRevoked: true,
174
+ localOnly: false,
175
+ alreadyInactive: true,
176
+ },
177
+ };
142
178
  }
143
179
  await clearConfig(context.paths);
144
- return { ok: true, message: 'Logged out', data: { authenticated: false } };
180
+ return {
181
+ ok: true,
182
+ message: 'Logged out; remote token revoked and local credentials removed.',
183
+ data: { authenticated: false, remoteRevoked: true, localOnly: false },
184
+ };
145
185
  }
146
186
  throw new Error('Usage: coauthor auth <login|status|logout>');
147
187
  }
188
+ function inactiveAgentTokenCode(error) {
189
+ if (!(error instanceof AgentHttpError))
190
+ return null;
191
+ const body = error.responseBody;
192
+ if (!body || typeof body !== 'object' || Array.isArray(body))
193
+ return null;
194
+ const envelope = body.error;
195
+ if (!envelope || typeof envelope !== 'object' || Array.isArray(envelope))
196
+ return null;
197
+ const code = envelope.code;
198
+ return code === 'token_revoked' || code === 'token_expired' ? code : null;
199
+ }
148
200
  async function runProjectCommand(action, input, client) {
149
201
  if (action === 'create') {
150
202
  const body = withNamedOptions(parseJsonOption(input.values), input.values, ['title', 'topic', 'audience']);
@@ -226,7 +278,7 @@ async function runWorkflowCommand(action, input, context) {
226
278
  return getBoolean(input.values, 'wait') ? waitForResearch(client, projectId, data, context.baseUrl) : { ok: true, data };
227
279
  }
228
280
  const researchStatus = await client.request({ path: `projects/${encodeURIComponent(projectId)}/research/status` });
229
- if (extractNestedString(researchStatus, ['run', 'status']) === 'paused_requires_key') {
281
+ if (['paused_requires_key', 'paused_credits_exhausted'].includes(extractNestedString(researchStatus, ['run', 'status']) ?? '')) {
230
282
  if (modelOverrides.writingModel && !getBoolean(input.values, 'wait')) {
231
283
  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
284
  }
@@ -234,7 +286,7 @@ async function runWorkflowCommand(action, input, context) {
234
286
  return getBoolean(input.values, 'wait') ? waitForWorkflowDraft(client, projectId, data, context.baseUrl, modelOverrides) : { ok: true, data };
235
287
  }
236
288
  const draftStatus = await client.request({ path: `projects/${encodeURIComponent(projectId)}/draft/status` });
237
- if (getResponseString(draftStatus, 'phase') === 'paused_requires_key') {
289
+ if (['paused_requires_key', 'paused_credits_exhausted'].includes(getResponseString(draftStatus, 'phase') ?? '')) {
238
290
  const data = await client.request({ method: 'POST', path: `projects/${encodeURIComponent(projectId)}/draft/generate`, body: modelOverrides });
239
291
  return getBoolean(input.values, 'wait') ? waitForDraft(client, projectId, data, context.baseUrl) : { ok: true, data };
240
292
  }
@@ -735,6 +787,9 @@ async function waitForResearch(client, projectId, initialData, baseUrl) {
735
787
  if (status === 'paused_requires_key') {
736
788
  return requiresKeyPauseResult(projectId, 'research', extractNestedString(latest, ['run', 'error_message']) ?? 'Research paused: add the required API key to continue.', latest, baseUrl);
737
789
  }
790
+ if (status === 'paused_credits_exhausted') {
791
+ return creditsExhaustedPauseResult(projectId, 'research', extractNestedString(latest, ['run', 'error_message']) ?? 'Research paused until included credits reset.', latest);
792
+ }
738
793
  const stale = researchRunningStaleResult(projectId, latest, null, initialData);
739
794
  if (stale)
740
795
  return stale;
@@ -755,6 +810,8 @@ async function waitForDraft(client, projectId, initialData, baseUrl) {
755
810
  }
756
811
  if (phase === 'paused_requires_key')
757
812
  return requiresKeyPauseResult(projectId, 'draft', getResponseString(latest, 'message') ?? 'Draft paused: add the required API key to continue.', latest, baseUrl);
813
+ if (phase === 'paused_credits_exhausted')
814
+ return creditsExhaustedPauseResult(projectId, 'draft', getResponseString(latest, 'message') ?? 'Draft paused until included credits reset.', latest);
758
815
  if (phase === 'failed')
759
816
  throw new Error(getResponseString(latest, 'message') ?? 'Draft generation failed');
760
817
  }
@@ -793,6 +850,13 @@ async function waitForWorkflowDraft(client, projectId, initialData, baseUrl, mod
793
850
  draft_status: latestDraft,
794
851
  }, baseUrl);
795
852
  }
853
+ if (draftPhase === 'paused_credits_exhausted') {
854
+ return creditsExhaustedPauseResult(projectId, 'draft', getResponseString(latestDraft, 'message') ?? 'Draft paused until included credits reset.', {
855
+ workflow: initialData,
856
+ research_status: latestResearch,
857
+ draft_status: latestDraft,
858
+ });
859
+ }
796
860
  latestResearch = await client.request({ path: `projects/${encodeURIComponent(projectId)}/research/status` });
797
861
  const researchStatus = extractNestedString(latestResearch, ['run', 'status']);
798
862
  if (researchStatus === 'failed') {
@@ -805,6 +869,13 @@ async function waitForWorkflowDraft(client, projectId, initialData, baseUrl, mod
805
869
  draft_status: latestDraft,
806
870
  }, baseUrl);
807
871
  }
872
+ if (researchStatus === 'paused_credits_exhausted') {
873
+ return creditsExhaustedPauseResult(projectId, 'research', extractNestedString(latestResearch, ['run', 'error_message']) ?? 'Research paused until included credits reset.', {
874
+ workflow: initialData,
875
+ research_status: latestResearch,
876
+ draft_status: latestDraft,
877
+ });
878
+ }
808
879
  const stale = researchRunningStaleResult(projectId, latestResearch, latestDraft, initialData);
809
880
  if (stale)
810
881
  return stale;
@@ -1003,6 +1074,49 @@ function requiresKeyPauseResult(projectId, target, message, data, baseUrl) {
1003
1074
  data,
1004
1075
  };
1005
1076
  }
1077
+ export function creditsExhaustedPauseResult(projectId, target, message, data) {
1078
+ const resumeCommand = `coauthor workflow resume ${projectId} --target ${target} --wait --json`;
1079
+ const resetAt = extractCreditPauseString(data, 'reset_at');
1080
+ const allowance = extractCreditPauseNumber(data, 'allowance');
1081
+ const used = extractCreditPauseNumber(data, 'used');
1082
+ const held = extractCreditPauseNumber(data, 'held');
1083
+ const remaining = extractCreditPauseNumber(data, 'remaining');
1084
+ return {
1085
+ ok: false,
1086
+ status: 'credits_exhausted',
1087
+ exitCode: 2,
1088
+ message: `${message}\nResume after reset: ${resumeCommand}`,
1089
+ resume_command: resumeCommand,
1090
+ ...(typeof resetAt === 'string' ? { reset_at: resetAt } : {}),
1091
+ ...(allowance !== undefined ? { allowance } : {}),
1092
+ ...(used !== undefined ? { used } : {}),
1093
+ ...(held !== undefined ? { held } : {}),
1094
+ ...(remaining !== undefined ? { remaining } : {}),
1095
+ data,
1096
+ };
1097
+ }
1098
+ const CREDIT_PAUSE_DETAIL_PREFIXES = [
1099
+ ['run', 'pause_metadata'],
1100
+ ['detail'],
1101
+ ['draft_status', 'detail'],
1102
+ ['research_status', 'run', 'pause_metadata'],
1103
+ ];
1104
+ function extractCreditPauseString(data, key) {
1105
+ for (const prefix of CREDIT_PAUSE_DETAIL_PREFIXES) {
1106
+ const value = extractNestedString(data, [...prefix, key]);
1107
+ if (value !== undefined)
1108
+ return value;
1109
+ }
1110
+ return undefined;
1111
+ }
1112
+ function extractCreditPauseNumber(data, key) {
1113
+ for (const prefix of CREDIT_PAUSE_DETAIL_PREFIXES) {
1114
+ const value = extractNestedValue(data, [...prefix, key]);
1115
+ if (typeof value === 'number' && Number.isFinite(value))
1116
+ return value;
1117
+ }
1118
+ return undefined;
1119
+ }
1006
1120
  function extractNestedString(value, path) {
1007
1121
  const current = extractNestedValue(value, path);
1008
1122
  return typeof current === 'string' ? current : undefined;
@@ -1068,7 +1182,7 @@ export function helpResult(command = []) {
1068
1182
  'Usage: coauthor <command> [options]',
1069
1183
  '',
1070
1184
  'Commands:',
1071
- ' auth login|status|logout',
1185
+ ' auth login|status|logout (logout supports --local-only)',
1072
1186
  ' project create|list|show',
1073
1187
  ' workspace show',
1074
1188
  ' chat [show|list]',
@@ -1096,6 +1210,12 @@ export function helpResult(command = []) {
1096
1210
  function commandHelp(command) {
1097
1211
  const key = command.join(' ');
1098
1212
  const help = {
1213
+ 'auth logout': [
1214
+ 'Usage: coauthor auth logout [--local-only] [--json]',
1215
+ '',
1216
+ 'Revokes the remote token before removing local credentials. If revocation cannot be confirmed, the token is kept locally so the command can be retried.',
1217
+ '--local-only removes the local credential without revoking the remote token. Use it only when explicitly abandoning remote revocation.',
1218
+ ].join('\n'),
1099
1219
  'project create': [
1100
1220
  'Usage: coauthor project create [--title <title>] [--topic <brief>] [--audience <audience>] [--contract <json>] [--json]',
1101
1221
  '',
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.16",
3
+ "version": "0.0.17",
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
+ }
@@ -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: "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`.
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`.
@@ -27,6 +31,18 @@ This skill guides agent use of the CoAuthor CLI.
27
31
  - After a timeout, interruption, network error, or unclear result, check operation status before retrying.
28
32
  - `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
33
 
34
+ ## Plans, Models, And Credits
35
+
36
+ - 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.
37
+ - 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.
38
+ - Model selection and BYOK are separate. A missing user key must never disable a supported model while included credits remain.
39
+ - `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.
40
+ - `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.
41
+ - 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.
42
+ - 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.
43
+ - 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.
44
+ - The Supabase `admins` table is the canonical admin source. Admins bypass customer access and quota checks across web, billing, workers, and the agent API.
45
+
30
46
  ## Project Briefing
31
47
 
32
48
  - For simple starts, use `coauthor project create --title "..." --topic "prose brief" --audience "target reader" --json`.
@@ -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: "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`.
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`.
@@ -27,6 +31,18 @@ This skill guides agent use of the CoAuthor CLI.
27
31
  - After a timeout, interruption, network error, or unclear result, check operation status before retrying.
28
32
  - `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
33
 
34
+ ## Plans, Models, And Credits
35
+
36
+ - 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.
37
+ - 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.
38
+ - Model selection and BYOK are separate. A missing user key must never disable a supported model while included credits remain.
39
+ - `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.
40
+ - `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.
41
+ - 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.
42
+ - 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.
43
+ - 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.
44
+ - The Supabase `admins` table is the canonical admin source. Admins bypass customer access and quota checks across web, billing, workers, and the agent API.
45
+
30
46
  ## Project Briefing
31
47
 
32
48
  - For simple starts, use `coauthor project create --title "..." --topic "prose brief" --audience "target reader" --json`.
@@ -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: "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`.
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`.
@@ -27,6 +31,18 @@ This skill guides agent use of the CoAuthor CLI.
27
31
  - After a timeout, interruption, network error, or unclear result, check operation status before retrying.
28
32
  - `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
33
 
34
+ ## Plans, Models, And Credits
35
+
36
+ - 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.
37
+ - 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.
38
+ - Model selection and BYOK are separate. A missing user key must never disable a supported model while included credits remain.
39
+ - `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.
40
+ - `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.
41
+ - 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.
42
+ - 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.
43
+ - 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.
44
+ - The Supabase `admins` table is the canonical admin source. Admins bypass customer access and quota checks across web, billing, workers, and the agent API.
45
+
30
46
  ## Project Briefing
31
47
 
32
48
  - 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: "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`.
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`.
@@ -21,6 +25,13 @@ alwaysApply: true
21
25
  - Use `coauthor credits <project-id> --json` to check credit allowance, pending credits, and remaining credits.
22
26
  - 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
27
  - Use `coauthor models preferences show|set` to inspect or update saved planning/writing preferences. Internal structuring models are not exposed through the CLI.
28
+ - 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`.
29
+ - 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.
30
+ - `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.
31
+ - Device tokens do not grant access by themselves. A valid token can return `coauthor_access_required` and work again after access is restored.
32
+ - 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.
33
+ - A genuine later active resubscription moves only work authorized on or after its start to new periods; historical periods remain intact.
34
+ - The Supabase `admins` table is the canonical admin source and grants the cross-surface access/quota bypass.
24
35
  - After timeout, interruption, network error, or ambiguous output, check operation status before retrying or reporting success.
25
36
  - `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
37
  - For simple starts, use `coauthor project create --title "..." --topic "prose brief" --audience "target reader" --json`.