@clickminded/coauthor-cli 0.0.55 → 0.0.57
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 +34 -6
- package/dist/parser.js +1 -1
- package/package.json +1 -1
- package/skills/coauthor/SKILL.md +1 -0
- package/skills/coauthor/references/interactive-widgets.md +1 -1
- package/skills/coauthor/references/seo-content-plan.md +7 -2
- package/skills/coauthor/references/troubleshooting.md +1 -1
- package/skills/cursor/coauthor-cli.mdc +10 -4
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
|
@@ -2130,12 +2130,18 @@ async function runWidgetsCommand(action, input, client) {
|
|
|
2130
2130
|
const placeholder = getResponseValue(data, 'placeholder');
|
|
2131
2131
|
const updated = getResponseValue(data, 'document_updated') === true;
|
|
2132
2132
|
const note = getResponseString(data, 'document_note');
|
|
2133
|
+
const alreadyDone = !updated && getResponseString(data, 'document_status') === 'already_removed';
|
|
2134
|
+
const placeholderId = placeholder?.placeholder_id ? String(placeholder.placeholder_id) : '<placeholder-id>';
|
|
2133
2135
|
return {
|
|
2134
2136
|
ok: true,
|
|
2135
2137
|
message: [
|
|
2136
|
-
`The interactive is replaced by an image placeholder${placeholder?.placeholder_id ? ` (${
|
|
2137
|
-
updated
|
|
2138
|
-
|
|
2138
|
+
`The interactive is replaced by an image placeholder${placeholder?.placeholder_id ? ` (${placeholderId})` : ''}.`,
|
|
2139
|
+
updated
|
|
2140
|
+
? 'The draft was updated.'
|
|
2141
|
+
: alreadyDone
|
|
2142
|
+
? 'Already done: the draft no longer has this interactive.'
|
|
2143
|
+
: `The draft was NOT updated${note ? `: ${note}` : '.'}`,
|
|
2144
|
+
`Generate the image with: coauthor image generate ${projectId} --placeholder-id ${placeholderId}`,
|
|
2139
2145
|
].join('\n'),
|
|
2140
2146
|
data,
|
|
2141
2147
|
};
|
|
@@ -2213,6 +2219,7 @@ const SEO_PLAN_USAGE = [
|
|
|
2213
2219
|
' coauthor seo-plan generate [--profile <profile-id>] [--adjust "<text>"] [--wait] [--json]',
|
|
2214
2220
|
' coauthor seo-plan write <item-id> [--json]',
|
|
2215
2221
|
' coauthor seo-plan dismiss <item-id> [--undo] [--json]',
|
|
2222
|
+
' coauthor seo-plan done <item-id> [--undo] [--json]',
|
|
2216
2223
|
].join('\n');
|
|
2217
2224
|
function planRecord(value) {
|
|
2218
2225
|
return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
|
|
@@ -2254,8 +2261,9 @@ function seoPlanItemLine(item) {
|
|
|
2254
2261
|
const hint = planString(item, 'improve_hint') ?? planString(item, 'reason') ?? planString(item, 'note');
|
|
2255
2262
|
const written = planString(item, 'project_id') ? ` -> project ${planString(item, 'project_id')}` : '';
|
|
2256
2263
|
const dismissed = item.dismissed === true ? ' (dismissed)' : '';
|
|
2264
|
+
const done = planString(item, 'done_at') ? ' (done)' : '';
|
|
2257
2265
|
return [
|
|
2258
|
-
`${head}${search}${facts ? ` (${facts})` : ''}${written}${dismissed}`,
|
|
2266
|
+
`${head}${search}${facts ? ` (${facts})` : ''}${written}${dismissed}${done}`,
|
|
2259
2267
|
where ? ` ${where}${position}` : null,
|
|
2260
2268
|
hint ? ` ${hint}` : null,
|
|
2261
2269
|
].filter(Boolean).join('\n');
|
|
@@ -2355,7 +2363,7 @@ async function waitForSeoPlan(client, profileId, started) {
|
|
|
2355
2363
|
};
|
|
2356
2364
|
}
|
|
2357
2365
|
async function runSeoPlanCommand(action, input, client) {
|
|
2358
|
-
if (!action || !['show', 'generate', 'write', 'dismiss'].includes(action))
|
|
2366
|
+
if (!action || !['show', 'generate', 'write', 'dismiss', 'done'].includes(action))
|
|
2359
2367
|
throw new Error(SEO_PLAN_USAGE);
|
|
2360
2368
|
if (action === 'show') {
|
|
2361
2369
|
const kind = (getString(input.values, 'kind') ?? 'post').trim().toLowerCase().replace(/-/g, '_');
|
|
@@ -2434,6 +2442,24 @@ async function runSeoPlanCommand(action, input, client) {
|
|
|
2434
2442
|
data,
|
|
2435
2443
|
};
|
|
2436
2444
|
}
|
|
2445
|
+
if (action === 'done') {
|
|
2446
|
+
if (!itemId)
|
|
2447
|
+
throw new Error('Usage: coauthor seo-plan done <item-id> [--undo]');
|
|
2448
|
+
const undoDone = getBoolean(input.values, 'undo');
|
|
2449
|
+
const data = await client.request({
|
|
2450
|
+
method: 'POST',
|
|
2451
|
+
path: `seo-plan/items/${encodeURIComponent(itemId)}/done`,
|
|
2452
|
+
body: { done: !undoDone },
|
|
2453
|
+
});
|
|
2454
|
+
return {
|
|
2455
|
+
ok: true,
|
|
2456
|
+
message: undoDone
|
|
2457
|
+
? `Cleared the done mark on ${itemId}.`
|
|
2458
|
+
: `Marked ${itemId} as done. Clear it with \`coauthor seo-plan done ${itemId} --undo\`.`,
|
|
2459
|
+
messageIncludesData: true,
|
|
2460
|
+
data,
|
|
2461
|
+
};
|
|
2462
|
+
}
|
|
2437
2463
|
if (!itemId)
|
|
2438
2464
|
throw new Error('Usage: coauthor seo-plan dismiss <item-id> [--undo]');
|
|
2439
2465
|
const undo = getBoolean(input.values, 'undo');
|
|
@@ -3251,7 +3277,7 @@ export function helpResult(command = []) {
|
|
|
3251
3277
|
' profile list|show|update (update: --interactive-widgets on|off)',
|
|
3252
3278
|
' widgets list|status|build|build-all|use-image|edit|delete (interactives, beta)',
|
|
3253
3279
|
' site status|reindex [--profile <profile-id>] (limited rollout)',
|
|
3254
|
-
' seo-plan show|generate|write|dismiss (limited rollout)',
|
|
3280
|
+
' seo-plan show|generate|write|dismiss|done (limited rollout)',
|
|
3255
3281
|
' source list|add|remove',
|
|
3256
3282
|
' integrations list',
|
|
3257
3283
|
' log add|show',
|
|
@@ -3388,12 +3414,14 @@ function commandHelp(command) {
|
|
|
3388
3414
|
' coauthor seo-plan generate [--profile <profile-id>] [--adjust "<text>"] [--wait] [--json]',
|
|
3389
3415
|
' coauthor seo-plan write <item-id> [--json]',
|
|
3390
3416
|
' coauthor seo-plan dismiss <item-id> [--undo] [--json]',
|
|
3417
|
+
' coauthor seo-plan done <item-id> [--undo] [--json]',
|
|
3391
3418
|
'',
|
|
3392
3419
|
'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.',
|
|
3393
3420
|
'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.',
|
|
3394
3421
|
'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.',
|
|
3395
3422
|
'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.',
|
|
3396
3423
|
'dismiss hides an idea from the plan; --undo brings it back.',
|
|
3424
|
+
'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.',
|
|
3397
3425
|
'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.',
|
|
3398
3426
|
].join('\n'),
|
|
3399
3427
|
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
|
|
|
@@ -25,7 +25,7 @@ coauthor models preferences set --widget-model claude-opus-5-5|claude-sonnet-5-5
|
|
|
25
25
|
- `list` returns `data.widgets` (each with `id`, `spec.title`, `spec.aha`, `spec.move`, `spec.visual`, `credit_cap`, `edit_credit_cap`, `replaces_image`, `build_state`, `current_version`, `embed_url`, and `error` when a build failed), `data.availability` (`canBuild` and the reason when not), and `data.model` (the build model and its cap). A placeholder has `current_version: null` and `build_state: "idle"`.
|
|
26
26
|
- `build` and `edit` queue the build and return at once (`already_running: true` if it was already building: calling again is safe). A build takes a few minutes. With `--wait` the command follows it for up to 9 minutes; on `still_running` run the `resume_command` it prints. Rebuilding a built widget works the same and costs credits again. Retries after a failure wait a minute (`widget_rate_limited`), and after 3 failed builds in a day the account must wait.
|
|
27
27
|
- `build-all` with no ids builds every placeholder; with ids, only those.
|
|
28
|
-
- `use-image` is for a placeholder that took over a planned image (`replaces_image: true`). It turns the node in the draft back into an image placeholder (it updates the draft for you); then generate it with `coauthor image generate <project-id> --placeholder-id <placeholder-id>`. If `document_updated` is false, the
|
|
28
|
+
- `use-image` is for a placeholder that took over a planned image (`replaces_image: true`). It turns the node in the draft back into an image placeholder (it updates the draft for you); then generate it with `coauthor image generate <project-id> --placeholder-id <placeholder-id>`. If `document_updated` is false, `document_status` says why: `already_removed` means a repeat (the swap was already done, nothing to fix); `not_updated` is a real failure and `document_note` has the manual fix. The call is safe to repeat.
|
|
29
29
|
- `edit` takes a plain instruction of up to 500 characters and rebuilds the widget. `edit` and `delete` change every published copy, so both need `--yes`: confirm with the user first. `delete` removes the interactive everywhere, including posts already published, and cannot be undone. It also removes the node from the draft.
|
|
30
30
|
- A built widget exports as its poster image linked to the live version in markdown and HTML (`draft get --format markdown`), and live in WordPress when the connection allows it.
|
|
31
31
|
|
|
@@ -14,7 +14,7 @@ Accounts outside the rollout get `not_enabled` from every `seo-plan` command. Ca
|
|
|
14
14
|
|
|
15
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
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.
|
|
17
|
+
- 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
18
|
- Only one plan runs per account at a time (`plan_running`).
|
|
19
19
|
|
|
20
20
|
## Commands
|
|
@@ -25,6 +25,7 @@ COAUTHOR_CLI_WAIT_TIMEOUT_MS=540000 coauthor seo-plan generate --wait --json
|
|
|
25
25
|
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
26
|
coauthor seo-plan write <item-id> --json
|
|
27
27
|
coauthor seo-plan dismiss <item-id> [--undo] --json
|
|
28
|
+
coauthor seo-plan done <item-id> [--undo] --json
|
|
28
29
|
```
|
|
29
30
|
|
|
30
31
|
- 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.
|
|
@@ -40,7 +41,7 @@ Each item has a `kind`, which decides what you can do with it:
|
|
|
40
41
|
| `kind` | What it is | What to do |
|
|
41
42
|
| --- | --- | --- |
|
|
42
43
|
| `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. |
|
|
44
|
+
| `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
45
|
| `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
46
|
| `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
47
|
| `covered` | The site already ranks well for it. | Nothing. |
|
|
@@ -68,6 +69,10 @@ Errors: `plan_stale` (the profile's website or market changed; run `generate` to
|
|
|
68
69
|
|
|
69
70
|
`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
71
|
|
|
72
|
+
## Mark as done
|
|
73
|
+
|
|
74
|
+
`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`.
|
|
75
|
+
|
|
71
76
|
## What to tell the user
|
|
72
77
|
|
|
73
78
|
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.
|
|
@@ -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
|
|
|
@@ -419,7 +420,7 @@ coauthor models preferences set --widget-model claude-opus-5-5|claude-sonnet-5-5
|
|
|
419
420
|
- `list` returns `data.widgets` (each with `id`, `spec.title`, `spec.aha`, `spec.move`, `spec.visual`, `credit_cap`, `edit_credit_cap`, `replaces_image`, `build_state`, `current_version`, `embed_url`, and `error` when a build failed), `data.availability` (`canBuild` and the reason when not), and `data.model` (the build model and its cap). A placeholder has `current_version: null` and `build_state: "idle"`.
|
|
420
421
|
- `build` and `edit` queue the build and return at once (`already_running: true` if it was already building: calling again is safe). A build takes a few minutes. With `--wait` the command follows it for up to 9 minutes; on `still_running` run the `resume_command` it prints. Rebuilding a built widget works the same and costs credits again. Retries after a failure wait a minute (`widget_rate_limited`), and after 3 failed builds in a day the account must wait.
|
|
421
422
|
- `build-all` with no ids builds every placeholder; with ids, only those.
|
|
422
|
-
- `use-image` is for a placeholder that took over a planned image (`replaces_image: true`). It turns the node in the draft back into an image placeholder (it updates the draft for you); then generate it with `coauthor image generate <project-id> --placeholder-id <placeholder-id>`. If `document_updated` is false, the
|
|
423
|
+
- `use-image` is for a placeholder that took over a planned image (`replaces_image: true`). It turns the node in the draft back into an image placeholder (it updates the draft for you); then generate it with `coauthor image generate <project-id> --placeholder-id <placeholder-id>`. If `document_updated` is false, `document_status` says why: `already_removed` means a repeat (the swap was already done, nothing to fix); `not_updated` is a real failure and `document_note` has the manual fix. The call is safe to repeat.
|
|
423
424
|
- `edit` takes a plain instruction of up to 500 characters and rebuilds the widget. `edit` and `delete` change every published copy, so both need `--yes`: confirm with the user first. `delete` removes the interactive everywhere, including posts already published, and cannot be undone. It also removes the node from the draft.
|
|
424
425
|
- A built widget exports as its poster image linked to the live version in markdown and HTML (`draft get --format markdown`), and live in WordPress when the connection allows it.
|
|
425
426
|
|
|
@@ -593,7 +594,7 @@ Accounts outside the rollout get `not_enabled` from every `seo-plan` command. Ca
|
|
|
593
594
|
|
|
594
595
|
- 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
596
|
- 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.
|
|
597
|
+
- 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
598
|
- Only one plan runs per account at a time (`plan_running`).
|
|
598
599
|
|
|
599
600
|
### Commands
|
|
@@ -604,6 +605,7 @@ COAUTHOR_CLI_WAIT_TIMEOUT_MS=540000 coauthor seo-plan generate --wait --json
|
|
|
604
605
|
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
606
|
coauthor seo-plan write <item-id> --json
|
|
606
607
|
coauthor seo-plan dismiss <item-id> [--undo] --json
|
|
608
|
+
coauthor seo-plan done <item-id> [--undo] --json
|
|
607
609
|
```
|
|
608
610
|
|
|
609
611
|
- 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.
|
|
@@ -619,7 +621,7 @@ Each item has a `kind`, which decides what you can do with it:
|
|
|
619
621
|
| `kind` | What it is | What to do |
|
|
620
622
|
| --- | --- | --- |
|
|
621
623
|
| `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. |
|
|
624
|
+
| `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
625
|
| `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
626
|
| `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
627
|
| `covered` | The site already ranks well for it. | Nothing. |
|
|
@@ -647,6 +649,10 @@ Errors: `plan_stale` (the profile's website or market changed; run `generate` to
|
|
|
647
649
|
|
|
648
650
|
`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
651
|
|
|
652
|
+
### Mark as done
|
|
653
|
+
|
|
654
|
+
`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`.
|
|
655
|
+
|
|
650
656
|
### What to tell the user
|
|
651
657
|
|
|
652
658
|
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.
|
|
@@ -730,7 +736,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
730
736
|
| `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
737
|
| `plan_updated` | `seo-plan write` on an idea that a newer plan run replaced. | `coauthor seo-plan show --json` for the current ideas. |
|
|
732
738
|
| `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 `
|
|
739
|
+
| `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
740
|
| `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
741
|
| `usage_error` | The command or its flags are wrong; nothing was sent. | Check `coauthor help <command>` and fix the command. |
|
|
736
742
|
| `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. |
|