@clickminded/coauthor-cli 0.0.56 → 0.0.58

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
@@ -91,6 +91,7 @@ coauthor seo-plan generate --wait --json # SEO content pla
91
91
  coauthor seo-plan show --kind post --json # strategy, Do next moves, counts, and the post ideas
92
92
  coauthor seo-plan write <item-id> --json # open a project for a post idea, then continue with workflow run
93
93
  coauthor seo-plan dismiss <item-id> --json # hide an idea (--undo brings it back)
94
+ coauthor seo-plan done <item-id> --json # mark an idea done, e.g. after improving the page (--undo clears it)
94
95
  ```
95
96
 
96
97
  Run `coauthor --help` or `coauthor <command> --help` for every command and option. `--json` gives machine-readable output, `--wait` waits for long-running work, and JSON options such as `--data` and `--contract` accept `@file.json` (or `@-` for stdin).
package/dist/commands.js CHANGED
@@ -2219,6 +2219,7 @@ const SEO_PLAN_USAGE = [
2219
2219
  ' coauthor seo-plan generate [--profile <profile-id>] [--adjust "<text>"] [--wait] [--json]',
2220
2220
  ' coauthor seo-plan write <item-id> [--json]',
2221
2221
  ' coauthor seo-plan dismiss <item-id> [--undo] [--json]',
2222
+ ' coauthor seo-plan done <item-id> [--undo] [--json]',
2222
2223
  ].join('\n');
2223
2224
  function planRecord(value) {
2224
2225
  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
@@ -2260,8 +2261,9 @@ function seoPlanItemLine(item) {
2260
2261
  const hint = planString(item, 'improve_hint') ?? planString(item, 'reason') ?? planString(item, 'note');
2261
2262
  const written = planString(item, 'project_id') ? ` -> project ${planString(item, 'project_id')}` : '';
2262
2263
  const dismissed = item.dismissed === true ? ' (dismissed)' : '';
2264
+ const done = planString(item, 'done_at') ? ' (done)' : '';
2263
2265
  return [
2264
- `${head}${search}${facts ? ` (${facts})` : ''}${written}${dismissed}`,
2266
+ `${head}${search}${facts ? ` (${facts})` : ''}${written}${dismissed}${done}`,
2265
2267
  where ? ` ${where}${position}` : null,
2266
2268
  hint ? ` ${hint}` : null,
2267
2269
  ].filter(Boolean).join('\n');
@@ -2271,8 +2273,10 @@ function seoPlanShowMessage(data, kind) {
2271
2273
  const plan = view.plan === null || view.plan === undefined ? null : planRecord(view.plan);
2272
2274
  const estimate = typeof view.estimate_credits === 'number' ? view.estimate_credits : null;
2273
2275
  const status = plan ? planString(plan, 'status') : null;
2276
+ const firstPlanFree = view.first_plan_free === true;
2274
2277
  if (!plan || status === 'idle') {
2275
- return `No SEO content plan for this profile yet. Make one with \`coauthor seo-plan generate --wait\`${estimate ? ` (about ${estimate} credits)` : ''}.`;
2278
+ const cost = firstPlanFree ? ' (your first plan is free)' : estimate ? ` (about ${estimate} credits)` : '';
2279
+ return `No SEO content plan for this profile yet. Make one with \`coauthor seo-plan generate --wait\`${cost}.`;
2276
2280
  }
2277
2281
  const lines = [];
2278
2282
  if (status === 'queued' || status === 'running') {
@@ -2281,7 +2285,7 @@ function seoPlanShowMessage(data, kind) {
2281
2285
  }
2282
2286
  else if (status === 'failed') {
2283
2287
  const code = planString(plan, 'error_code');
2284
- lines.push(`The last plan run failed${code ? ` (${code})` : ''}: ${planString(plan, 'error_message') ?? 'unknown error'}. Try again with \`coauthor seo-plan generate --wait\`.`);
2288
+ lines.push(`The last plan run failed${code ? ` (${code})` : ''}: ${planString(plan, 'error_message') ?? 'unknown error'}. Try again with \`coauthor seo-plan generate --wait\`.${firstPlanFree ? ' Your first plan is free, so the retry uses no credits.' : ''}`);
2285
2289
  }
2286
2290
  if (view.stale === true)
2287
2291
  lines.push('The profile\'s website or market changed since this plan was made. `coauthor seo-plan generate` updates it.');
@@ -2361,7 +2365,7 @@ async function waitForSeoPlan(client, profileId, started) {
2361
2365
  };
2362
2366
  }
