@clickminded/coauthor-cli 0.0.15 → 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.15",
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`.
@@ -98,10 +114,109 @@ This skill guides agent use of the CoAuthor CLI.
98
114
 
99
115
  - Use `reading_commitment.kind: "preset"` with a preset id for quick length choices; use `"custom"` with explicit `length_guidance` when the user gives a custom range.
100
116
  - Use top-level `canonical_entities`, `outline_seed`, `style_rules`, `must_not_change`, `structure_preference`, and `confidence_notes`. A legacy nested `handoff` object may be normalized, but top-level fields are clearer for agents.
101
- - Example:
117
+ - Field guidance:
118
+ - `topic`: The concrete subject or assignment. Include the search keyword, product, debate, or source brief if that is the true starting point.
119
+ - `angle`: The editorial thesis or framing. Use this to explain what makes this piece different from a generic article on the same topic.
120
+ - `target_audience`: Who the piece is for, including their sophistication, context, objections, and buying or reading intent.
121
+ - `core_promise`: The reader outcome. Phrase it as what the reader will understand, decide, or be able to do after reading.
122
+ - `format`: Human-readable format label, such as `blog post`, `guide`, `listicle`, `case study`, or `long-form SEO comparison guide`.
123
+ - `reading_commitment`: Use a preset when the user picked or implied a length tier. Use `custom` plus `length_guidance` when the user gave a specific range.
124
+ - `length_guidance`: Word-count bounds. Use positive integers or `null`; keep `min_words <= target_words <= max_words` when known.
125
+ - `audience_knowledge_assumptions`: What the reader already knows, so the draft does not over-explain or under-explain.
126
+ - `desired_reader_experience`: How the finished piece should feel to read, such as fast and scannable, authoritative and comprehensive, funny but informative, or practical and no-fluff.
127
+ - `structure_preferences`: List of preferred sections, ordering, comparison/table requirements, intro/conclusion instructions, or other structural choices.
128
+ - `must_include`: Specific points, keywords, URLs, products, claims, examples, or sections that must appear.
129
+ - `must_avoid`: Things to leave out, weak arguments, banned phrasings, unsupported claims, or misleading positioning.
130
+ - `non_negotiables`: Hard constraints that would make the draft wrong if violated. Use this for stricter requirements than ordinary `must_avoid` guidance.
131
+ - `evidence_expectations`: What kind of support the argument needs, such as official docs, pricing pages, public data, examples, or completed research.
132
+ - `citation_expectations`: Which claims need links or citations, preferred source types, and any source URLs that should be used.
133
+ - `liked_examples`: URLs, titles, patterns, or descriptions of examples to emulate.
134
+ - `rejected_examples`: URLs, titles, patterns, or descriptions of examples to avoid.
135
+ - `additional_editorial_guidance`: Any important prose brief that does not fit another field, including voice, pacing, product positioning, or inherited brief details.
136
+ - `editorial_profile`: Structured style controls. Use `notes` for nuance that enum values cannot capture.
137
+ - `canonical_entities`: Stable names for products, people, companies, characters, or concepts that must be referred to consistently. `actor_key` is the stable snake-case id used by `outline_seed.required_actor_keys`.
138
+ - `outline_seed`: Suggested section plan. Use `required_actor_keys` to tie sections to entries in `canonical_entities`.
139
+ - `style_rules`: Reusable sentence-level or formatting rules, such as short paragraphs, markdown tables, direct second person, or no academic hedging.
140
+ - `must_not_change`: Facts, names, positioning statements, URLs, or product limitations that must survive editing unchanged.
141
+ - `structure_preference`: A one-string summary of the overall structure. Use `structure_preferences` for the detailed list.
142
+ - `confidence_notes`: Explain what the contract was based on and where uncertainty remains.
143
+ - Real saved contract examples from the database, compacted for agent reuse:
144
+
145
+ Deep SEO comparison guide:
146
+
147
+ ```json
148
+ {
149
+ "topic": "Write a comprehensive long-form SEO comparison guide targeting the keyword \"mailchimp alternatives\" for ClickMinded Newsletter Generator.",
150
+ "angle": "Satisfy standard Mailchimp alternatives search intent, then show the category-aware distinction between email sending platforms and newsletter production workflows.",
151
+ "target_audience": "Busy founders, creators, consultants, solo marketers, agency owners, and small marketing teams evaluating Mailchimp competitors.",
152
+ "core_promise": "Help readers choose the right Mailchimp alternative by use case while making clear that ClickMinded may be the better fix when the real bottleneck is newsletter production.",
153
+ "format": "long-form SEO comparison guide",
154
+ "reading_commitment": { "kind": "custom", "preset_id": null, "source": "user_explicit" },
155
+ "length_guidance": { "min_words": 3200, "target_words": 3700, "max_words": 4200 },
156
+ "desired_reader_experience": "Comprehensive, practical, fair, and category-aware.",
157
+ "structure_preferences": ["Preserve the existing article structure and heading flow.", "Expand comparison depth for every platform."],
158
+ "must_include": ["Primary keyword \"mailchimp alternatives\" in the H1, intro, one H2 or H3, and conclusion naturally.", "Cover MailerLite, Brevo, Kit, ActiveCampaign, beehiiv, Substack, Klaviyo, Omnisend, Constant Contact, Drip, and Campaign Monitor."],
159
+ "must_avoid": ["Do not make ClickMinded sound like an ESP or Mailchimp replacement.", "Do not imply ClickMinded handles list management, deliverability, automations, forms, ecommerce, analytics, compliance management, or sending."],
160
+ "non_negotiables": ["The article must satisfy search intent for \"mailchimp alternatives\" before pitching ClickMinded.", "The ClickMinded positioning must be category-accurate and honest."],
161
+ "evidence_expectations": ["Use completed research and official pricing/features sources.", "Qualify pricing as current at time of writing."],
162
+ "citation_expectations": ["Use current source links for pricing/features, especially official sources.", "Include the ClickMinded product page and CTA URLs exactly as required."],
163
+ "editorial_profile": { "tone": "balanced", "form": "guide", "depth": "deep", "humor": "none", "section_length": "adaptive", "cadence": "moderate", "notes": "Long-form SEO comparison guide; practical, fair, and category-aware." },
164
+ "canonical_entities": [
165
+ { "actor_key": "clickminded_newsletter_generator", "character_name": "ClickMinded Newsletter Generator", "role_title": "AI newsletter generator and production workflow", "description": "A newsletter production layer. It is not an ESP.", "aliases": ["ClickMinded Newsletter Generator", "ClickMinded"], "must_preserve": true },
166
+ { "actor_key": "mailchimp", "character_name": "Mailchimp", "role_title": "Email marketing platform / ESP", "description": "Email marketing software for list management, sending, automations, forms, templates, analytics, and related ESP functions.", "aliases": ["Mailchimp"], "must_preserve": true }
167
+ ],
168
+ "outline_seed": [
169
+ { "id": "intro_quick_comparison", "heading": "The Best Mailchimp Alternatives in 2026", "intent": "Satisfy core search intent quickly and clarify replacement versus production workflow.", "must_include_points": ["Primary keyword in H1 and intro", "Clarify that some tools replace Mailchimp and ClickMinded complements it by solving production"], "required_actor_keys": ["mailchimp", "clickminded_newsletter_generator"], "notes": "" }
170
+ ],
171
+ "style_rules": ["Use Markdown headings and tables where helpful.", "Keep ClickMinded category-accurate and honest."],
172
+ "must_not_change": ["ClickMinded is not an ESP.", "ClickMinded direct integrations: Mailchimp, GoHighLevel, Kit."],
173
+ "structure_preference": "Preserve the same 10-section structure from the existing draft while expanding depth and word count.",
174
+ "confidence_notes": "Based on a saved draft expansion request and a successful research run."
175
+ }
176
+ ```
177
+
178
+ Search-intent listicle with examples:
102
179
 
103
- ```bash
104
- coauthor project create --title "AI search attribution" --contract '{"topic":"AI search attribution","angle":"How marketing teams should measure source visibility across AI answer engines","target_audience":"B2B marketing leaders","core_promise":"Give readers a practical measurement framework they can use this quarter.","must_include":["source provenance","measurement tradeoffs","examples of query-level visibility checks"],"must_avoid":["generic SEO advice","unsupported vendor claims"],"evidence_expectations":["Use current platform documentation or credible examples for factual claims."],"editorial_profile":{"tone":"serious","form":"guide","depth":"deep","cadence":"moderate"}}' --json
180
+ ```json
181
+ {
182
+ "topic": "A long-form SEO comparison/listicle article targeting \"mailchimp alternatives\" for ClickMinded Newsletter Generator.",
183
+ "angle": "Compare email platforms by the expected criteria, then add the insight that switching ESPs does not solve the weekly newsletter production problem.",
184
+ "target_audience": "Busy founders, creators, consultants, solo marketers, and small teams evaluating email marketing platforms.",
185
+ "core_promise": "Help readers choose the right Mailchimp alternative while showing when newsletter production is the real bottleneck.",
186
+ "format": "blog post",
187
+ "reading_commitment": { "kind": "preset", "preset_id": "balanced_post", "source": "user_explicit" },
188
+ "structure_preferences": ["Use an SEO-friendly H1 such as \"The Best Mailchimp Alternatives in 2026\".", "Include a quick comparison table before the detailed reviews."],
189
+ "must_include": ["Primary keyword: mailchimp alternatives.", "ClickMinded Newsletter Generator product page: https://www.clickminded.com/products/newsletter/"],
190
+ "must_avoid": ["Do not claim ClickMinded replaces Mailchimp for list management, deliverability, automations, forms, ecommerce, or sending.", "Do not use generic AI hype or imply a one-prompt ChatGPT-style wrapper."],
191
+ "non_negotiables": ["The article must satisfy the \"Mailchimp alternatives\" search intent first.", "The ClickMinded pitch must be honest and category-accurate."],
192
+ "citation_expectations": ["Include useful source links inline for competitor information and pricing claims.", "Use SERP references as structure/gap examples."],
193
+ "liked_examples": ["Zapier alternatives posts for skimmable structure and practical recommendations.", "MailerLite comparison page for direct competitor positioning."],
194
+ "rejected_examples": ["Thin SEO listicles that merely paraphrase feature pages without judgment.", "Vendor pages that pretend their tool is best for every use case."],
195
+ "editorial_profile": { "tone": "balanced", "form": "essay", "depth": "standard", "humor": "low", "section_length": "adaptive", "cadence": "moderate", "notes": "Satisfy search intent first, then make the production-workflow insight feel obvious." },
196
+ "style_rules": ["Use short paragraphs.", "Use clear H2s/H3s matching search intent."],
197
+ "must_not_change": ["ClickMinded is not an ESP.", "ClickMinded direct integrations: Mailchimp, GoHighLevel, Kit."],
198
+ "structure_preference": "Comparison/listicle with a strategic bridge section and a dedicated ClickMinded companion-workflow section.",
199
+ "confidence_notes": "Created from ClickMinded product context and SERP research."
200
+ }
201
+ ```
202
+
203
+ Persuasive opinion essay:
204
+
205
+ ```json
206
+ {
207
+ "topic": "Whether people are justified in pressuring or shaming wealthy individuals into spending their money differently",
208
+ "angle": "Directly address readers who complain about billionaire spending, then pivot to the deeper diagnosis: external locus of control and projected helplessness.",
209
+ "target_audience": "Politically engaged readers who follow wealth and inequality debates and know the standard talking points.",
210
+ "core_promise": "Readers get a confrontational but empowering argument: policing billionaire spending is often emotional, the exploitation narrative is weaker than it looks, and the better answer is to build agency.",
211
+ "format": "blog post",
212
+ "reading_commitment": { "kind": "preset", "preset_id": "balanced_post", "source": "user_explicit" },
213
+ "length_guidance": { "min_words": 1200, "target_words": 1500, "max_words": 1800 },
214
+ "must_include": ["Confrontational second-person opening hook about outrage at billionaire spending.", "Name external locus of control explicitly.", "Central reframe: stop outsourcing your sense of agency to what someone else does with their money."],
215
+ "must_avoid": ["Do not turn this into a money-printing, COVID-spending, or MMT thread.", "Do not use the word communism or slippery-slope-to-communism phrasing.", "Do not soften, hedge, or both-sides the core argument."],
216
+ "citation_expectations": ["Cost of a single NYC subway station.", "Annual US Medicare cost and approximate Elon Musk net worth for scale comparison.", "Rolex foundation ownership and limits on public profit claims."],
217
+ "editorial_profile": { "tone": "balanced", "form": "essay", "depth": "standard", "humor": "low", "section_length": "adaptive", "cadence": "moderate", "notes": "Reasoned and persuasive; do not make it a pure political rant or strawman the opposing view." },
218
+ "style_rules": ["Confident first-person or direct second-person OK.", "No hedge-everything academic tone.", "Use concrete scale comparisons rather than abstract moralizing."]
219
+ }
105
220
  ```
