@clickminded/coauthor-cli 0.0.71 → 0.0.73

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
@@ -84,7 +84,7 @@ coauthor post-details set <id> --live-url https://example.com/post/ # where th
84
84
  coauthor draft get <id> --format markdown --frontmatter --json # markdown with YAML frontmatter
85
85
  coauthor draft get <id> --format markdown --widgets embed --json # interactives as live iframes, for a site you control
86
86
  coauthor export wordpress <id> --yes --json # creates a WordPress draft post (--slug to override)
87
- coauthor credits <id> --json
87
+ coauthor credits --json # account plan, credits left and reset date (no project needed)
88
88
  coauthor integrations list --json # WordPress sites and X accounts
89
89
  coauthor seo markets --country Mexico --language Spanish --json # Google search data coverage for a market
90
90
  coauthor search-brief show <id> --json # SEO mode: target keyword and what ranks
@@ -112,7 +112,7 @@ coauthor export wordpress <id> --yes --json
112
112
 
113
113
  ## Credits
114
114
 
115
- `coauthor credits <id> --json` shows your plan, credits used, and when they reset. A typical article uses about 300 credits; images and rework rounds add the most. When included credits run out, work pauses safely and resumes with `coauthor workflow resume <id> --wait --json` (after the reset, or on Pro after adding your own provider key in CoAuthor's AI settings).
115
+ `coauthor credits --json` shows your plan, credits used, and when they reset. A typical article uses about 300 credits; images and rework rounds add the most. When included credits run out, work pauses safely and resumes with `coauthor workflow resume <id> --wait --json` (after the reset, or on Pro after adding your own provider key in CoAuthor's AI settings).
116
116
 
117
117
  ## Security
118
118
 
package/dist/commands.js CHANGED
@@ -471,9 +471,23 @@ async function runWorkflowCommand(action, input, context) {
471
471
  throw new Error('Usage: coauthor workflow <show|status|advance|run|rewind|approve|resume> <projectId>');
472
472
  }
473
473
  async function runCreditsCommand(input, client) {
474
- const projectId = requireProjectId(input);
475
- const data = await client.request({ path: `projects/${encodeURIComponent(projectId)}/credits` });
476
- return { ok: true, data };
474
+ // With no project id this is the account's balance, so an agent can check its plan and credits
475
+ // right after setup, before any project exists. The balance is per account either way.
476
+ const projectId = getString(input.values, 'project') ?? input.positionals[0];
477
+ const data = await client.request({ path: projectId ? `projects/${encodeURIComponent(projectId)}/credits` : 'credits' });
478
+ return { ok: true, message: creditsSummaryLine(data), data };
479
+ }
480
+ function creditsSummaryLine(data) {
481
+ if (getResponseValue(data, 'admin') === true || getResponseValue(data, 'unlimited') === true)
482
+ return 'Unlimited credits.';
483
+ const period = planRecord(getResponseValue(data, 'currentPeriod'));
484
+ const remaining = typeof period.remaining === 'number' ? period.remaining : null;
485
+ if (remaining === null)
486
+ return undefined;
487
+ const plan = getResponseString(data, 'plan');
488
+ const allowance = typeof period.allowance === 'number' ? ` of ${period.allowance}` : '';
489
+ const reset = typeof period.renewalDate === 'string' ? `; resets ${period.renewalDate.slice(0, 10)}` : '';
490
+ return `${plan ? `Plan: ${plan}. ` : ''}${remaining}${allowance} credits left this period${reset}.`;
477
491
  }
478
492
  async function runShareCommand(input, client) {
479
493
  const projectId = requireProjectId(input);
@@ -2271,7 +2285,7 @@ const SEO_PLAN_KIND_LABELS = {
2271
2285
  };
2272
2286
  const SEO_PLAN_USAGE = [
2273
2287
  'Usage: coauthor seo-plan show [--profile <profile-id>] [--kind post|improve|page|left_out|covered|not_checked] [--stage <stage>] [--chance <chance>] [--limit <n>] [--json]',
2274
- ' coauthor seo-plan generate [--profile <profile-id>] [--adjust "<text>"] [--wait] [--json]',
2288
+ ' coauthor seo-plan generate [--profile <profile-id>] [--adjust "<text>"] [--wait] [--idempotency-key <key>] [--json]',
2275
2289
  ' coauthor seo-plan write <item-id> [--json]',
2276
2290
  ' coauthor seo-plan dismiss <item-id> [--undo] [--json]',
2277
2291
  ' coauthor seo-plan done <item-id> [--undo] [--json]',
@@ -2295,6 +2309,10 @@ async function resolveProfileOption(input, client) {
2295
2309
  throw new Error('No writer profile found. Create one in the CoAuthor web app.');
2296
2310
  return fallback;
2297
2311
  }
2312
+ // Quotes a value for a printed shell command (POSIX single quotes) unless it is plainly safe.
2313
+ function shellQuote(value) {
2314
+ return /^[A-Za-z0-9_@%+=:,./-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
2315
+ }
2298
2316
  function httpErrorCode(error) {
2299
2317
  if (!(error instanceof AgentHttpError))
2300
2318
  return null;
@@ -2531,9 +2549,8 @@ function seoPlanQueueNote(status) {
2531
2549
  return null;
2532
2550
  return `#${position} in line, starts in about ${eta} min`;
2533
2551
  }
2534
- async function waitForSeoPlan(client, profileId, started) {
2552
+ async function waitForSeoPlan(client, profileId, started, resume) {
2535
2553
  const statusPath = `profiles/${encodeURIComponent(profileId)}/seo-plan/status`;
2536
- const resume = `coauthor seo-plan generate --profile ${profileId} --wait`;
2537
2554
  const deadline = Date.now() + waitTimeoutMs(9 * 60_000);
2538
2555
  const pollMs = Math.max(waitPollMs(), 0);
2539
2556
  let status = planRecord(await client.request({ path: statusPath }));
@@ -2548,7 +2565,9 @@ async function waitForSeoPlan(client, profileId, started) {
2548
2565
  status: 'still_running',
2549
2566
  exitCode: 2,
2550
2567
  resume_command: resume,
2551
- message: `The plan is still being made${step ? ` (${step})` : ''}. Plans take about 5 to 12 minutes. Keep waiting with: ${resume}`,
2568
+ // The resume command reuses this request's Idempotency-Key, so it replays the request instead of
2569
+ // starting (and charging for) a second plan if this one finishes before the agent re-runs it.
2570
+ message: `The plan is still being made${step ? ` (${step})` : ''}. Plans take about 5 to 12 minutes. Keep waiting with: ${resume} (it reuses this request's key, so it never starts a second plan), or check with \`coauthor seo-plan show --profile ${profileId}\`. Don't re-run generate without --idempotency-key: once this plan is ready, that makes a new one.`,
2552
2571
  data: (started ?? status),
2553
2572
  };
2554
2573
  }
@@ -2595,7 +2614,9 @@ async function runSeoPlanCommand(action, input, client) {
2595
2614
  throw new Error('--adjust can be at most 2000 characters.');
2596
2615
  const wait = getBoolean(input.values, 'wait');
2597
2616
  const profileId = await resolveProfileOption(input, client);
2617
+ const resuming = Boolean(getString(input.values, 'idempotency-key')?.trim());
2598
2618
  const idempotencyKey = getString(input.values, 'idempotency-key')?.trim() || randomUUID();
2619
+ const resume = `coauthor seo-plan generate --profile ${profileId}${adjust?.trim() ? ` --adjust ${shellQuote(adjust.trim())}` : ''} --idempotency-key ${shellQuote(idempotencyKey)} --wait`;
2599
2620
  let started;
2600
2621
  try {
2601
2622
  started = await client.request({
@@ -2607,11 +2628,13 @@ async function runSeoPlanCommand(action, input, client) {
2607
2628
  }
2608
2629
  catch (error) {
2609
2630
  // One plan runs per account at a time. When --wait finds this profile's plan already running
2610
- // (an earlier --wait timed out), join it instead of failing.
2631
+ // (an earlier --wait timed out), join it instead of failing. Resuming with the same key replays
2632
+ // that plan_running answer, so a plan that has finished since returns as ready, not as an error.
2611
2633
  if (wait && httpErrorCode(error) === 'plan_running') {
2612
2634
  const status = planRecord(await client.request({ path: `profiles/${encodeURIComponent(profileId)}/seo-plan/status` }));
2613
- if (status.done === false)
2614
- return waitForSeoPlan(client, profileId, null);
2635
+ if (status.done === false || (resuming && (status.status === 'ready' || status.status === 'failed'))) {
2636
+ return { ...await waitForSeoPlan(client, profileId, null, resume), idempotency_key: idempotencyKey };
2637
+ }
2615
2638
  }
2616
2639
  throw error;
2617
2640
  }
@@ -2627,7 +2650,7 @@ async function runSeoPlanCommand(action, input, client) {
2627
2650
  data: started,
2628
2651
  };
2629
2652
  }
2630
- const result = await waitForSeoPlan(client, profileId, started);
2653
+ const result = await waitForSeoPlan(client, profileId, started, resume);
2631
2654
  return { ...result, idempotency_key: idempotencyKey };
2632
2655
  }
2633
2656
  if (action === 'monthly-check') {
@@ -3522,7 +3545,7 @@ export function helpResult(command = []) {
3522
3545
  ' publish thread (supports --idempotency-key)',
3523
3546
  ' export list|wordpress (supports --idempotency-key)',
3524
3547
  ' operation list|show|status (publish, export and image generate/edit)',
3525
- ' credits',
3548
+ ' credits [<project-id>]',
3526
3549
  ' share <project-id>',
3527
3550
  ' models list|preferences show|preferences set',
3528
3551
  ' skills list|install',
@@ -3638,7 +3661,7 @@ function commandHelp(command) {
3638
3661
  ].join('\n'),
3639
3662
  'seo-plan': [
3640
3663
  'Usage: coauthor seo-plan show [--profile <profile-id>] [--kind post|improve|page|left_out|covered|not_checked] [--stage ready-to-buy|comparing|learning] [--chance easy|stretch|long-shot] [--limit <n>] [--json]',
3641
- ' coauthor seo-plan generate [--profile <profile-id>] [--adjust "<text>"] [--wait] [--json]',
3664
+ ' coauthor seo-plan generate [--profile <profile-id>] [--adjust "<text>"] [--wait] [--idempotency-key <key>] [--json]',
3642
3665
  ' coauthor seo-plan write <item-id> [--json]',
3643
3666
  ' coauthor seo-plan dismiss <item-id> [--undo] [--json]',
3644
3667
  ' coauthor seo-plan done <item-id> [--undo] [--json]',
@@ -3647,7 +3670,7 @@ function commandHelp(command) {
3647
3670
  '',
3648
3671
  'SEO content plan: a business-wide keyword plan for a writer profile, built from live search data and the profile\'s website. Without --profile it uses the default profile.',
3649
3672
  'show prints the strategy, the Do next moves, counts per kind, and the ideas of one kind (default post). Kinds: post (written post ideas), improve (existing pages to improve), page (page ideas, not blog posts), left_out (searches skipped, with a reason), covered, not_checked.',
3650
- 'generate makes or updates the plan (about 420 credits, most plans 300-500, charged as it runs; the account needs 500 credits remaining to start). --adjust gives a one-line steer. --wait polls for up to 9 minutes, then exits 2 with still_running; run the same command again to keep waiting.',
3673
+ 'generate makes or updates the plan (about 420 credits, most plans 300-500, charged as it runs; the account needs 500 credits remaining to start). --adjust gives a one-line steer. --wait polls for up to 9 minutes, then exits 2 with still_running and a resume_command that reuses the request\'s --idempotency-key, so it keeps waiting without starting a second plan (or check with show). Re-running generate without that key after the plan is ready makes, and charges for, a new plan.',
3651
3674
  'write <item-id> opens a project for a post idea, already set up from the plan, and prints its id and the start prompt. Continue with the normal project flow. Writing the same idea again returns the same project.',
3652
3675
  'dismiss hides an idea from the plan; --undo brings it back.',
3653
3676
  'done marks an idea as done (for example after you improved the page); --undo clears the mark. A done idea stays in the plan and stays done when the plan is updated.',
@@ -3800,9 +3823,10 @@ function commandHelp(command) {
3800
3823
  'Returns the public read-only link (data.share_url), creating it if needed. Anyone with the link can read the draft.',
3801
3824
  ].join('\n'),
3802
3825
  credits: [
3803
- 'Usage: coauthor credits <project-id> [--json]',
3826
+ 'Usage: coauthor credits [<project-id>] [--json]',
3804
3827
  '',
3805
- 'Shows the plan, credits used and remaining this period, and the reset date.',
3828
+ 'Shows the plan, credits used and remaining this period, and the reset date. Credits belong to the account, so the',
3829
+ 'project id is optional: with none (for example right after setup, before any project exists) it reads the account.',
3806
3830
  ].join('\n'),
3807
3831
  'skills install': [
3808
3832
  'Usage: coauthor skills install [claude|codex|agents|cursor|all] [--scope user|project] [--force] [--dry-run] [--json]',
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.71",
3
+ "version": "0.0.73",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: coauthor
3
- description: Research, outline, draft, illustrate, revise, and export long-form articles with CoAuthor (ClickMinded's AI writing app) through the `coauthor` CLI. Use when the user wants to write, draft, research, or edit a blog post, article, guide, or newsletter piece with CoAuthor; review a CoAuthor brief, outline, or research plan; revise or polish a CoAuthor draft; generate article images or an X thread; check CoAuthor credits; get a share link; or send a draft to WordPress. Not for git "Co-authored-by" commit trailers.
3
+ description: Research, outline, draft, illustrate, revise, and export long-form articles with CoAuthor (ClickMinded's AI writing app) through the `coauthor` CLI. Use when the user wants to write, draft, research, or edit a blog post, article, guide, or newsletter piece with CoAuthor; review a CoAuthor brief, outline, or research plan; revise or polish a CoAuthor draft; generate article images or an X thread; make an SEO content plan (which posts to write to rank on Google) and write its ideas; check CoAuthor credits; get a share link; or send a draft to WordPress. Not for git "Co-authored-by" commit trailers.
4
4
  ---
5
5
 
6
6
  # CoAuthor
@@ -12,7 +12,7 @@ You drive it with the `coauthor` CLI. CoAuthor does the writing. **You are the u
12
12
  ## Before you start
13
13
 
14
14
  1. `coauthor --version`. If the command is missing: `npm install -g @clickminded/coauthor-cli`.
15
- 2. `coauthor auth status --json`. If `data.hasToken` is false, run `coauthor auth login --no-browser` in the background, give the user the printed URL and code to approve in their browser, and wait for it to finish.
15
+ 2. `coauthor auth status --json`. If `data.hasToken` is false, run `coauthor auth login --no-browser` in the background, give the user the printed URL and code to approve in their browser, and wait for it to finish. `coauthor credits --json` confirms the account works and shows the plan, credits left and reset date; it needs no project.
16
16
  3. Never print tokens or `~/.coauthor/config.json`. Never ask the user to paste AI provider keys into chat; keys belong in CoAuthor's AI settings.
17
17
 
18
18
  ## Rules
@@ -65,7 +65,7 @@ Everything else, including auth problems: `references/troubleshooting.md`. Credi
65
65
 
66
66
  When the user wants to know what to write about for a business site, or asks for a keyword or content strategy, make a plan instead of guessing topics. A plan reads live search data and the profile's website, then lists post ideas that can win, pages to improve, and page ideas that are not blog posts.
67
67
 
68
- - `coauthor seo-plan generate --wait --json` makes it: about 420 credits (most plans 300–500) and 5–12 minutes. Tell the user the cost first. After 9 minutes it exits 2 with `still_running`; run the same command again to keep waiting.
68
+ - `coauthor seo-plan generate --wait --json` makes it: about 420 credits (most plans 300–500) and 5–12 minutes. Tell the user the cost first. After 9 minutes it exits 2 with `still_running`; to keep waiting, run the `resume_command` it prints (it reuses the request's `--idempotency-key`, so it never starts a second plan) or poll `coauthor seo-plan show --json`. Never re-run `generate` without that key to keep waiting: once the first plan is ready, that makes and charges for a new one.
69
69
  - `coauthor seo-plan show --json` reads it (strategy, Do next moves, counts, `--kind post|improve|page|left_out|covered|not_checked`).
70
70
  - `coauthor seo-plan write <item-id> --json` opens a project for a `post` idea, already set up from the plan; continue with `workflow run <project-id> --target outline` as usual. Only `post` items are writable: `improve` items are edits to a page the site already has, and `page` items are site tasks.
71
71
  - `coauthor seo-plan dismiss <item-id> [--undo] --json` hides an idea the user rules out.
@@ -2,7 +2,7 @@
2
2
 
3
3
  ## Credits
4
4
 
5
- `coauthor credits <id> --json` shows the user's plan, this period's allowance, credits used and held by running work, what remains, and when the period resets. Credits reset monthly on the subscription anniversary.
5
+ `coauthor credits --json` (or `coauthor credits <id> --json` for a project; the balance is the account's either way) shows the user's plan, this period's allowance, credits used and held by running work, what remains, and when the period resets. Credits reset monthly on the subscription anniversary.
6
6
 
7
7
  Rough costs, to set expectations before starting:
8
8
 
@@ -17,6 +17,7 @@ coauthor draft revise <id> --instruction "Cut the intro to two sentences and lea
17
17
  - One revision can be open on a draft at a time, and an open one blocks the user's saves in the browser. Always apply or discard it. `revision_pending` means one is already open. A revision you leave waiting for review is discarded automatically after 30 minutes (`expires_at` in `draft revision show`), so review it promptly; after that, start a new one.
18
18
  - If `--wait` returns `still_running`, check again with `coauthor draft revision show <id> <revision-id> --json`.
19
19
  - While a revision runs, up to 100 available credits are temporarily held for its steps. Only actual usage is charged; unused held credits are released when it finishes or stops. A hold is included in `coauthor credits <id> --json` and does not change the request's spending limit.
20
+ - A revision that ends without a result (it failed, or didn't finish within 12 minutes and was closed) has the credits it used refunded automatically. A revision you cancel is not refunded.
20
21
  - `revise_unavailable` means this account cannot revise by instruction yet; use a direct edit.
21
22
 
22
23
  ## 2. Direct edit (exact text you already have)
@@ -32,7 +32,7 @@ coauthor seo-plan results [--profile <id>] --json
32
32
  ```
33
33
 
34
34
  - Without `--profile` the default profile is used. Run `coauthor profile list --json` first when the user has several profiles and the request names a site or brand.
35
- - `generate` returns at once with `data.plan_id`, `data.free` and `data.estimate_credits`. With `--wait` it polls until the plan is ready. After 9 minutes it exits with code 2 and `still_running`; run the same `generate ... --wait` command again to keep waiting (it joins the running plan; it does not start a second one).
35
+ - `generate` returns at once with `data.plan_id`, `data.free` and `data.estimate_credits`. With `--wait` it polls until the plan is ready. After 9 minutes it exits with code 2 and `still_running` and prints a `resume_command`. Run that to keep waiting: it reuses the request's `--idempotency-key`, so it replays the first request instead of starting a second plan, and returns the plan if it finished in the meantime. You can also poll `coauthor seo-plan show --json` until `plan.status` is `ready`. Don't re-run plain `generate ... --wait` to keep waiting: while the plan runs it joins it, but once the plan is ready it makes (and charges for) a new one.
36
36
  - Many plans can be made at once, so a new plan may wait its turn. While `status` is `queued`, the status data carries `queue_position` (1 = next), `queue_eta_minutes` (a rough estimate) and `queue_paused`; the position and estimate are `null` once the plan is running or before the position is known. When `queue_paused` is `true` the plan is waiting for free plans to resume and has no estimate. Tell the user their place in line and keep waiting; the plan starts by itself.
37
37
  - A plan can still be the free **preview** a person got from the website (`data.plan.is_preview` is `true`): it holds only the first 10 posts and a few pages to improve, with no monthly check. Running `generate` finishes it into the full plan, which counts as the user's free first plan (`first_plan_free` ignores previews). Say so when the user asks why a plan is short.
38
38
  - `--adjust` is a short steer for this run, for example `--adjust "focus on B2B buyers, skip anything about hiring"`. Use it when the user wants a different emphasis. Competitors are found automatically; the user corrects them in the web app.
@@ -1,5 +1,5 @@
1
1
  ---
2
- description: Research, outline, draft, illustrate, revise, and export long-form articles with CoAuthor (ClickMinded's AI writing app) through the `coauthor` CLI. Use when the user wants to write, draft, research, or edit a blog post, article, guide, or newsletter piece with CoAuthor; review a CoAuthor brief, outline, or research plan; revise or polish a CoAuthor draft; generate article images or an X thread; check CoAuthor credits; get a share link; or send a draft to WordPress. Not for git "Co-authored-by" commit trailers.
2
+ description: Research, outline, draft, illustrate, revise, and export long-form articles with CoAuthor (ClickMinded's AI writing app) through the `coauthor` CLI. Use when the user wants to write, draft, research, or edit a blog post, article, guide, or newsletter piece with CoAuthor; review a CoAuthor brief, outline, or research plan; revise or polish a CoAuthor draft; generate article images or an X thread; make an SEO content plan (which posts to write to rank on Google) and write its ideas; check CoAuthor credits; get a share link; or send a draft to WordPress. Not for git "Co-authored-by" commit trailers.
3
3
  alwaysApply: false
4
4
  ---
5
5
 
@@ -14,7 +14,7 @@ You drive it with the `coauthor` CLI. CoAuthor does the writing. **You are the u
14
14
  ## Before you start
15
15
 
16
16
  1. `coauthor --version`. If the command is missing: `npm install -g @clickminded/coauthor-cli`.
17
- 2. `coauthor auth status --json`. If `data.hasToken` is false, run `coauthor auth login --no-browser` in the background, give the user the printed URL and code to approve in their browser, and wait for it to finish.
17
+ 2. `coauthor auth status --json`. If `data.hasToken` is false, run `coauthor auth login --no-browser` in the background, give the user the printed URL and code to approve in their browser, and wait for it to finish. `coauthor credits --json` confirms the account works and shows the plan, credits left and reset date; it needs no project.
18
18
  3. Never print tokens or `~/.coauthor/config.json`. Never ask the user to paste AI provider keys into chat; keys belong in CoAuthor's AI settings.
19
19
 
20
20
  ## Rules
@@ -67,7 +67,7 @@ Everything else, including auth problems: `references/troubleshooting.md`. Credi
67
67
 
68
68
  When the user wants to know what to write about for a business site, or asks for a keyword or content strategy, make a plan instead of guessing topics. A plan reads live search data and the profile's website, then lists post ideas that can win, pages to improve, and page ideas that are not blog posts.
69
69
 
70
- - `coauthor seo-plan generate --wait --json` makes it: about 420 credits (most plans 300–500) and 5–12 minutes. Tell the user the cost first. After 9 minutes it exits 2 with `still_running`; run the same command again to keep waiting.
70
+ - `coauthor seo-plan generate --wait --json` makes it: about 420 credits (most plans 300–500) and 5–12 minutes. Tell the user the cost first. After 9 minutes it exits 2 with `still_running`; to keep waiting, run the `resume_command` it prints (it reuses the request's `--idempotency-key`, so it never starts a second plan) or poll `coauthor seo-plan show --json`. Never re-run `generate` without that key to keep waiting: once the first plan is ready, that makes and charges for a new one.
71
71
  - `coauthor seo-plan show --json` reads it (strategy, Do next moves, counts, `--kind post|improve|page|left_out|covered|not_checked`).
72
72
  - `coauthor seo-plan write <item-id> --json` opens a project for a `post` idea, already set up from the plan; continue with `workflow run <project-id> --target outline` as usual. Only `post` items are writable: `improve` items are edits to a page the site already has, and `page` items are site tasks.
73
73
  - `coauthor seo-plan dismiss <item-id> [--undo] --json` hides an idea the user rules out.
@@ -271,7 +271,7 @@ SEO mode is rolling out gradually; accounts outside it get `feature_unavailable`
271
271
 
272
272
  ### Credits
273
273
 
274
- `coauthor credits <id> --json` shows the user's plan, this period's allowance, credits used and held by running work, what remains, and when the period resets. Credits reset monthly on the subscription anniversary.
274
+ `coauthor credits --json` (or `coauthor credits <id> --json` for a project; the balance is the account's either way) shows the user's plan, this period's allowance, credits used and held by running work, what remains, and when the period resets. Credits reset monthly on the subscription anniversary.
275
275
 
276
276
  Rough costs, to set expectations before starting:
277
277
 
@@ -317,6 +317,7 @@ coauthor draft revise <id> --instruction "Cut the intro to two sentences and lea
317
317
  - One revision can be open on a draft at a time, and an open one blocks the user's saves in the browser. Always apply or discard it. `revision_pending` means one is already open. A revision you leave waiting for review is discarded automatically after 30 minutes (`expires_at` in `draft revision show`), so review it promptly; after that, start a new one.
318
318
  - If `--wait` returns `still_running`, check again with `coauthor draft revision show <id> <revision-id> --json`.
319
319
  - While a revision runs, up to 100 available credits are temporarily held for its steps. Only actual usage is charged; unused held credits are released when it finishes or stops. A hold is included in `coauthor credits <id> --json` and does not change the request's spending limit.
320
+ - A revision that ends without a result (it failed, or didn't finish within 12 minutes and was closed) has the credits it used refunded automatically. A revision you cancel is not refunded.
320
321
  - `revise_unavailable` means this account cannot revise by instruction yet; use a direct edit.
321
322
 
322
323
  ### 2. Direct edit (exact text you already have)
@@ -627,7 +628,7 @@ coauthor seo-plan results [--profile <id>] --json
627
628
  ```
628
629
 
629
630
  - Without `--profile` the default profile is used. Run `coauthor profile list --json` first when the user has several profiles and the request names a site or brand.
630
- - `generate` returns at once with `data.plan_id`, `data.free` and `data.estimate_credits`. With `--wait` it polls until the plan is ready. After 9 minutes it exits with code 2 and `still_running`; run the same `generate ... --wait` command again to keep waiting (it joins the running plan; it does not start a second one).
631
+ - `generate` returns at once with `data.plan_id`, `data.free` and `data.estimate_credits`. With `--wait` it polls until the plan is ready. After 9 minutes it exits with code 2 and `still_running` and prints a `resume_command`. Run that to keep waiting: it reuses the request's `--idempotency-key`, so it replays the first request instead of starting a second plan, and returns the plan if it finished in the meantime. You can also poll `coauthor seo-plan show --json` until `plan.status` is `ready`. Don't re-run plain `generate ... --wait` to keep waiting: while the plan runs it joins it, but once the plan is ready it makes (and charges for) a new one.
631
632
  - Many plans can be made at once, so a new plan may wait its turn. While `status` is `queued`, the status data carries `queue_position` (1 = next), `queue_eta_minutes` (a rough estimate) and `queue_paused`; the position and estimate are `null` once the plan is running or before the position is known. When `queue_paused` is `true` the plan is waiting for free plans to resume and has no estimate. Tell the user their place in line and keep waiting; the plan starts by itself.
632
633
  - A plan can still be the free **preview** a person got from the website (`data.plan.is_preview` is `true`): it holds only the first 10 posts and a few pages to improve, with no monthly check. Running `generate` finishes it into the full plan, which counts as the user's free first plan (`first_plan_free` ignores previews). Say so when the user asks why a plan is short.
633
634
  - `--adjust` is a short steer for this run, for example `--adjust "focus on B2B buyers, skip anything about hiring"`. Use it when the user wants a different emphasis. Competitors are found automatically; the user corrects them in the web app.