2363
2367
  async function runSeoPlanCommand(action, input, client) {
2364
- if (!action || !['show', 'generate', 'write', 'dismiss'].includes(action))
2368
+ if (!action || !['show', 'generate', 'write', 'dismiss', 'done'].includes(action))
2365
2369
  throw new Error(SEO_PLAN_USAGE);
2366
2370
  if (action === 'show') {
2367
2371
  const kind = (getString(input.values, 'kind') ?? 'post').trim().toLowerCase().replace(/-/g, '_');
@@ -2410,7 +2414,9 @@ async function runSeoPlanCommand(action, input, client) {
2410
2414
  throw error;
2411
2415
  }
2412
2416
  const estimate = getResponseNumber(started, 'estimate_credits');
2413
- const queued = `Plan queued${estimate ? ` (about ${estimate} credits, charged as it runs)` : ''}. It takes about 5 to 12 minutes.`;
2417
+ const free = planRecord(started).free === true;
2418
+ const cost = free ? ' (your first plan is free: no credits are used)' : estimate ? ` (about ${estimate} credits, charged as it runs)` : '';
2419
+ const queued = `Plan queued${cost}. It takes about 5 to 12 minutes.`;
2414
2420
  if (!wait) {
2415
2421
  return {
2416
2422
  ok: true,
@@ -2440,6 +2446,24 @@ async function runSeoPlanCommand(action, input, client) {
2440
2446
  data,
2441
2447
  };
2442
2448
  }
2449
+ if (action === 'done') {
2450
+ if (!itemId)
2451
+ throw new Error('Usage: coauthor seo-plan done <item-id> [--undo]');
2452
+ const undoDone = getBoolean(input.values, 'undo');
2453
+ const data = await client.request({
2454
+ method: 'POST',
2455
+ path: `seo-plan/items/${encodeURIComponent(itemId)}/done`,
2456
+ body: { done: !undoDone },
2457
+ });
2458
+ return {
2459
+ ok: true,
2460
+ message: undoDone
2461
+ ? `Cleared the done mark on ${itemId}.`
2462
+ : `Marked ${itemId} as done. Clear it with \`coauthor seo-plan done ${itemId} --undo\`.`,
2463
+ messageIncludesData: true,
2464
+ data,
2465
+ };
2466
+ }
2443
2467
  if (!itemId)
2444
2468
  throw new Error('Usage: coauthor seo-plan dismiss <item-id> [--undo]');
2445
2469
  const undo = getBoolean(input.values, 'undo');
@@ -3257,7 +3281,7 @@ export function helpResult(command = []) {
3257
3281
  ' profile list|show|update (update: --interactive-widgets on|off)',
3258
3282
  ' widgets list|status|build|build-all|use-image|edit|delete (interactives, beta)',
3259
3283
  ' site status|reindex [--profile <profile-id>] (limited rollout)',
3260
- ' seo-plan show|generate|write|dismiss (limited rollout)',
3284
+ ' seo-plan show|generate|write|dismiss|done (limited rollout)',
3261
3285
  ' source list|add|remove',
3262
3286
  ' integrations list',
3263
3287
  ' log add|show',
@@ -3394,12 +3418,14 @@ function commandHelp(command) {
3394
3418
  ' coauthor seo-plan generate [--profile <profile-id>] [--adjust "<text>"] [--wait] [--json]',
3395
3419
  ' coauthor seo-plan write <item-id> [--json]',
3396
3420
  ' coauthor seo-plan dismiss <item-id> [--undo] [--json]',
3421
+ ' coauthor seo-plan done <item-id> [--undo] [--json]',
3397
3422
  '',
3398
3423
  'SEO content plan (limited rollout): 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.',
3399
3424
  '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.',
3400
3425
  '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.',
3401
3426
  '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.',
3402
3427
  'dismiss hides an idea from the plan; --undo brings it back.',
3428
+ '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.',
3403
3429
  'Errors: not_enabled, profile_not_found, profile_archived, site_required, site_indexing, market_confirmation_needed, market_not_supported, insufficient_credits, plan_running, worker_unavailable, plan_stale, plan_updated, not_writable, plan_item_not_found.',
3404
3430
  ].join('\n'),
3405
3431
  integrations: [
package/dist/parser.js CHANGED
@@ -188,7 +188,7 @@ function commandLength(positionals) {
188
188
  if (first === 'site')
189
189
  return second && ['status', 'reindex'].includes(second) ? 2 : 1;
190
190
  if (first === 'seo-plan')
191
- return second && ['show', 'generate', 'write', 'dismiss'].includes(second) ? 2 : 1;
191
+ return second && ['show', 'generate', 'write', 'dismiss', 'done'].includes(second) ? 2 : 1;
192
192
  if (first === 'integrations')
193
193
  return second === 'list' ? 2 : 1;
194
194
  if (first === 'source')
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.56",
3
+ "version": "0.0.58",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -69,6 +69,7 @@ When the user wants to know what to write about for a business site, or asks for
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.
72
+ - `coauthor seo-plan done <item-id> [--undo] --json` marks an idea done (usually an `improve` page the user has updated). Items carry `done_at`; a done idea stays done when the plan is updated.
72
73
 
73
74
  Details, item fields, and what each kind means: `references/seo-content-plan.md`. If a command answers `not_enabled`, the account is outside the rollout; carry on without a plan.
74
75
 
@@ -9,7 +9,7 @@ Rough costs, to set expectations before starting:
9
9
  - A complete article (brief through draft) is typically about 300 credits.
10
10
  - Images and extra rework rounds (regenerating, many revisions) drive cost more than word count does.
11
11
  - Adding the repurposed formats in the web app (social posts, newsletter, slideshow) adds roughly 100–150 more.
12
- - An SEO content plan (`coauthor seo-plan generate`) is about 420 credits (most plans 300–500) and needs 500 remaining to start. See `references/seo-content-plan.md`.
12
+ - An SEO content plan (`coauthor seo-plan generate`): the first plan an account makes is free. Later plans are about 420 credits (most plans 300–500) and need 500 remaining to start. See `references/seo-content-plan.md`.
13
13
 
14
14
  Tell the user the expected cost before large or repeated work, and report credits used at the end.
15
15
 
@@ -12,9 +12,10 @@ Accounts outside the rollout get `not_enabled` from every `seo-plan` command. Ca
12
12
 
13
13
  ## Cost and timing
14
14
 
15
- - A plan costs about 420 credits (most plans 300 to 500), charged as it runs, and takes about 5 to 12 minutes. `generate` prints an estimate; tell the user before you start, and get a yes if they have not asked for a plan.
16
- - The account needs at least 500 credits remaining to start, otherwise `insufficient_credits` (nothing is spent).
17
- - Reading the plan (`show`), writing from it, and dismissing ideas cost nothing. Writing a post from an idea then costs credits like any other piece.
15
+ - The first plan an account makes is free: no credits are used. `show` reports `data.first_plan_free: true` until any plan has finished, and `generate` returns `data.free: true` with `data.estimate_credits: 0`. A first run that fails leaves the account eligible, so the retry is free too. It starts only if the account has at least 1 credit remaining (`insufficient_credits` with `details.required: 1` otherwise).
16
+ - Every later plan costs about 420 credits (most plans 300 to 500), charged as it runs, and takes about 5 to 12 minutes. This includes Update plan, `--adjust`, and a plan for another profile. `generate` prints an estimate; tell the user before you start, and get a yes if they have not asked for a plan.
17
+ - A paid plan needs at least 500 credits remaining to start, otherwise `insufficient_credits` (nothing is spent).
18
+ - Reading the plan (`show`), writing from it, and dismissing or marking ideas done cost nothing. Writing a post from an idea then costs credits like any other piece.
18
19
  - Only one plan runs per account at a time (`plan_running`).
19
20
 
20
21
  ## Commands
@@ -25,10 +26,11 @@ COAUTHOR_CLI_WAIT_TIMEOUT_MS=540000 coauthor seo-plan generate --wait --json
25
26
  coauthor seo-plan show [--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
26
27
  coauthor seo-plan write <item-id> --json
27
28
  coauthor seo-plan dismiss <item-id> [--undo] --json
29
+ coauthor seo-plan done <item-id> [--undo] --json
28
30
  ```
29
31
 
30
32
  - 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.
31
- - `generate` returns at once with `data.plan_id` 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).
33
+ - `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).
32
34
  - `--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.
33
35
  - `show` returns `data.plan` (`strategy_line`, `competitors_line`, `status`), `data.do_next` (the five best next moves), `data.counts_by_kind`, and `data.items` for one `--kind` (default `post`). Items are sorted as the web app shows them.
34
36
  - A plan run that fails says why in `data.error_code` and `data.error_message` (see `references/troubleshooting.md`). Credits for a failed run are only charged for work that finished.
@@ -40,7 +42,7 @@ Each item has a `kind`, which decides what you can do with it:
40
42
  | `kind` | What it is | What to do |
41
43
  | --- | --- | --- |
42
44
  | `post` | A blog post idea that can rank. | **Write this**: `coauthor seo-plan write <item-id>`. |
43
- | `improve` | The site already has a page for this search (`existing_url`, `existing_position`). | **Improve this page**: do not write a new post (it would compete with the old one). Tell the user what `improve_hint` says; the edit happens on their site. |
45
+ | `improve` | The site already has a page for this search (`existing_url`, `existing_position`). | **Improve this page**: do not write a new post (it would compete with the old one). Tell the user what `improve_hint` says (two or three short sentences, each one concrete change; the edit happens on their site). Mark it done afterwards with `seo-plan done`. |
44
46
  | `page` | The search wants a product, pricing, landing, category or tool page, not an article. | **Page idea**: not a blog post and not writable. Give it to the user as a site task (`page_kind` says what kind). |
45
47
  | `left_out` | A search the plan skipped, with the `reason` (another brand's name, the wrong meaning, videos or forums only, and so on). | Nothing. Mention it only if the user asks why something is missing. |
46
48
  | `covered` | The site already ranks well for it. | Nothing. |
@@ -68,6 +70,10 @@ Errors: `plan_stale` (the profile's website or market changed; run `generate` to
68
70
 
69
71
  `coauthor seo-plan dismiss <item-id> --json` hides an idea the user does not want (it leaves the counts and `show`). `--undo` brings it back. Use it when the user rules an idea out; do not dismiss on your own judgment.
70
72
 
73
+ ## Mark as done
74
+
75
+ `coauthor seo-plan done <item-id> --json` marks an idea as done and returns `data.item_id` and `data.done_at`. `--undo` clears the mark (`done_at` is `null`). Use it for an `improve` item once the user says the page has been updated, or for any other idea they have finished outside CoAuthor. Do not mark ideas done on your own judgment. Done ideas stay in `show` with a non-null `done_at` (the human output marks them `(done)`), and they stay done when the plan is updated with `generate`. Only `post`, `improve`, `covered` and `page` items can be marked; other ids answer `plan_item_not_found`.
76
+
71
77
  ## What to tell the user
72
78
 
73
79
  Summarize rather than dump: the `strategy_line`, the Do next moves with their `chance` and why, and the counts. Offer to write the first one or two posts. Mention `improve` items separately, because they are quick wins on pages that already rank.
@@ -61,7 +61,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
61
61
  | `site_indexing` | CoAuthor is still reading the profile's website. | Check `coauthor site status`; run `generate` again when it is `ready` (a few minutes). Nothing was spent. |
62
62
  | `market_confirmation_needed` | CoAuthor can't tell which country's search results to plan for. | The user confirms the search country in the profile settings in the web app, then run `generate` again. Nothing was spent. |
63
63
  | `market_not_supported` | Search data doesn't fully cover the profile's country and language. | Give the user `details.explanation.message` and its alternatives; they change the profile's country or language in the web app. Nothing was spent. |
64
- | `insufficient_credits` | A plan needs at least 500 credits remaining (`details.required`, `details.remaining`). | Tell the user; resume after the reset (`coauthor credits --json`). Nothing was spent. |
64
+ | `insufficient_credits` | A plan needs at least 500 credits remaining (`details.required`, `details.remaining`). The first plan is free but still needs at least 1 credit remaining (`details.free: true`). | Tell the user; resume after the reset (`coauthor credits --json`). Nothing was spent. |
65
65
  | `plan_running` | A plan is already being made on this account (only one runs at a time). | `coauthor seo-plan generate --profile <id> --wait` joins the running plan for that profile; otherwise wait and use `seo-plan show`. |
66
66
  | `worker_unavailable` | The plan service couldn't be reached. Nothing was spent. | Try again in a few minutes. |
67
67
  | `dataforseo_busy` | A plan run stopped because the search data provider was busy (`seo-plan show` or the `--wait` result carries it as `error_code`). | Run `coauthor seo-plan generate --wait` again in a few minutes. Work already done is cached, so a retry costs less. |
@@ -75,7 +75,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
75
75
  | `plan_stale` | `seo-plan write` on an idea from a plan built for a website or market the profile no longer has. | `coauthor seo-plan generate --wait --json` to update the plan, then pick an idea again. |
76
76
  | `plan_updated` | `seo-plan write` on an idea that a newer plan run replaced. | `coauthor seo-plan show --json` for the current ideas. |
77
77
  | `not_writable` | `seo-plan write` on an item that isn't a `post` idea (improve, page idea, left out, covered). | Only `post` items are written. Improve and page ideas are tasks on the user's site. |
78
- | `plan_item_not_found` | `seo-plan write` or `dismiss` with an unknown item id. | Take the `id` from `seo-plan show --json`. |
78
+ | `plan_item_not_found` | `seo-plan write`, `dismiss` or `done` with an unknown item id (`done` also rejects left-out and not-checked items). | Take the `id` from `seo-plan show --json`. |
79
79
  | `operation_in_progress` | A `seo-plan generate` with the same `--idempotency-key` is still being processed. | Wait a moment and check `coauthor seo-plan show`. |
80
80
  | `usage_error` | The command or its flags are wrong; nothing was sent. | Check `coauthor help <command>` and fix the command. |
81
81
  | `request_timeout`, `network_error` | No answer from CoAuthor in time, or the connection failed. | For reads, retry. For exports, publishes, and image generate/edit, check `coauthor operation status <idempotency_key>` before retrying. |
@@ -71,6 +71,7 @@ When the user wants to know what to write about for a business site, or asks for
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.
74
+ - `coauthor seo-plan done <item-id> [--undo] --json` marks an idea done (usually an `improve` page the user has updated). Items carry `done_at`; a done idea stays done when the plan is updated.
74
75
 
75
76
  Details, item fields, and what each kind means: `references/seo-content-plan.md`. If a command answers `not_enabled`, the account is outside the rollout; carry on without a plan.
76
77
 
@@ -275,7 +276,7 @@ Rough costs, to set expectations before starting:
275
276
  - A complete article (brief through draft) is typically about 300 credits.
276
277
  - Images and extra rework rounds (regenerating, many revisions) drive cost more than word count does.
277
278
  - Adding the repurposed formats in the web app (social posts, newsletter, slideshow) adds roughly 100–150 more.
278
- - An SEO content plan (`coauthor seo-plan generate`) is about 420 credits (most plans 300–500) and needs 500 remaining to start. See `references/seo-content-plan.md`.
279
+ - An SEO content plan (`coauthor seo-plan generate`): the first plan an account makes is free. Later plans are about 420 credits (most plans 300–500) and need 500 remaining to start. See `references/seo-content-plan.md`.
279
280
 
280
281
  Tell the user the expected cost before large or repeated work, and report credits used at the end.
281
282
 
@@ -591,9 +592,10 @@ Accounts outside the rollout get `not_enabled` from every `seo-plan` command. Ca
591
592
 
592
593
  ### Cost and timing
593
594
 
594
- - A plan costs about 420 credits (most plans 300 to 500), charged as it runs, and takes about 5 to 12 minutes. `generate` prints an estimate; tell the user before you start, and get a yes if they have not asked for a plan.
595
- - The account needs at least 500 credits remaining to start, otherwise `insufficient_credits` (nothing is spent).
596
- - Reading the plan (`show`), writing from it, and dismissing ideas cost nothing. Writing a post from an idea then costs credits like any other piece.
595
+ - The first plan an account makes is free: no credits are used. `show` reports `data.first_plan_free: true` until any plan has finished, and `generate` returns `data.free: true` with `data.estimate_credits: 0`. A first run that fails leaves the account eligible, so the retry is free too. It starts only if the account has at least 1 credit remaining (`insufficient_credits` with `details.required: 1` otherwise).
596
+ - Every later plan costs about 420 credits (most plans 300 to 500), charged as it runs, and takes about 5 to 12 minutes. This includes Update plan, `--adjust`, and a plan for another profile. `generate` prints an estimate; tell the user before you start, and get a yes if they have not asked for a plan.
597
+ - A paid plan needs at least 500 credits remaining to start, otherwise `insufficient_credits` (nothing is spent).
598
+ - Reading the plan (`show`), writing from it, and dismissing or marking ideas done cost nothing. Writing a post from an idea then costs credits like any other piece.
597
599
  - Only one plan runs per account at a time (`plan_running`).
598
600
 
599
601
  ### Commands
@@ -604,10 +606,11 @@ COAUTHOR_CLI_WAIT_TIMEOUT_MS=540000 coauthor seo-plan generate --wait --json
604
606
  coauthor seo-plan show [--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
605
607
  coauthor seo-plan write <item-id> --json
606
608
  coauthor seo-plan dismiss <item-id> [--undo] --json
609
+ coauthor seo-plan done <item-id> [--undo] --json
607
610
  ```
608
611
 
609
612
  - 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.
610
- - `generate` returns at once with `data.plan_id` 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).
613
+ - `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).
611
614
  - `--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.
612
615
  - `show` returns `data.plan` (`strategy_line`, `competitors_line`, `status`), `data.do_next` (the five best next moves), `data.counts_by_kind`, and `data.items` for one `--kind` (default `post`). Items are sorted as the web app shows them.
613
616
  - A plan run that fails says why in `data.error_code` and `data.error_message` (see `references/troubleshooting.md`). Credits for a failed run are only charged for work that finished.
@@ -619,7 +622,7 @@ Each item has a `kind`, which decides what you can do with it:
619
622
  | `kind` | What it is | What to do |
620
623
  | --- | --- | --- |
621
624
  | `post` | A blog post idea that can rank. | **Write this**: `coauthor seo-plan write <item-id>`. |
622
- | `improve` | The site already has a page for this search (`existing_url`, `existing_position`). | **Improve this page**: do not write a new post (it would compete with the old one). Tell the user what `improve_hint` says; the edit happens on their site. |
625
+ | `improve` | The site already has a page for this search (`existing_url`, `existing_position`). | **Improve this page**: do not write a new post (it would compete with the old one). Tell the user what `improve_hint` says (two or three short sentences, each one concrete change; the edit happens on their site). Mark it done afterwards with `seo-plan done`. |
623
626
  | `page` | The search wants a product, pricing, landing, category or tool page, not an article. | **Page idea**: not a blog post and not writable. Give it to the user as a site task (`page_kind` says what kind). |
624
627
  | `left_out` | A search the plan skipped, with the `reason` (another brand's name, the wrong meaning, videos or forums only, and so on). | Nothing. Mention it only if the user asks why something is missing. |
625
628
  | `covered` | The site already ranks well for it. | Nothing. |
@@ -647,6 +650,10 @@ Errors: `plan_stale` (the profile's website or market changed; run `generate` to
647
650
 
648
651
  `coauthor seo-plan dismiss <item-id> --json` hides an idea the user does not want (it leaves the counts and `show`). `--undo` brings it back. Use it when the user rules an idea out; do not dismiss on your own judgment.
649
652
 
653
+ ### Mark as done
654
+
655
+ `coauthor seo-plan done <item-id> --json` marks an idea as done and returns `data.item_id` and `data.done_at`. `--undo` clears the mark (`done_at` is `null`). Use it for an `improve` item once the user says the page has been updated, or for any other idea they have finished outside CoAuthor. Do not mark ideas done on your own judgment. Done ideas stay in `show` with a non-null `done_at` (the human output marks them `(done)`), and they stay done when the plan is updated with `generate`. Only `post`, `improve`, `covered` and `page` items can be marked; other ids answer `plan_item_not_found`.
656
+
650
657
  ### What to tell the user
651
658
 
652
659
  Summarize rather than dump: the `strategy_line`, the Do next moves with their `chance` and why, and the counts. Offer to write the first one or two posts. Mention `improve` items separately, because they are quick wins on pages that already rank.
@@ -716,7 +723,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
716
723
  | `site_indexing` | CoAuthor is still reading the profile's website. | Check `coauthor site status`; run `generate` again when it is `ready` (a few minutes). Nothing was spent. |
717
724
  | `market_confirmation_needed` | CoAuthor can't tell which country's search results to plan for. | The user confirms the search country in the profile settings in the web app, then run `generate` again. Nothing was spent. |
718
725
  | `market_not_supported` | Search data doesn't fully cover the profile's country and language. | Give the user `details.explanation.message` and its alternatives; they change the profile's country or language in the web app. Nothing was spent. |
719
- | `insufficient_credits` | A plan needs at least 500 credits remaining (`details.required`, `details.remaining`). | Tell the user; resume after the reset (`coauthor credits --json`). Nothing was spent. |
726
+ | `insufficient_credits` | A plan needs at least 500 credits remaining (`details.required`, `details.remaining`). The first plan is free but still needs at least 1 credit remaining (`details.free: true`). | Tell the user; resume after the reset (`coauthor credits --json`). Nothing was spent. |
720
727
  | `plan_running` | A plan is already being made on this account (only one runs at a time). | `coauthor seo-plan generate --profile <id> --wait` joins the running plan for that profile; otherwise wait and use `seo-plan show`. |
721
728
  | `worker_unavailable` | The plan service couldn't be reached. Nothing was spent. | Try again in a few minutes. |
722
729
  | `dataforseo_busy` | A plan run stopped because the search data provider was busy (`seo-plan show` or the `--wait` result carries it as `error_code`). | Run `coauthor seo-plan generate --wait` again in a few minutes. Work already done is cached, so a retry costs less. |
@@ -730,7 +737,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
730
737
  | `plan_stale` | `seo-plan write` on an idea from a plan built for a website or market the profile no longer has. | `coauthor seo-plan generate --wait --json` to update the plan, then pick an idea again. |
731
738
  | `plan_updated` | `seo-plan write` on an idea that a newer plan run replaced. | `coauthor seo-plan show --json` for the current ideas. |
732
739
  | `not_writable` | `seo-plan write` on an item that isn't a `post` idea (improve, page idea, left out, covered). | Only `post` items are written. Improve and page ideas are tasks on the user's site. |
733
- | `plan_item_not_found` | `seo-plan write` or `dismiss` with an unknown item id. | Take the `id` from `seo-plan show --json`. |
740
+ | `plan_item_not_found` | `seo-plan write`, `dismiss` or `done` with an unknown item id (`done` also rejects left-out and not-checked items). | Take the `id` from `seo-plan show --json`. |
734
741
  | `operation_in_progress` | A `seo-plan generate` with the same `--idempotency-key` is still being processed. | Wait a moment and check `coauthor seo-plan show`. |
735
742
  | `usage_error` | The command or its flags are wrong; nothing was sent. | Check `coauthor help <command>` and fix the command. |
736
743
  | `request_timeout`, `network_error` | No answer from CoAuthor in time, or the connection failed. | For reads, retry. For exports, publishes, and image generate/edit, check `coauthor operation status <idempotency_key>` before retrying. |