106
221
 
107
222
  ## Safety
@@ -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`.
@@ -98,10 +114,109 @@ This skill guides agent use of the CoAuthor CLI.
98
114
 
99
115
  - Use `reading_commitment.kind: "preset"` with a preset id for quick length choices; use `"custom"` with explicit `length_guidance` when the user gives a custom range.
100
116
  - Use top-level `canonical_entities`, `outline_seed`, `style_rules`, `must_not_change`, `structure_preference`, and `confidence_notes`. A legacy nested `handoff` object may be normalized, but top-level fields are clearer for agents.
101
- - Example:
117
+ - Field guidance:
118
+ - `topic`: The concrete subject or assignment. Include the search keyword, product, debate, or source brief if that is the true starting point.
119
+ - `angle`: The editorial thesis or framing. Use this to explain what makes this piece different from a generic article on the same topic.
120
+ - `target_audience`: Who the piece is for, including their sophistication, context, objections, and buying or reading intent.
121
+ - `core_promise`: The reader outcome. Phrase it as what the reader will understand, decide, or be able to do after reading.
122
+ - `format`: Human-readable format label, such as `blog post`, `guide`, `listicle`, `case study`, or `long-form SEO comparison guide`.
123
+ - `reading_commitment`: Use a preset when the user picked or implied a length tier. Use `custom` plus `length_guidance` when the user gave a specific range.
124
+ - `length_guidance`: Word-count bounds. Use positive integers or `null`; keep `min_words <= target_words <= max_words` when known.
125
+ - `audience_knowledge_assumptions`: What the reader already knows, so the draft does not over-explain or under-explain.
126
+ - `desired_reader_experience`: How the finished piece should feel to read, such as fast and scannable, authoritative and comprehensive, funny but informative, or practical and no-fluff.
127
+ - `structure_preferences`: List of preferred sections, ordering, comparison/table requirements, intro/conclusion instructions, or other structural choices.
128
+ - `must_include`: Specific points, keywords, URLs, products, claims, examples, or sections that must appear.
129
+ - `must_avoid`: Things to leave out, weak arguments, banned phrasings, unsupported claims, or misleading positioning.
130
+ - `non_negotiables`: Hard constraints that would make the draft wrong if violated. Use this for stricter requirements than ordinary `must_avoid` guidance.
131
+ - `evidence_expectations`: What kind of support the argument needs, such as official docs, pricing pages, public data, examples, or completed research.
132
+ - `citation_expectations`: Which claims need links or citations, preferred source types, and any source URLs that should be used.
133
+ - `liked_examples`: URLs, titles, patterns, or descriptions of examples to emulate.
134
+ - `rejected_examples`: URLs, titles, patterns, or descriptions of examples to avoid.
135
+ - `additional_editorial_guidance`: Any important prose brief that does not fit another field, including voice, pacing, product positioning, or inherited brief details.
136
+ - `editorial_profile`: Structured style controls. Use `notes` for nuance that enum values cannot capture.
137
+ - `canonical_entities`: Stable names for products, people, companies, characters, or concepts that must be referred to consistently. `actor_key` is the stable snake-case id used by `outline_seed.required_actor_keys`.
138
+ - `outline_seed`: Suggested section plan. Use `required_actor_keys` to tie sections to entries in `canonical_entities`.
139
+ - `style_rules`: Reusable sentence-level or formatting rules, such as short paragraphs, markdown tables, direct second person, or no academic hedging.
140
+ - `must_not_change`: Facts, names, positioning statements, URLs, or product limitations that must survive editing unchanged.
141
+ - `structure_preference`: A one-string summary of the overall structure. Use `structure_preferences` for the detailed list.
142
+ - `confidence_notes`: Explain what the contract was based on and where uncertainty remains.
143
+ - Real saved contract examples from the database, compacted for agent reuse:
144
+
145
+ Deep SEO comparison guide:
146
+
147
+ ```json
148
+ {
149
+ "topic": "Write a comprehensive long-form SEO comparison guide targeting the keyword \"mailchimp alternatives\" for ClickMinded Newsletter Generator.",
150
+ "angle": "Satisfy standard Mailchimp alternatives search intent, then show the category-aware distinction between email sending platforms and newsletter production workflows.",
151
+ "target_audience": "Busy founders, creators, consultants, solo marketers, agency owners, and small marketing teams evaluating Mailchimp competitors.",
152
+ "core_promise": "Help readers choose the right Mailchimp alternative by use case while making clear that ClickMinded may be the better fix when the real bottleneck is newsletter production.",
153
+ "format": "long-form SEO comparison guide",
154
+ "reading_commitment": { "kind": "custom", "preset_id": null, "source": "user_explicit" },
155
+ "length_guidance": { "min_words": 3200, "target_words": 3700, "max_words": 4200 },
156
+ "desired_reader_experience": "Comprehensive, practical, fair, and category-aware.",
157
+ "structure_preferences": ["Preserve the existing article structure and heading flow.", "Expand comparison depth for every platform."],
158
+ "must_include": ["Primary keyword \"mailchimp alternatives\" in the H1, intro, one H2 or H3, and conclusion naturally.", "Cover MailerLite, Brevo, Kit, ActiveCampaign, beehiiv, Substack, Klaviyo, Omnisend, Constant Contact, Drip, and Campaign Monitor."],
159
+ "must_avoid": ["Do not make ClickMinded sound like an ESP or Mailchimp replacement.", "Do not imply ClickMinded handles list management, deliverability, automations, forms, ecommerce, analytics, compliance management, or sending."],
160
+ "non_negotiables": ["The article must satisfy search intent for \"mailchimp alternatives\" before pitching ClickMinded.", "The ClickMinded positioning must be category-accurate and honest."],
161
+ "evidence_expectations": ["Use completed research and official pricing/features sources.", "Qualify pricing as current at time of writing."],
162
+ "citation_expectations": ["Use current source links for pricing/features, especially official sources.", "Include the ClickMinded product page and CTA URLs exactly as required."],
163
+ "editorial_profile": { "tone": "balanced", "form": "guide", "depth": "deep", "humor": "none", "section_length": "adaptive", "cadence": "moderate", "notes": "Long-form SEO comparison guide; practical, fair, and category-aware." },
164
+ "canonical_entities": [
165
+ { "actor_key": "clickminded_newsletter_generator", "character_name": "ClickMinded Newsletter Generator", "role_title": "AI newsletter generator and production workflow", "description": "A newsletter production layer. It is not an ESP.", "aliases": ["ClickMinded Newsletter Generator", "ClickMinded"], "must_preserve": true },
166
+ { "actor_key": "mailchimp", "character_name": "Mailchimp", "role_title": "Email marketing platform / ESP", "description": "Email marketing software for list management, sending, automations, forms, templates, analytics, and related ESP functions.", "aliases": ["Mailchimp"], "must_preserve": true }
167
+ ],
168
+ "outline_seed": [
169
+ { "id": "intro_quick_comparison", "heading": "The Best Mailchimp Alternatives in 2026", "intent": "Satisfy core search intent quickly and clarify replacement versus production workflow.", "must_include_points": ["Primary keyword in H1 and intro", "Clarify that some tools replace Mailchimp and ClickMinded complements it by solving production"], "required_actor_keys": ["mailchimp", "clickminded_newsletter_generator"], "notes": "" }
170
+ ],
171
+ "style_rules": ["Use Markdown headings and tables where helpful.", "Keep ClickMinded category-accurate and honest."],
172
+ "must_not_change": ["ClickMinded is not an ESP.", "ClickMinded direct integrations: Mailchimp, GoHighLevel, Kit."],
173
+ "structure_preference": "Preserve the same 10-section structure from the existing draft while expanding depth and word count.",
174
+ "confidence_notes": "Based on a saved draft expansion request and a successful research run."
175
+ }
176
+ ```
177
+
178
+ Search-intent listicle with examples:
102
179
 
103
- ```bash
104
- coauthor project create --title "AI search attribution" --contract '{"topic":"AI search attribution","angle":"How marketing teams should measure source visibility across AI answer engines","target_audience":"B2B marketing leaders","core_promise":"Give readers a practical measurement framework they can use this quarter.","must_include":["source provenance","measurement tradeoffs","examples of query-level visibility checks"],"must_avoid":["generic SEO advice","unsupported vendor claims"],"evidence_expectations":["Use current platform documentation or credible examples for factual claims."],"editorial_profile":{"tone":"serious","form":"guide","depth":"deep","cadence":"moderate"}}' --json
180
+ ```json
181
+ {
182
+ "topic": "A long-form SEO comparison/listicle article targeting \"mailchimp alternatives\" for ClickMinded Newsletter Generator.",
183
+ "angle": "Compare email platforms by the expected criteria, then add the insight that switching ESPs does not solve the weekly newsletter production problem.",
184
+ "target_audience": "Busy founders, creators, consultants, solo marketers, and small teams evaluating email marketing platforms.",
185
+ "core_promise": "Help readers choose the right Mailchimp alternative while showing when newsletter production is the real bottleneck.",
186
+ "format": "blog post",
187
+ "reading_commitment": { "kind": "preset", "preset_id": "balanced_post", "source": "user_explicit" },
188
+ "structure_preferences": ["Use an SEO-friendly H1 such as \"The Best Mailchimp Alternatives in 2026\".", "Include a quick comparison table before the detailed reviews."],
189
+ "must_include": ["Primary keyword: mailchimp alternatives.", "ClickMinded Newsletter Generator product page: https://www.clickminded.com/products/newsletter/"],
190
+ "must_avoid": ["Do not claim ClickMinded replaces Mailchimp for list management, deliverability, automations, forms, ecommerce, or sending.", "Do not use generic AI hype or imply a one-prompt ChatGPT-style wrapper."],
191
+ "non_negotiables": ["The article must satisfy the \"Mailchimp alternatives\" search intent first.", "The ClickMinded pitch must be honest and category-accurate."],
192
+ "citation_expectations": ["Include useful source links inline for competitor information and pricing claims.", "Use SERP references as structure/gap examples."],
193
+ "liked_examples": ["Zapier alternatives posts for skimmable structure and practical recommendations.", "MailerLite comparison page for direct competitor positioning."],
194
+ "rejected_examples": ["Thin SEO listicles that merely paraphrase feature pages without judgment.", "Vendor pages that pretend their tool is best for every use case."],
195
+ "editorial_profile": { "tone": "balanced", "form": "essay", "depth": "standard", "humor": "low", "section_length": "adaptive", "cadence": "moderate", "notes": "Satisfy search intent first, then make the production-workflow insight feel obvious." },
196
+ "style_rules": ["Use short paragraphs.", "Use clear H2s/H3s matching search intent."],
197
+ "must_not_change": ["ClickMinded is not an ESP.", "ClickMinded direct integrations: Mailchimp, GoHighLevel, Kit."],
198
+ "structure_preference": "Comparison/listicle with a strategic bridge section and a dedicated ClickMinded companion-workflow section.",
199
+ "confidence_notes": "Created from ClickMinded product context and SERP research."
200
+ }
201
+ ```
202
+
203
+ Persuasive opinion essay:
204
+
205
+ ```json
206
+ {
207
+ "topic": "Whether people are justified in pressuring or shaming wealthy individuals into spending their money differently",
208
+ "angle": "Directly address readers who complain about billionaire spending, then pivot to the deeper diagnosis: external locus of control and projected helplessness.",
209
+ "target_audience": "Politically engaged readers who follow wealth and inequality debates and know the standard talking points.",
210
+ "core_promise": "Readers get a confrontational but empowering argument: policing billionaire spending is often emotional, the exploitation narrative is weaker than it looks, and the better answer is to build agency.",
211
+ "format": "blog post",
212
+ "reading_commitment": { "kind": "preset", "preset_id": "balanced_post", "source": "user_explicit" },
213
+ "length_guidance": { "min_words": 1200, "target_words": 1500, "max_words": 1800 },
214
+ "must_include": ["Confrontational second-person opening hook about outrage at billionaire spending.", "Name external locus of control explicitly.", "Central reframe: stop outsourcing your sense of agency to what someone else does with their money."],
215
+ "must_avoid": ["Do not turn this into a money-printing, COVID-spending, or MMT thread.", "Do not use the word communism or slippery-slope-to-communism phrasing.", "Do not soften, hedge, or both-sides the core argument."],
216
+ "citation_expectations": ["Cost of a single NYC subway station.", "Annual US Medicare cost and approximate Elon Musk net worth for scale comparison.", "Rolex foundation ownership and limits on public profit claims."],
217
+ "editorial_profile": { "tone": "balanced", "form": "essay", "depth": "standard", "humor": "low", "section_length": "adaptive", "cadence": "moderate", "notes": "Reasoned and persuasive; do not make it a pure political rant or strawman the opposing view." },
218
+ "style_rules": ["Confident first-person or direct second-person OK.", "No hedge-everything academic tone.", "Use concrete scale comparisons rather than abstract moralizing."]
219
+ }
105
220
  ```
