@clickminded/coauthor-cli 0.0.70 → 0.0.72

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;
@@ -2302,6 +2320,8 @@ function httpErrorCode(error) {
2302
2320
  const code = planRecord(body.error).code;
2303
2321
  return typeof code === 'string' ? code : null;
2304
2322
  }
2323
+ /** Post types the plan gives to link magnets: reference posts other sites link to as a source. */
2324
+ const SEO_PLAN_LINK_MAGNET_POST_TYPES = ['stats_hub', 'regulation_tracker', 'cost_reference'];
2305
2325
  function seoPlanItemLine(item) {
2306
2326
  const keyword = planString(item, 'primary_keyword');
2307
2327
  const title = planString(item, 'title') ?? keyword ?? '(untitled)';
@@ -2311,7 +2331,9 @@ function seoPlanItemLine(item) {
2311
2331
  planString(item, 'chance'),
2312
2332
  ].filter(Boolean).join(', ');
2313
2333
  const id = planString(item, 'id') ?? '';
2314
- const head = ` ${id} ${title}`;
2334
+ const postType = planString(item, 'post_type');
2335
+ const linkMagnet = (item.kind === undefined || item.kind === 'post') && postType !== null && SEO_PLAN_LINK_MAGNET_POST_TYPES.includes(postType) ? '[link magnet] ' : '';
2336
+ const head = ` ${id} ${linkMagnet}${title}`;
2315
2337
  const search = keyword && keyword !== title ? ` [search: ${keyword}]` : '';
2316
2338
  const where = planString(item, 'existing_url');
2317
2339
  const position = typeof item.existing_position === 'number' ? ` (position ${item.existing_position})` : '';
@@ -2527,9 +2549,8 @@ function seoPlanQueueNote(status) {
2527
2549
  return null;
2528
2550
  return `#${position} in line, starts in about ${eta} min`;
2529
2551
  }
2530
- async function waitForSeoPlan(client, profileId, started) {
2552
+ async function waitForSeoPlan(client, profileId, started, resume) {
2531
2553
  const statusPath = `profiles/${encodeURIComponent(profileId)}/seo-plan/status`;
2532
- const resume = `coauthor seo-plan generate --profile ${profileId} --wait`;
2533
2554
  const deadline = Date.now() + waitTimeoutMs(9 * 60_000);
2534
2555
  const pollMs = Math.max(waitPollMs(), 0);
2535
2556
  let status = planRecord(await client.request({ path: statusPath }));
@@ -2544,7 +2565,9 @@ async function waitForSeoPlan(client, profileId, started) {
2544
2565
  status: 'still_running',
2545
2566
  exitCode: 2,
2546
2567
  resume_command: resume,
2547
- 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.`,
2548
2571
  data: (started ?? status),
2549
2572
  };
2550
2573
  }
@@ -2591,7 +2614,9 @@ async function runSeoPlanCommand(action, input, client) {
2591
2614
  throw new Error('--adjust can be at most 2000 characters.');
2592
2615
  const wait = getBoolean(input.values, 'wait');
2593
2616
  const profileId = await resolveProfileOption(input, client);
2617
+ const resuming = Boolean(getString(input.values, 'idempotency-key')?.trim());
2594
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`;
2595
2620
  let started;
2596
2621
  try {
2597
2622
  started = await client.request({
@@ -2603,11 +2628,13 @@ async function runSeoPlanCommand(action, input, client) {
2603
2628
  }
2604
2629
  catch (error) {
2605
2630
  // One plan runs per account at a time. When --wait finds this profile's plan already running
2606
- // (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.
2607
2633
  if (wait && httpErrorCode(error) === 'plan_running') {
2608
2634
  const status = planRecord(await client.request({ path: `profiles/${encodeURIComponent(profileId)}/seo-plan/status` }));
2609
- if (status.done === false)
2610
- 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
+ }
2611
2638
  }
2612
2639
  throw error;
2613
2640
  }
@@ -2623,7 +2650,7 @@ async function runSeoPlanCommand(action, input, client) {
2623
2650
  data: started,
2624
2651
  };
2625
2652
  }
2626
- const result = await waitForSeoPlan(client, profileId, started);
2653
+ const result = await waitForSeoPlan(client, profileId, started, resume);
2627
2654
  return { ...result, idempotency_key: idempotencyKey };
2628
2655
  }
2629
2656
  if (action === 'monthly-check') {
@@ -3518,7 +3545,7 @@ export function helpResult(command = []) {
3518
3545
  ' publish thread (supports --idempotency-key)',
3519
3546
  ' export list|wordpress (supports --idempotency-key)',
3520
3547
  ' operation list|show|status (publish, export and image generate/edit)',
3521
- ' credits',
3548
+ ' credits [<project-id>]',
3522
3549
  ' share <project-id>',
3523
3550
  ' models list|preferences show|preferences set',
3524
3551
  ' skills list|install',
@@ -3634,7 +3661,7 @@ function commandHelp(command) {
3634
3661
  ].join('\n'),
3635
3662
  'seo-plan': [
3636
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]',
3637
- ' 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]',
3638
3665
  ' coauthor seo-plan write <item-id> [--json]',
3639
3666
  ' coauthor seo-plan dismiss <item-id> [--undo] [--json]',
3640
3667
  ' coauthor seo-plan done <item-id> [--undo] [--json]',
@@ -3643,7 +3670,7 @@ function commandHelp(command) {
3643
3670
  '',
3644
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.',
3645
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.',
3646
- '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.',
3647
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.',
3648
3675
  'dismiss hides an idea from the plan; --undo brings it back.',
3649
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.',
@@ -3796,9 +3823,10 @@ function commandHelp(command) {
3796
3823
  'Returns the public read-only link (data.share_url), creating it if needed. Anyone with the link can read the draft.',
3797
3824
  ].join('\n'),
3798
3825
  credits: [
3799
- 'Usage: coauthor credits <project-id> [--json]',
3826
+ 'Usage: coauthor credits [<project-id>] [--json]',
3800
3827
  '',
3801
- '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.',
3802
3830
  ].join('\n'),
3803
3831
  'skills install': [
3804
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.70",
3
+ "version": "0.0.72",
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
 
@@ -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.
@@ -52,6 +52,18 @@ Each item has a `kind`, which decides what you can do with it:
52
52
  | `covered` | The site already ranks well for it. | Nothing. |
53
53
  | `not_checked` | Ideas the plan did not have budget to check. | Optional; a later update may check them. |
54
54
 
55
+ ### Link magnets
56
+
57
+ Some `post` items are **link magnets**: reference pages other sites cite as a source, so each link that comes in makes the whole site stronger and helps its other posts rank. A plan holds at most three, and only when the search data shows that pages like this earn links for this kind of site (many plans have none). A link magnet is a `post` item whose `post_type` is one of:
58
+
59
+ - `stats_hub`: a statistics page that collects current numbers on a topic, each with its source.
60
+ - `regulation_tracker`: a rules or law tracker by state, country or city, with the date it was last checked.
61
+ - `cost_reference`: a price or cost reference, with where each figure comes from.
62
+
63
+ They all have `stage: "Learning"`. `reason` holds the evidence in one line (for example "Pages like this earn links from 50+ other sites."), `note` says what to build, and `top_results` lists the pages that earn links today. `chance` is not an outranking chance for these: do not describe a link magnet as an easy win. In the human output of `show` they are prefixed `[link magnet]`; the web app shows a "Link magnet" badge and a "Pages others link to" section.
64
+
65
+ Write one like any other post with `seo-plan write`. Tell the user why it is on the list ("other sites would cite it"), and warn that it needs current, sourced figures: a link magnet is only worth building if every number is dated and traceable. Do not pick a link magnet for the user over their easier posts unless they ask for link building.
66
+
55
67
  Other fields to use when you recommend an idea:
56
68
 
57
69
  - `stage`: `Ready to buy`, `Comparing options` or `Learning`. It sets how strong the post's call to action is.
@@ -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
 
@@ -627,7 +627,7 @@ coauthor seo-plan results [--profile <id>] --json
627
627
  ```
628
628
 
629
629
  - 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).
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` 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
631
  - 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
632
  - 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
633
  - `--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.
@@ -647,6 +647,18 @@ Each item has a `kind`, which decides what you can do with it:
647
647
  | `covered` | The site already ranks well for it. | Nothing. |
648
648
  | `not_checked` | Ideas the plan did not have budget to check. | Optional; a later update may check them. |
649
649
 
650
+ #### Link magnets
651
+
652
+ Some `post` items are **link magnets**: reference pages other sites cite as a source, so each link that comes in makes the whole site stronger and helps its other posts rank. A plan holds at most three, and only when the search data shows that pages like this earn links for this kind of site (many plans have none). A link magnet is a `post` item whose `post_type` is one of:
653
+
654
+ - `stats_hub`: a statistics page that collects current numbers on a topic, each with its source.
655
+ - `regulation_tracker`: a rules or law tracker by state, country or city, with the date it was last checked.
656
+ - `cost_reference`: a price or cost reference, with where each figure comes from.
657
+
658
+ They all have `stage: "Learning"`. `reason` holds the evidence in one line (for example "Pages like this earn links from 50+ other sites."), `note` says what to build, and `top_results` lists the pages that earn links today. `chance` is not an outranking chance for these: do not describe a link magnet as an easy win. In the human output of `show` they are prefixed `[link magnet]`; the web app shows a "Link magnet" badge and a "Pages others link to" section.
659
+
660
+ Write one like any other post with `seo-plan write`. Tell the user why it is on the list ("other sites would cite it"), and warn that it needs current, sourced figures: a link magnet is only worth building if every number is dated and traceable. Do not pick a link magnet for the user over their easier posts unless they ask for link building.
661
+
650
662
  Other fields to use when you recommend an idea:
651
663
 
652
664
  - `stage`: `Ready to buy`, `Comparing options` or `Learning`. It sets how strong the post's call to action is.