@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 +1 -0
- package/dist/commands.js +32 -6
- package/dist/parser.js +1 -1
- package/package.json +1 -1
- package/skills/coauthor/SKILL.md +1 -0
- package/skills/coauthor/references/credits-and-plans.md +1 -1
- package/skills/coauthor/references/seo-content-plan.md +11 -5
- package/skills/coauthor/references/troubleshooting.md +2 -2
- package/skills/cursor/coauthor-cli.mdc +15 -8
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
|
-
|
|
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
|
|
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
package/skills/coauthor/SKILL.md
CHANGED
|
@@ -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
|
|
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
|
-
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
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 `
|
|
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
|
|
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
|
-
-
|
|
595
|
-
-
|
|
596
|
-
-
|
|
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 `
|
|
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. |
|