106
221
 
107
222
  ## Safety
@@ -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`.
@@ -98,10 +114,109 @@ This skill guides agent use of the CoAuthor CLI.
98
114
 
99
115
  - Use `reading_commitment.kind: "preset"` with a preset id for quick length choices; use `"custom"` with explicit `length_guidance` when the user gives a custom range.
100
116
  - Use top-level `canonical_entities`, `outline_seed`, `style_rules`, `must_not_change`, `structure_preference`, and `confidence_notes`. A legacy nested `handoff` object may be normalized, but top-level fields are clearer for agents.
101
- - Example:
117
+ - Field guidance:
118
+ - `topic`: The concrete subject or assignment. Include the search keyword, product, debate, or source brief if that is the true starting point.
119
+ - `angle`: The editorial thesis or framing. Use this to explain what makes this piece different from a generic article on the same topic.
120
+ - `target_audience`: Who the piece is for, including their sophistication, context, objections, and buying or reading intent.
121
+ - `core_promise`: The reader outcome. Phrase it as what the reader will understand, decide, or be able to do after reading.
122
+ - `format`: Human-readable format label, such as `blog post`, `guide`, `listicle`, `case study`, or `long-form SEO comparison guide`.
123
+ - `reading_commitment`: Use a preset when the user picked or implied a length tier. Use `custom` plus `length_guidance` when the user gave a specific range.
124
+ - `length_guidance`: Word-count bounds. Use positive integers or `null`; keep `min_words <= target_words <= max_words` when known.
125
+ - `audience_knowledge_assumptions`: What the reader already knows, so the draft does not over-explain or under-explain.
126
+ - `desired_reader_experience`: How the finished piece should feel to read, such as fast and scannable, authoritative and comprehensive, funny but informative, or practical and no-fluff.
127
+ - `structure_preferences`: List of preferred sections, ordering, comparison/table requirements, intro/conclusion instructions, or other structural choices.
128
+ - `must_include`: Specific points, keywords, URLs, products, claims, examples, or sections that must appear.
129
+ - `must_avoid`: Things to leave out, weak arguments, banned phrasings, unsupported claims, or misleading positioning.
130
+ - `non_negotiables`: Hard constraints that would make the draft wrong if violated. Use this for stricter requirements than ordinary `must_avoid` guidance.
131
+ - `evidence_expectations`: What kind of support the argument needs, such as official docs, pricing pages, public data, examples, or completed research.
132
+ - `citation_expectations`: Which claims need links or citations, preferred source types, and any source URLs that should be used.
133
+ - `liked_examples`: URLs, titles, patterns, or descriptions of examples to emulate.
134
+ - `rejected_examples`: URLs, titles, patterns, or descriptions of examples to avoid.
135
+ - `additional_editorial_guidance`: Any important prose brief that does not fit another field, including voice, pacing, product positioning, or inherited brief details.
136
+ - `editorial_profile`: Structured style controls. Use `notes` for nuance that enum values cannot capture.
137
+ - `canonical_entities`: Stable names for products, people, companies, characters, or concepts that must be referred to consistently. `actor_key` is the stable snake-case id used by `outline_seed.required_actor_keys`.
138
+ - `outline_seed`: Suggested section plan. Use `required_actor_keys` to tie sections to entries in `canonical_entities`.
139
+ - `style_rules`: Reusable sentence-level or formatting rules, such as short paragraphs, markdown tables, direct second person, or no academic hedging.
140
+ - `must_not_change`: Facts, names, positioning statements, URLs, or product limitations that must survive editing unchanged.
141
+ - `structure_preference`: A one-string summary of the overall structure. Use `structure_preferences` for the detailed list.
142
+ - `confidence_notes`: Explain what the contract was based on and where uncertainty remains.
143
+ - Real saved contract examples from the database, compacted for agent reuse:
144
+
145
+ Deep SEO comparison guide:
146
+
147
+ ```json
148
+ {
149
+ "topic": "Write a comprehensive long-form SEO comparison guide targeting the keyword \"mailchimp alternatives\" for ClickMinded Newsletter Generator.",
150
+ "angle": "Satisfy standard Mailchimp alternatives search intent, then show the category-aware distinction between email sending platforms and newsletter production workflows.",
151
+ "target_audience": "Busy founders, creators, consultants, solo marketers, agency owners, and small marketing teams evaluating Mailchimp competitors.",
152
+ "core_promise": "Help readers choose the right Mailchimp alternative by use case while making clear that ClickMinded may be the better fix when the real bottleneck is newsletter production.",
153
+ "format": "long-form SEO comparison guide",
154
+ "reading_commitment": { "kind": "custom", "preset_id": null, "source": "user_explicit" },
155
+ "length_guidance": { "min_words": 3200, "target_words": 3700, "max_words": 4200 },
156
+ "desired_reader_experience": "Comprehensive, practical, fair, and category-aware.",
157
+ "structure_preferences": ["Preserve the existing article structure and heading flow.", "Expand comparison depth for every platform."],
158
+ "must_include": ["Primary keyword \"mailchimp alternatives\" in the H1, intro, one H2 or H3, and conclusion naturally.", "Cover MailerLite, Brevo, Kit, ActiveCampaign, beehiiv, Substack, Klaviyo, Omnisend, Constant Contact, Drip, and Campaign Monitor."],
159
+ "must_avoid": ["Do not make ClickMinded sound like an ESP or Mailchimp replacement.", "Do not imply ClickMinded handles list management, deliverability, automations, forms, ecommerce, analytics, compliance management, or sending."],
160
+ "non_negotiables": ["The article must satisfy search intent for \"mailchimp alternatives\" before pitching ClickMinded.", "The ClickMinded positioning must be category-accurate and honest."],
161
+ "evidence_expectations": ["Use completed research and official pricing/features sources.", "Qualify pricing as current at time of writing."],
162
+ "citation_expectations": ["Use current source links for pricing/features, especially official sources.", "Include the ClickMinded product page and CTA URLs exactly as required."],
163
+ "editorial_profile": { "tone": "balanced", "form": "guide", "depth": "deep", "humor": "none", "section_length": "adaptive", "cadence": "moderate", "notes": "Long-form SEO comparison guide; practical, fair, and category-aware." },
164
+ "canonical_entities": [
165
+ { "actor_key": "clickminded_newsletter_generator", "character_name": "ClickMinded Newsletter Generator", "role_title": "AI newsletter generator and production workflow", "description": "A newsletter production layer. It is not an ESP.", "aliases": ["ClickMinded Newsletter Generator", "ClickMinded"], "must_preserve": true },
166
+ { "actor_key": "mailchimp", "character_name": "Mailchimp", "role_title": "Email marketing platform / ESP", "description": "Email marketing software for list management, sending, automations, forms, templates, analytics, and related ESP functions.", "aliases": ["Mailchimp"], "must_preserve": true }
167
+ ],
168
+ "outline_seed": [
169
+ { "id": "intro_quick_comparison", "heading": "The Best Mailchimp Alternatives in 2026", "intent": "Satisfy core search intent quickly and clarify replacement versus production workflow.", "must_include_points": ["Primary keyword in H1 and intro", "Clarify that some tools replace Mailchimp and ClickMinded complements it by solving production"], "required_actor_keys": ["mailchimp", "clickminded_newsletter_generator"], "notes": "" }
170
+ ],
171
+ "style_rules": ["Use Markdown headings and tables where helpful.", "Keep ClickMinded category-accurate and honest."],
172
+ "must_not_change": ["ClickMinded is not an ESP.", "ClickMinded direct integrations: Mailchimp, GoHighLevel, Kit."],
173
+ "structure_preference": "Preserve the same 10-section structure from the existing draft while expanding depth and word count.",
174
+ "confidence_notes": "Based on a saved draft expansion request and a successful research run."
175
+ }
176
+ ```
177
+
178
+ Search-intent listicle with examples:
102
179
 
103
- ```bash
104
- coauthor project create --title "AI search attribution" --contract '{"topic":"AI search attribution","angle":"How marketing teams should measure source visibility across AI answer engines","target_audience":"B2B marketing leaders","core_promise":"Give readers a practical measurement framework they can use this quarter.","must_include":["source provenance","measurement tradeoffs","examples of query-level visibility checks"],"must_avoid":["generic SEO advice","unsupported vendor claims"],"evidence_expectations":["Use current platform documentation or credible examples for factual claims."],"editorial_profile":{"tone":"serious","form":"guide","depth":"deep","cadence":"moderate"}}' --json
180
+ ```json
181
+ {
182
+ "topic": "A long-form SEO comparison/listicle article targeting \"mailchimp alternatives\" for ClickMinded Newsletter Generator.",
183
+ "angle": "Compare email platforms by the expected criteria, then add the insight that switching ESPs does not solve the weekly newsletter production problem.",
184
+ "target_audience": "Busy founders, creators, consultants, solo marketers, and small teams evaluating email marketing platforms.",
185
+ "core_promise": "Help readers choose the right Mailchimp alternative while showing when newsletter production is the real bottleneck.",
186
+ "format": "blog post",
187
+ "reading_commitment": { "kind": "preset", "preset_id": "balanced_post", "source": "user_explicit" },
188
+ "structure_preferences": ["Use an SEO-friendly H1 such as \"The Best Mailchimp Alternatives in 2026\".", "Include a quick comparison table before the detailed reviews."],
189
+ "must_include": ["Primary keyword: mailchimp alternatives.", "ClickMinded Newsletter Generator product page: https://www.clickminded.com/products/newsletter/"],
190
+ "must_avoid": ["Do not claim ClickMinded replaces Mailchimp for list management, deliverability, automations, forms, ecommerce, or sending.", "Do not use generic AI hype or imply a one-prompt ChatGPT-style wrapper."],
191
+ "non_negotiables": ["The article must satisfy the \"Mailchimp alternatives\" search intent first.", "The ClickMinded pitch must be honest and category-accurate."],
192
+ "citation_expectations": ["Include useful source links inline for competitor information and pricing claims.", "Use SERP references as structure/gap examples."],
193
+ "liked_examples": ["Zapier alternatives posts for skimmable structure and practical recommendations.", "MailerLite comparison page for direct competitor positioning."],
194
+ "rejected_examples": ["Thin SEO listicles that merely paraphrase feature pages without judgment.", "Vendor pages that pretend their tool is best for every use case."],
195
+ "editorial_profile": { "tone": "balanced", "form": "essay", "depth": "standard", "humor": "low", "section_length": "adaptive", "cadence": "moderate", "notes": "Satisfy search intent first, then make the production-workflow insight feel obvious." },
196
+ "style_rules": ["Use short paragraphs.", "Use clear H2s/H3s matching search intent."],
197
+ "must_not_change": ["ClickMinded is not an ESP.", "ClickMinded direct integrations: Mailchimp, GoHighLevel, Kit."],
198
+ "structure_preference": "Comparison/listicle with a strategic bridge section and a dedicated ClickMinded companion-workflow section.",
199
+ "confidence_notes": "Created from ClickMinded product context and SERP research."
200
+ }
201
+ ```
202
+
203
+ Persuasive opinion essay:
204
+
205
+ ```json
206
+ {
207
+ "topic": "Whether people are justified in pressuring or shaming wealthy individuals into spending their money differently",
208
+ "angle": "Directly address readers who complain about billionaire spending, then pivot to the deeper diagnosis: external locus of control and projected helplessness.",
209
+ "target_audience": "Politically engaged readers who follow wealth and inequality debates and know the standard talking points.",
210
+ "core_promise": "Readers get a confrontational but empowering argument: policing billionaire spending is often emotional, the exploitation narrative is weaker than it looks, and the better answer is to build agency.",
211
+ "format": "blog post",
212
+ "reading_commitment": { "kind": "preset", "preset_id": "balanced_post", "source": "user_explicit" },
213
+ "length_guidance": { "min_words": 1200, "target_words": 1500, "max_words": 1800 },
214
+ "must_include": ["Confrontational second-person opening hook about outrage at billionaire spending.", "Name external locus of control explicitly.", "Central reframe: stop outsourcing your sense of agency to what someone else does with their money."],
215
+ "must_avoid": ["Do not turn this into a money-printing, COVID-spending, or MMT thread.", "Do not use the word communism or slippery-slope-to-communism phrasing.", "Do not soften, hedge, or both-sides the core argument."],
216
+ "citation_expectations": ["Cost of a single NYC subway station.", "Annual US Medicare cost and approximate Elon Musk net worth for scale comparison.", "Rolex foundation ownership and limits on public profit claims."],
217
+ "editorial_profile": { "tone": "balanced", "form": "essay", "depth": "standard", "humor": "low", "section_length": "adaptive", "cadence": "moderate", "notes": "Reasoned and persuasive; do not make it a pure political rant or strawman the opposing view." },
218
+ "style_rules": ["Confident first-person or direct second-person OK.", "No hedge-everything academic tone.", "Use concrete scale comparisons rather than abstract moralizing."]
219
+ }
105
220
  ```
106
221
 
107
222
  ## Safety
@@ -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`.
@@ -93,6 +104,113 @@ alwaysApply: true
93
104
 
94
105
  - Use `reading_commitment.kind: "preset"` with a preset id for quick length choices; use `"custom"` with explicit `length_guidance` when the user gives a custom range.
95
106
  - Use top-level `canonical_entities`, `outline_seed`, `style_rules`, `must_not_change`, `structure_preference`, and `confidence_notes`. A legacy nested `handoff` object may be normalized, but top-level fields are clearer for agents.
107
+
108
+ ## Editorial Contract Field Guidance
109
+
110
+ - `topic`: The concrete subject or assignment. Include the search keyword, product, debate, or source brief if that is the true starting point.
111
+ - `angle`: The editorial thesis or framing. Use this to explain what makes this piece different from a generic article on the same topic.
112
+ - `target_audience`: Who the piece is for, including their sophistication, context, objections, and buying or reading intent.
113
+ - `core_promise`: The reader outcome. Phrase it as what the reader will understand, decide, or be able to do after reading.
114
+ - `format`: Human-readable format label, such as `blog post`, `guide`, `listicle`, `case study`, or `long-form SEO comparison guide`.
115
+ - `reading_commitment`: Use a preset when the user picked or implied a length tier. Use `custom` plus `length_guidance` when the user gave a specific range.
116
+ - `length_guidance`: Word-count bounds. Use positive integers or `null`; keep `min_words <= target_words <= max_words` when known.
117
+ - `audience_knowledge_assumptions`: What the reader already knows, so the draft does not over-explain or under-explain.
118
+ - `desired_reader_experience`: How the finished piece should feel to read, such as fast and scannable, authoritative and comprehensive, funny but informative, or practical and no-fluff.
119
+ - `structure_preferences`: List of preferred sections, ordering, comparison/table requirements, intro/conclusion instructions, or other structural choices.
120
+ - `must_include`: Specific points, keywords, URLs, products, claims, examples, or sections that must appear.
121
+ - `must_avoid`: Things to leave out, weak arguments, banned phrasings, unsupported claims, or misleading positioning.
122
+ - `non_negotiables`: Hard constraints that would make the draft wrong if violated. Use this for stricter requirements than ordinary `must_avoid` guidance.
123
+ - `evidence_expectations`: What kind of support the argument needs, such as official docs, pricing pages, public data, examples, or completed research.
124
+ - `citation_expectations`: Which claims need links or citations, preferred source types, and any source URLs that should be used.
125
+ - `liked_examples`: URLs, titles, patterns, or descriptions of examples to emulate.
126
+ - `rejected_examples`: URLs, titles, patterns, or descriptions of examples to avoid.
127
+ - `additional_editorial_guidance`: Any important prose brief that does not fit another field, including voice, pacing, product positioning, or inherited brief details.
128
+ - `editorial_profile`: Structured style controls. Use `notes` for nuance that enum values cannot capture.
129
+ - `canonical_entities`: Stable names for products, people, companies, characters, or concepts that must be referred to consistently. `actor_key` is the stable snake-case id used by `outline_seed.required_actor_keys`.
130
+ - `outline_seed`: Suggested section plan. Use `required_actor_keys` to tie sections to entries in `canonical_entities`.
131
+ - `style_rules`: Reusable sentence-level or formatting rules, such as short paragraphs, markdown tables, direct second person, or no academic hedging.
132
+ - `must_not_change`: Facts, names, positioning statements, URLs, or product limitations that must survive editing unchanged.
133
+ - `structure_preference`: A one-string summary of the overall structure. Use `structure_preferences` for the detailed list.
134
+ - `confidence_notes`: Explain what the contract was based on and where uncertainty remains.
135
+
136
+ ## Real Saved Contract Examples
137
+
138
+ Deep SEO comparison guide:
139
+
140
+ ```json
141
+ {
142
+ "topic": "Write a comprehensive long-form SEO comparison guide targeting the keyword \"mailchimp alternatives\" for ClickMinded Newsletter Generator.",
143
+ "angle": "Satisfy standard Mailchimp alternatives search intent, then show the category-aware distinction between email sending platforms and newsletter production workflows.",
144
+ "target_audience": "Busy founders, creators, consultants, solo marketers, agency owners, and small marketing teams evaluating Mailchimp competitors.",
145
+ "core_promise": "Help readers choose the right Mailchimp alternative by use case while making clear that ClickMinded may be the better fix when the real bottleneck is newsletter production.",
146
+ "format": "long-form SEO comparison guide",
147
+ "reading_commitment": { "kind": "custom", "preset_id": null, "source": "user_explicit" },
148
+ "length_guidance": { "min_words": 3200, "target_words": 3700, "max_words": 4200 },
149
+ "desired_reader_experience": "Comprehensive, practical, fair, and category-aware.",
150
+ "structure_preferences": ["Preserve the existing article structure and heading flow.", "Expand comparison depth for every platform."],
151
+ "must_include": ["Primary keyword \"mailchimp alternatives\" in the H1, intro, one H2 or H3, and conclusion naturally.", "Cover MailerLite, Brevo, Kit, ActiveCampaign, beehiiv, Substack, Klaviyo, Omnisend, Constant Contact, Drip, and Campaign Monitor."],
152
+ "must_avoid": ["Do not make ClickMinded sound like an ESP or Mailchimp replacement.", "Do not imply ClickMinded handles list management, deliverability, automations, forms, ecommerce, analytics, compliance management, or sending."],
153
+ "non_negotiables": ["The article must satisfy search intent for \"mailchimp alternatives\" before pitching ClickMinded.", "The ClickMinded positioning must be category-accurate and honest."],
154
+ "evidence_expectations": ["Use completed research and official pricing/features sources.", "Qualify pricing as current at time of writing."],
155
+ "citation_expectations": ["Use current source links for pricing/features, especially official sources.", "Include the ClickMinded product page and CTA URLs exactly as required."],
156
+ "editorial_profile": { "tone": "balanced", "form": "guide", "depth": "deep", "humor": "none", "section_length": "adaptive", "cadence": "moderate", "notes": "Long-form SEO comparison guide; practical, fair, and category-aware." },
157
+ "canonical_entities": [
158
+ { "actor_key": "clickminded_newsletter_generator", "character_name": "ClickMinded Newsletter Generator", "role_title": "AI newsletter generator and production workflow", "description": "A newsletter production layer. It is not an ESP.", "aliases": ["ClickMinded Newsletter Generator", "ClickMinded"], "must_preserve": true },
159
+ { "actor_key": "mailchimp", "character_name": "Mailchimp", "role_title": "Email marketing platform / ESP", "description": "Email marketing software for list management, sending, automations, forms, templates, analytics, and related ESP functions.", "aliases": ["Mailchimp"], "must_preserve": true }
160
+ ],
161
+ "outline_seed": [
162
+ { "id": "intro_quick_comparison", "heading": "The Best Mailchimp Alternatives in 2026", "intent": "Satisfy core search intent quickly and clarify replacement versus production workflow.", "must_include_points": ["Primary keyword in H1 and intro", "Clarify that some tools replace Mailchimp and ClickMinded complements it by solving production"], "required_actor_keys": ["mailchimp", "clickminded_newsletter_generator"], "notes": "" }
163
+ ],
164
+ "style_rules": ["Use Markdown headings and tables where helpful.", "Keep ClickMinded category-accurate and honest."],
165
+ "must_not_change": ["ClickMinded is not an ESP.", "ClickMinded direct integrations: Mailchimp, GoHighLevel, Kit."],
166
+ "structure_preference": "Preserve the same 10-section structure from the existing draft while expanding depth and word count.",
167
+ "confidence_notes": "Based on a saved draft expansion request and a successful research run."
168
+ }
169
+ ```
170
+
171
+ Search-intent listicle with examples:
172
+
173
+ ```json
174
+ {
175
+ "topic": "A long-form SEO comparison/listicle article targeting \"mailchimp alternatives\" for ClickMinded Newsletter Generator.",
176
+ "angle": "Compare email platforms by the expected criteria, then add the insight that switching ESPs does not solve the weekly newsletter production problem.",
177
+ "target_audience": "Busy founders, creators, consultants, solo marketers, and small teams evaluating email marketing platforms.",
178
+ "core_promise": "Help readers choose the right Mailchimp alternative while showing when newsletter production is the real bottleneck.",
179
+ "format": "blog post",
180
+ "reading_commitment": { "kind": "preset", "preset_id": "balanced_post", "source": "user_explicit" },
181
+ "structure_preferences": ["Use an SEO-friendly H1 such as \"The Best Mailchimp Alternatives in 2026\".", "Include a quick comparison table before the detailed reviews."],
182
+ "must_include": ["Primary keyword: mailchimp alternatives.", "ClickMinded Newsletter Generator product page: https://www.clickminded.com/products/newsletter/"],
183
+ "must_avoid": ["Do not claim ClickMinded replaces Mailchimp for list management, deliverability, automations, forms, ecommerce, or sending.", "Do not use generic AI hype or imply a one-prompt ChatGPT-style wrapper."],
184
+ "non_negotiables": ["The article must satisfy the \"Mailchimp alternatives\" search intent first.", "The ClickMinded pitch must be honest and category-accurate."],
185
+ "citation_expectations": ["Include useful source links inline for competitor information and pricing claims.", "Use SERP references as structure/gap examples."],
186
+ "liked_examples": ["Zapier alternatives posts for skimmable structure and practical recommendations.", "MailerLite comparison page for direct competitor positioning."],
187
+ "rejected_examples": ["Thin SEO listicles that merely paraphrase feature pages without judgment.", "Vendor pages that pretend their tool is best for every use case."],
188
+ "editorial_profile": { "tone": "balanced", "form": "essay", "depth": "standard", "humor": "low", "section_length": "adaptive", "cadence": "moderate", "notes": "Satisfy search intent first, then make the production-workflow insight feel obvious." },
189
+ "style_rules": ["Use short paragraphs.", "Use clear H2s/H3s matching search intent."],
190
+ "must_not_change": ["ClickMinded is not an ESP.", "ClickMinded direct integrations: Mailchimp, GoHighLevel, Kit."],
191
+ "structure_preference": "Comparison/listicle with a strategic bridge section and a dedicated ClickMinded companion-workflow section.",
192
+ "confidence_notes": "Created from ClickMinded product context and SERP research."
193
+ }
194
+ ```
195
+
196
+ Persuasive opinion essay:
197
+
198
+ ```json
199
+ {
200
+ "topic": "Whether people are justified in pressuring or shaming wealthy individuals into spending their money differently",
201
+ "angle": "Directly address readers who complain about billionaire spending, then pivot to the deeper diagnosis: external locus of control and projected helplessness.",
202
+ "target_audience": "Politically engaged readers who follow wealth and inequality debates and know the standard talking points.",
203
+ "core_promise": "Readers get a confrontational but empowering argument: policing billionaire spending is often emotional, the exploitation narrative is weaker than it looks, and the better answer is to build agency.",
204
+ "format": "blog post",
205
+ "reading_commitment": { "kind": "preset", "preset_id": "balanced_post", "source": "user_explicit" },
206
+ "length_guidance": { "min_words": 1200, "target_words": 1500, "max_words": 1800 },
207
+ "must_include": ["Confrontational second-person opening hook about outrage at billionaire spending.", "Name external locus of control explicitly.", "Central reframe: stop outsourcing your sense of agency to what someone else does with their money."],
208
+ "must_avoid": ["Do not turn this into a money-printing, COVID-spending, or MMT thread.", "Do not use the word communism or slippery-slope-to-communism phrasing.", "Do not soften, hedge, or both-sides the core argument."],
209
+ "citation_expectations": ["Cost of a single NYC subway station.", "Annual US Medicare cost and approximate Elon Musk net worth for scale comparison.", "Rolex foundation ownership and limits on public profit claims."],
210
+ "editorial_profile": { "tone": "balanced", "form": "essay", "depth": "standard", "humor": "low", "section_length": "adaptive", "cadence": "moderate", "notes": "Reasoned and persuasive; do not make it a pure political rant or strawman the opposing view." },
211
+ "style_rules": ["Confident first-person or direct second-person OK.", "No hedge-everything academic tone.", "Use concrete scale comparisons rather than abstract moralizing."]
212
+ }
213
+ ```
96
214
  - Never print tokens, service-role keys, cookies, or authorization headers.
97
215
  - Never ask the user to paste Anthropic, OpenAI, or Gemini provider API keys into chat or the terminal; key entry belongs in CoAuthor AI settings.
98
216
  - Pass tokens through environment variables or secret-backed CLI options only.