@clickminded/coauthor-cli 0.0.68 → 0.0.69
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 -1
- package/dist/commands.js +50 -9
- package/dist/parser.js +2 -0
- package/package.json +1 -1
- package/skills/coauthor/SKILL.md +1 -1
- package/skills/coauthor/references/publishing-and-export.md +5 -1
- package/skills/coauthor/references/seo-content-plan.md +5 -3
- package/skills/coauthor/references/troubleshooting.md +3 -2
- package/skills/cursor/coauthor-cli.mdc +14 -7
package/README.md
CHANGED
|
@@ -80,7 +80,7 @@ coauthor repurpose download <id> --out ./social # copy-ready files
|
|
|
80
80
|
coauthor share <id> --json # public read-only link
|
|
81
81
|
coauthor post-details show <id> --json # SEO title, meta description, slug, excerpt
|
|
82
82
|
coauthor post-details set <id> --seo-title "..." --json # exports use these as defaults
|
|
83
|
-
coauthor post-details set <id> --live-url https://example.com/post/ # where the post is live (--clear-live-url removes it)
|
|
83
|
+
coauthor post-details set <id> --live-url https://example.com/post/ # where the post is live (--clear-live-url removes it; --track-search "..." sets the search to track for a post without a target search)
|
|
84
84
|
coauthor draft get <id> --format markdown --frontmatter --json # markdown with YAML frontmatter
|
|
85
85
|
coauthor draft get <id> --format markdown --widgets embed --json # interactives as live iframes, for a site you control
|
|
86
86
|
coauthor export wordpress <id> --yes --json # creates a WordPress draft post (--slug to override)
|
package/dist/commands.js
CHANGED
|
@@ -747,6 +747,18 @@ function postSeoMessage(data) {
|
|
|
747
747
|
parts.push(`${count('fail')} missing`);
|
|
748
748
|
return `Targeting "${seo.keyword}": SEO checklist ${parts.join(', ')}. Details in data.seo.checks.`;
|
|
749
749
|
}
|
|
750
|
+
// Posts written without a target search are tracked by the monthly check through the live address and search on `tracking`.
|
|
751
|
+
function postTrackingMessage(data) {
|
|
752
|
+
const tracking = getResponseValue(data, 'tracking');
|
|
753
|
+
if (!tracking)
|
|
754
|
+
return '';
|
|
755
|
+
const url = typeof tracking.published_url === 'string' && tracking.published_url ? tracking.published_url : null;
|
|
756
|
+
const keyword = typeof tracking.tracking_keyword === 'string' && tracking.tracking_keyword ? tracking.tracking_keyword : null;
|
|
757
|
+
if (!url && !keyword)
|
|
758
|
+
return '';
|
|
759
|
+
const picked = tracking.tracking_keyword_source === 'ranked' || tracking.tracking_keyword_source === 'suggested' ? ' (picked by CoAuthor)' : '';
|
|
760
|
+
return ` Tracked by the monthly check: ${url ? `live at ${url}` : 'no live address yet'}; ${keyword ? `search "${keyword}"${picked}` : 'no search yet, the next check picks one'}.`;
|
|
761
|
+
}
|
|
750
762
|
async function runPostDetailsCommand(action, input, client) {
|
|
751
763
|
const projectId = requireProjectId(input);
|
|
752
764
|
const path = `projects/${encodeURIComponent(projectId)}/post-details`;
|
|
@@ -754,7 +766,7 @@ async function runPostDetailsCommand(action, input, client) {
|
|
|
754
766
|
const data = await client.request({ path });
|
|
755
767
|
const details = getResponseValue(data, 'post_details');
|
|
756
768
|
return details === null
|
|
757
|
-
? { ok: true, message:
|
|
769
|
+
? { ok: true, message: `This post has no post details. They are generated for drafts created after the feature launched.${postTrackingMessage(data)}`, data }
|
|
758
770
|
: { ok: true, message: postSeoMessage(data), data };
|
|
759
771
|
}
|
|
760
772
|
if (action === 'set') {
|
|
@@ -778,8 +790,21 @@ async function runPostDetailsCommand(action, input, client) {
|
|
|
778
790
|
else if (clearLiveUrl) {
|
|
779
791
|
body.published_url = null;
|
|
780
792
|
}
|
|
793
|
+
// The search a post written without a target search is tracked with. --clear-track-search has CoAuthor pick again at the next check.
|
|
794
|
+
const trackSearch = getString(input.values, 'track-search')?.trim();
|
|
795
|
+
const clearTrackSearch = getBoolean(input.values, 'clear-track-search');
|
|
796
|
+
if (clearTrackSearch && trackSearch !== undefined)
|
|
797
|
+
throw new Error('Pass either --track-search <search> or --clear-track-search, not both.');
|
|
798
|
+
if (trackSearch !== undefined) {
|
|
799
|
+
if (trackSearch.length < 1 || trackSearch.length > 120)
|
|
800
|
+
throw new Error('--track-search needs a search of 1 to 120 characters.');
|
|
801
|
+
body.tracking_keyword = trackSearch;
|
|
802
|
+
}
|
|
803
|
+
else if (clearTrackSearch) {
|
|
804
|
+
body.tracking_keyword = null;
|
|
805
|
+
}
|
|
781
806
|
if (Object.keys(body).length === 0) {
|
|
782
|
-
throw new Error('Usage: coauthor post-details set <projectId> [--seo-title "..."] [--description "..."] [--slug "..."] [--excerpt "..."] [--live-url <url> | --clear-live-url]');
|
|
807
|
+
throw new Error('Usage: coauthor post-details set <projectId> [--seo-title "..."] [--description "..."] [--slug "..."] [--excerpt "..."] [--live-url <url> | --clear-live-url] [--track-search <search> | --clear-track-search]');
|
|
783
808
|
}
|
|
784
809
|
return { ok: true, data: await client.request({ method: 'PATCH', path, body }) };
|
|
785
810
|
}
|
|
@@ -2384,6 +2409,19 @@ function resultChange(row, depth) {
|
|
|
2384
2409
|
default: return 'steady';
|
|
2385
2410
|
}
|
|
2386
2411
|
}
|
|
2412
|
+
// A post written without a target search carries `tracking: {keyword, source}`: who picked its search, and what the next check will use.
|
|
2413
|
+
function resultTrackingNote(row) {
|
|
2414
|
+
if (row.tracking === null || row.tracking === undefined)
|
|
2415
|
+
return '';
|
|
2416
|
+
const tracking = planRecord(row.tracking);
|
|
2417
|
+
const tracked = planString(tracking, 'keyword') ?? '';
|
|
2418
|
+
const reading = planString(row, 'keyword') ?? '';
|
|
2419
|
+
if (tracked === '')
|
|
2420
|
+
return ' · next check picks a new search';
|
|
2421
|
+
const picked = tracked === reading && (tracking.source === 'ranked' || tracking.source === 'suggested') ? ' (picked by CoAuthor)' : '';
|
|
2422
|
+
const next = tracked === reading ? '' : ` · next check uses "${tracked}"`;
|
|
2423
|
+
return `${picked}${next}`;
|
|
2424
|
+
}
|
|
2387
2425
|
function seoPlanCheckReason(check) {
|
|
2388
2426
|
if (!check || check.status === 'queued' || check.status === 'running')
|
|
2389
2427
|
return null;
|
|
@@ -2435,7 +2473,7 @@ function seoPlanResultsMessage(data) {
|
|
|
2435
2473
|
].filter(Boolean).join(' · '), '');
|
|
2436
2474
|
for (const row of rows) {
|
|
2437
2475
|
const position = typeof row.position === 'number' ? `#${row.position}` : '--';
|
|
2438
|
-
lines.push(` ${position.padEnd(4)} ${resultChange(row, depth).padEnd(16)} ${planString(row, 'title') ?? 'Untitled'} [search: ${planString(row, 'keyword') ?? ''}]`);
|
|
2476
|
+
lines.push(` ${position.padEnd(4)} ${resultChange(row, depth).padEnd(16)} ${planString(row, 'title') ?? 'Untitled'} [search: ${planString(row, 'keyword') ?? ''}${resultTrackingNote(row)}]`);
|
|
2439
2477
|
lines.push(` ${planString(row, 'tracked_url') ?? ''} (project ${planString(row, 'project_id') ?? ''})`);
|
|
2440
2478
|
const otherPage = planString(row, 'ranking_url');
|
|
2441
2479
|
if (row.movement === 'not_found' && otherPage)
|
|
@@ -2443,13 +2481,15 @@ function seoPlanResultsMessage(data) {
|
|
|
2443
2481
|
}
|
|
2444
2482
|
}
|
|
2445
2483
|
else {
|
|
2446
|
-
lines.push('No posts are tracked yet. A post is tracked once it has a
|
|
2484
|
+
lines.push('No posts are tracked yet. A post is tracked once it has a live address and a search to track.');
|
|
2447
2485
|
}
|
|
2448
2486
|
const missing = Array.isArray(view.missing_urls) ? view.missing_urls.map(planRecord) : [];
|
|
2449
2487
|
if (missing.length > 0) {
|
|
2450
2488
|
lines.push('', `${missing.length} ${missing.length === 1 ? 'post has' : 'posts have'} no live address yet, so ${missing.length === 1 ? 'it is' : 'they are'} not tracked. Set one with \`coauthor post-details set <project-id> --live-url <url>\`:`);
|
|
2451
|
-
for (const row of missing.slice(0, RESULT_ROWS_SHOWN))
|
|
2452
|
-
|
|
2489
|
+
for (const row of missing.slice(0, RESULT_ROWS_SHOWN)) {
|
|
2490
|
+
const search = row.needs_search === true ? 'no target search yet' : `search: ${planString(row, 'keyword') ?? ''}`;
|
|
2491
|
+
lines.push(` ${planString(row, 'project_id') ?? ''} ${planString(row, 'title') ?? 'Untitled'} [${search}]`);
|
|
2492
|
+
}
|
|
2453
2493
|
if (missing.length > RESULT_ROWS_SHOWN)
|
|
2454
2494
|
lines.push(` and ${missing.length - RESULT_ROWS_SHOWN} more (see --json data.missing_urls).`);
|
|
2455
2495
|
}
|
|
@@ -3605,7 +3645,7 @@ function commandHelp(command) {
|
|
|
3605
3645
|
'dismiss hides an idea from the plan; --undo brings it back.',
|
|
3606
3646
|
'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.',
|
|
3607
3647
|
'monthly-check on|off switches the plan\'s monthly check (free). Once a month it re-checks where each published post ranks on Google, refreshes the plan\'s ranking data and chances, and uses credits (the first check is free). show prints its state: enabled, next_check_at and about how many credits a month. It is absent while monthly checks are not switched on for the account. Turning it on picks the next date at least 25 days after the last check.',
|
|
3608
|
-
'results prints where each tracked post ranked at the last monthly check (position, change since the check before, live address; a post no check has read yet reads "checked next time"; when another page of the site ranks instead it prints that page), the posts
|
|
3648
|
+
'results prints where each tracked post ranked at the last monthly check (position, change since the check before, live address; a post no check has read yet reads "checked next time"; when another page of the site ranks instead it prints that page), the posts with no live address yet (except ones marked as still being edited; a post written without a target search reads "no target search yet" and gets one picked at the next check), and why the last check did less than a full job. --json returns data.results, data.missing_urls, data.last_check and data.monthly_check. Without monthly checks switched on for the account there are no results. A post is tracked once it has a live address and a search: set the address with `coauthor post-details set <project-id> --live-url <url>`. Posts written without a target search are tracked automatically (CoAuthor finds the live page and picks a search; results shows "(picked by CoAuthor)"); change the search with `post-details set <project-id> --track-search "<search>"`, and --json adds tracking to each row and needs_search to each missing post.',
|
|
3609
3649
|
'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.',
|
|
3610
3650
|
].join('\n'),
|
|
3611
3651
|
integrations: [
|
|
@@ -3738,12 +3778,13 @@ function commandHelp(command) {
|
|
|
3738
3778
|
].join('\n'),
|
|
3739
3779
|
'post-details': [
|
|
3740
3780
|
'Usage: coauthor post-details show <project-id> [--json]',
|
|
3741
|
-
' coauthor post-details set <project-id> [--seo-title "..."] [--description "..."] [--slug "..."] [--excerpt "..."] [--live-url <url> | --clear-live-url] [--json]',
|
|
3781
|
+
' coauthor post-details set <project-id> [--seo-title "..."] [--description "..."] [--slug "..."] [--excerpt "..."] [--live-url <url> | --clear-live-url] [--track-search <search> | --clear-track-search] [--json]',
|
|
3742
3782
|
'',
|
|
3743
3783
|
'Post details are the SEO title, meta description, slug and excerpt CoAuthor writes after a draft. Exports use them as defaults.',
|
|
3744
3784
|
'set changes only the fields you pass; an empty value clears a field. Edited fields are kept when the draft is regenerated.',
|
|
3745
3785
|
'The live URL is where the post is published. show returns published_url and published_url_source (export, manual, auto_detect or cleared). --live-url sets it by hand (an http or https address) and wins over later exports; --clear-live-url removes it, and CoAuthor then does not look for it again.',
|
|
3746
|
-
'Posts drafted before
|
|
3786
|
+
'Posts written without a target search (mostly drafted before SEO mode) are tracked by the monthly check anyway: CoAuthor finds the live page and picks a search. show returns tracking (published_url, published_url_source, tracking_keyword, tracking_keyword_source: ranked or suggested = CoAuthor picked it, manual = you did). --track-search sets the search to track (1 to 120 characters; wins over later picks); --clear-track-search has CoAuthor pick again at the next check. To stop tracking such a post, use --clear-live-url. --track-search is for posts without a target search (a post with one answers post_has_target_search).',
|
|
3787
|
+
'Posts drafted before post details launched have no SEO fields (show returns post_details: null; setting SEO fields returns post_details_unavailable), but --live-url, --clear-live-url and --track-search still work for them.',
|
|
3747
3788
|
'SEO posts also return seo: the target keyword, market, SEO research credits and a checklist computed from the current draft (pass, warn, fail or skip per check).',
|
|
3748
3789
|
].join('\n'),
|
|
3749
3790
|
share: [
|
package/dist/parser.js
CHANGED
|
@@ -56,6 +56,8 @@ const OPTIONS = {
|
|
|
56
56
|
'seo-title': { type: 'string' },
|
|
57
57
|
'live-url': { type: 'string' },
|
|
58
58
|
'clear-live-url': { type: 'boolean', default: false },
|
|
59
|
+
'track-search': { type: 'string' },
|
|
60
|
+
'clear-track-search': { type: 'boolean', default: false },
|
|
59
61
|
keyword: { type: 'string' },
|
|
60
62
|
seo: { type: 'string' },
|
|
61
63
|
'confirm-reset': { type: 'boolean', default: false },
|
package/package.json
CHANGED
package/skills/coauthor/SKILL.md
CHANGED
|
@@ -71,7 +71,7 @@ When the user wants to know what to write about for a business site, or asks for
|
|
|
71
71
|
- `coauthor seo-plan dismiss <item-id> [--undo] --json` hides an idea the user rules out.
|
|
72
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.
|
|
73
73
|
- `coauthor seo-plan monthly-check on|off --json` switches the plan's monthly check, which re-checks where each published post ranks on Google and refreshes the plan's chances. It uses credits (about 30 a month; the first check is free). `show` returns `data.monthly_check` (`enabled`, `next_check_at`, `estimate_credits`), or `null` while it is not switched on for the account.
|
|
74
|
-
- `coauthor seo-plan results --json` reads the last monthly check: where each tracked post ranks on Google (`data.results`: `position`, `previous_position`, `movement`, `ranking_url`), the posts
|
|
74
|
+
- `coauthor seo-plan results --json` reads the last monthly check: where each tracked post ranks on Google (`data.results`: `position`, `previous_position`, `movement`, `ranking_url`), the posts with no live address yet, except ones marked as still being edited (`data.missing_urls`), and how the check went (`data.last_check`). Posts without a live address are not tracked; set one with `coauthor post-details set <id> --live-url <url>`. Posts written without a target search are tracked automatically (CoAuthor finds the live page and picks a search, shown in `tracking`); set or change the search with `post-details set <id> --track-search "<search>"`.
|
|
75
75
|
|
|
76
76
|
Details, item fields, and what each kind means: `references/seo-content-plan.md`. If a command answers `not_enabled`, SEO content plans are not switched on for this account; carry on without a plan.
|
|
77
77
|
|
|
@@ -23,12 +23,16 @@ coauthor post-details show <id> --json # data.post_details (null for drafts ma
|
|
|
23
23
|
coauthor post-details set <id> --seo-title "..." --description "..." --slug "..." --excerpt "..." --json
|
|
24
24
|
coauthor post-details set <id> --live-url https://example.com/my-post/ --json # where the post is live
|
|
25
25
|
coauthor post-details set <id> --clear-live-url --json
|
|
26
|
+
coauthor post-details set <id> --track-search "welcome email examples" --json # posts written without a target search: the search to track
|
|
27
|
+
coauthor post-details set <id> --clear-track-search --json # CoAuthor picks the search again at the next check
|
|
26
28
|
```
|
|
27
29
|
|
|
28
|
-
`set` changes only the fields you pass; an empty value clears one. Fields the user or you edited are kept when the draft is regenerated. Keep the SEO title near 60 characters and the description near 155. `post_details_unavailable` means the draft predates post details.
|
|
30
|
+
`set` changes only the fields you pass; an empty value clears one. Fields the user or you edited are kept when the draft is regenerated. Keep the SEO title near 60 characters and the description near 155. `post_details_unavailable` means the draft predates post details and you tried to change an SEO field.
|
|
29
31
|
|
|
30
32
|
The live URL is where the post is published. `post_details.published_url` holds it (null until it is known) and `published_url_source` says where it came from: `export` (an export reported the post live, or a WordPress post the user published afterwards), `manual` (set with `--live-url` or in the app), `auto_detect` (CoAuthor found the page on the user's site) or `cleared` (removed on purpose). Set it when the user tells you where a post went live. A URL set by hand wins over later exports, and `--clear-live-url` removes it so CoAuthor does not look for it again. It must be an `http` or `https` address, and it is not one of the four SEO fields, so it never counts as an edited field.
|
|
31
33
|
|
|
34
|
+
Posts written without a target search (mostly drafted before SEO mode, many with no post details at all) are still tracked by the monthly check: CoAuthor finds the live page and picks a search to track. `post-details show` returns `data.tracking`: `{published_url, published_url_source, tracking_keyword, tracking_keyword_source}`, the live address and search used for tracking (post details first, then CoAuthor's own record), where `tracking_keyword_source` is `ranked` or `suggested` (CoAuthor picked it), `manual` (set with `--track-search`) or `null`. `--live-url` and `--clear-live-url` work for these posts even without post details. `--track-search` sets the search (1 to 120 characters, kept over later picks; changing the address makes CoAuthor pick again unless you set the search by hand) and `--clear-track-search` asks for a new pick at the next check. `--clear-live-url` stops tracking the post. A post that has a target search of its own answers `post_has_target_search`: its tracked search is that one.
|
|
35
|
+
|
|
32
36
|
For SEO posts on a profile with a website, `post_details.incoming_link_suggestions` lists existing pages on the user's site that could link to the new post: `{status, suggestions: [{url, title, anchor, sentence}]}`. `status` is `ready`, `none`, or `index_not_ready` (the site was still being indexed when the draft was written; links appear on the next post). It is read-only. After the post is published, offer the user the sentences to add on those pages, linking the anchor text to the new post's URL. It is `null` for other posts.
|
|
33
37
|
|
|
34
38
|
For SEO posts, `post-details show` also returns `seo`: the target `keyword`, its `market`, `seo_research_credits`, and a `checks` list computed from the current draft and title. Each check has an `id`, a `status` (`pass`, `warn`, `fail`, or `skip` when there is nothing to measure) and a plain `detail`. The ids are `keyword_in_title`, `keyword_in_intro` (first 100 words), `secondary_in_h2`, `table_stakes`, `angle_section`, `questions_answered`, `internal_link`, `outbound_sources` and `length`. A `fail` on the title is worth fixing before publishing: edit it with `project rename`. A `warn` on `keyword_in_intro` is fine when the keyword wouldn't read naturally in the opening, so don't force it in. `secondary_in_h2` and `questions_answered` are optional: they report `pass` or `skip`, never `warn`. `seo` is `null` for other posts.
|
|
@@ -80,18 +80,20 @@ Errors: `plan_stale` (the profile's website or market changed; run `generate` to
|
|
|
80
80
|
|
|
81
81
|
## Monthly check
|
|
82
82
|
|
|
83
|
-
Once a month CoAuthor looks up where each published post (one with a
|
|
83
|
+
Once a month CoAuthor looks up where each published post (one with a search to track and a live URL) ranks on Google, refreshes the plan's ranking data and the chance of its top ideas, and records the result. It uses credits, about 30 a month, and the account's first check is free. It is on by default for a plan.
|
|
84
84
|
|
|
85
85
|
`coauthor seo-plan monthly-check on|off [--profile <id>] --json` switches it for that profile's plan and returns `data.enabled` and `data.next_check_at` (`null` when off). Turning it on picks the next date at least 25 days after the last check, so switching does not buy an early check. `show` returns `data.monthly_check` with `enabled`, `next_check_at`, `last_check_at`, `estimate_credits` and `first_check_free`; it is `null` while monthly checks are not switched on for the account, and then there is nothing to switch. Do not turn it off on your own judgment: it is what keeps the plan's rankings and chances current. Errors: `not_enabled`, `profile_not_found`, `plan_not_found` (make the plan first), `invalid_input`.
|
|
86
86
|
|
|
87
87
|
Posts are only tracked once their live URL is known: set it with `coauthor post-details set <id> --live-url <url>` (see `references/publishing-and-export.md`).
|
|
88
88
|
|
|
89
|
+
Posts written without a target search (mostly drafted before SEO mode) are tracked automatically: CoAuthor finds the live page on the site and picks a search for it, and tracking starts at once. The pick is shown in the results so the user can change it, and it costs about one credit more per month for each extra tracked search. Set or change the search with `coauthor post-details set <id> --track-search "<search>"` (`--clear-track-search` has CoAuthor pick again at the next check), and stop tracking a post with `--clear-live-url`. A post whose live page is not found yet shows under `data.missing_urls` with `needs_search: true`; give it an address (and optionally a search) the same way.
|
|
90
|
+
|
|
89
91
|
### Results
|
|
90
92
|
|
|
91
93
|
`coauthor seo-plan results [--profile <id>] --json` shows what the last monthly check found; the human output is a short list. The same fields come back from `show` (`data.results`, `data.missing_urls`, `data.last_check`, `data.monthly_check`).
|
|
92
94
|
|
|
93
|
-
- `data.results` has one row per tracked post (a live address and a
|
|
94
|
-
- `data.missing_urls` lists posts that have
|
|
95
|
+
- `data.results` has one row per tracked post (a live address and a search), best news first (moved up, then page one by position, then the rest, then posts no check has read yet): `project_id`, `title`, `keyword`, `tracked_url`, `position`, `previous_position`, `movement`, `ranking_url`, `checked_at` and `tracking`. `tracking` is `null` for a post written for a target search; for a post written without one it is `{keyword, source}`: the search tracked now (`keyword` is `""` while the next check will pick one; it can differ from the row's `keyword`, which is what the last reading used) and who chose it (`source`: `ranked` or `suggested` = CoAuthor picked it, `manual` = the user did, `null` = not picked yet). `position` is Google's organic position; page one means 10 or better. It is `null` when the post's address is not within the top results the check looked at (`data.last_check.depth`, 30 by default), and `movement` is then `not_found`; if `ranking_url` is set, another page of the same site ranks for that search instead, which is worth telling the user. `movement` is `up` or `down` only for a move of 3 places or more, or a move onto or off page one; `same` is steady; `new` means the first reading of that search and address, so there is nothing to compare with yet; `pending` means the post went live after the last check and has no reading yet (`position` and `checked_at` are `null`; the next check reads it).
|
|
96
|
+
- `data.missing_urls` lists posts that have no live address (`project_id`, `title`, `keyword`, `needs_search`, `publication_status`: `needs_search` is `true`, with `keyword` `""`, for a post written without a target search that has no search to track yet, so the next check picks one; `publication_status`: `published`, `submitted`, or `null` when nobody marked the post); only posts explicitly marked as still being edited are left out. Most posts are unmarked, so a `null` post may not be live yet: ask the user before setting an address. They are not tracked until you set one with `coauthor post-details set <project-id> --live-url <url>` (add `--track-search "<search>"` to choose the search for a post without a target search); the next check picks it up.
|
|
95
97
|
- `data.last_check` is `{status, finished_at, partial, partial_reason, plan_refresh_skipped, error_code, credits_charged, free, depth}`. `partial` means the check stopped early (for example credits ran out); `plan_refresh_skipped` (`stale` or `failed`) means the plan's own chances were not refreshed because the plan needs updating, so run `coauthor seo-plan generate`. `status` `skipped` with `error_code` `insufficient_credits` means the account had too few credits and nothing was spent.
|
|
96
98
|
- Everything is empty or `null` while monthly checks are not switched on for the account, and before the first check has run.
|
|
97
99
|
|
|
@@ -49,8 +49,9 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
49
49
|
| `invalid_keyword` | The keyword is empty or longer than 200 characters. | Pass a plain search phrase. |
|
|
50
50
|
| `invalid_seo_mode` | `--seo` or `set-mode` got something other than `optimize`, `my-way` or `off`, or `--seo off` was combined with `--keyword`. | Pass one of the three modes; drop `--keyword` with `off`. |
|
|
51
51
|
| `no_search_target` | `search-brief set-mode optimize` or `my-way` on a project with no target keyword. | Set one with `search-brief set-keyword`, or let the outline pick one. |
|
|
52
|
-
| `post_details_unavailable` | The draft was made before post details launched, so it has
|
|
53
|
-
| `invalid_post_details` | `post-details set` got something other than text for a field,
|
|
52
|
+
| `post_details_unavailable` | The draft was made before post details launched, so it has no SEO fields to edit (`--live-url` and `--track-search` still work). | Pass the slug and description to the export directly. |
|
|
53
|
+
| `invalid_post_details` | `post-details set` got something other than text for a field, a live URL that is not an `http` or `https` address, or a `--track-search` that is empty or over 120 characters. | Pass plain text with `--seo-title`, `--description`, `--slug`, or `--excerpt`, a full address with `--live-url`, and a search of 1 to 120 characters with `--track-search`. |
|
|
54
|
+
| `post_has_target_search` | `post-details set --track-search` on a post that was written for a target search. | Nothing to do: that post is tracked with its target search. Change it with `search-brief set-keyword` if the user wants another. |
|
|
54
55
|
| `structured_brief` | `image generate --prompt` on a comparison or technical-diagram image, which is built from structured fields. | Generate without `--prompt`, then `image edit --edit-prompt "..."`. |
|
|
55
56
|
| `uploaded_image` | `image generate` on an image the user replaced with their own file. | Use `image edit --edit-prompt "..."`, or `image replace` again. |
|
|
56
57
|
| `not_a_panel` | `image replace` on an article image. | Only slideshow and video panels can be replaced from the CLI. |
|
|
@@ -73,7 +73,7 @@ When the user wants to know what to write about for a business site, or asks for
|
|
|
73
73
|
- `coauthor seo-plan dismiss <item-id> [--undo] --json` hides an idea the user rules out.
|
|
74
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.
|
|
75
75
|
- `coauthor seo-plan monthly-check on|off --json` switches the plan's monthly check, which re-checks where each published post ranks on Google and refreshes the plan's chances. It uses credits (about 30 a month; the first check is free). `show` returns `data.monthly_check` (`enabled`, `next_check_at`, `estimate_credits`), or `null` while it is not switched on for the account.
|
|
76
|
-
- `coauthor seo-plan results --json` reads the last monthly check: where each tracked post ranks on Google (`data.results`: `position`, `previous_position`, `movement`, `ranking_url`), the posts
|
|
76
|
+
- `coauthor seo-plan results --json` reads the last monthly check: where each tracked post ranks on Google (`data.results`: `position`, `previous_position`, `movement`, `ranking_url`), the posts with no live address yet, except ones marked as still being edited (`data.missing_urls`), and how the check went (`data.last_check`). Posts without a live address are not tracked; set one with `coauthor post-details set <id> --live-url <url>`. Posts written without a target search are tracked automatically (CoAuthor finds the live page and picks a search, shown in `tracking`); set or change the search with `post-details set <id> --track-search "<search>"`.
|
|
77
77
|
|
|
78
78
|
Details, item fields, and what each kind means: `references/seo-content-plan.md`. If a command answers `not_enabled`, SEO content plans are not switched on for this account; carry on without a plan.
|
|
79
79
|
|
|
@@ -466,12 +466,16 @@ coauthor post-details show <id> --json # data.post_details (null for drafts ma
|
|
|
466
466
|
coauthor post-details set <id> --seo-title "..." --description "..." --slug "..." --excerpt "..." --json
|
|
467
467
|
coauthor post-details set <id> --live-url https://example.com/my-post/ --json # where the post is live
|
|
468
468
|
coauthor post-details set <id> --clear-live-url --json
|
|
469
|
+
coauthor post-details set <id> --track-search "welcome email examples" --json # posts written without a target search: the search to track
|
|
470
|
+
coauthor post-details set <id> --clear-track-search --json # CoAuthor picks the search again at the next check
|
|
469
471
|
```
|
|
470
472
|
|
|
471
|
-
`set` changes only the fields you pass; an empty value clears one. Fields the user or you edited are kept when the draft is regenerated. Keep the SEO title near 60 characters and the description near 155. `post_details_unavailable` means the draft predates post details.
|
|
473
|
+
`set` changes only the fields you pass; an empty value clears one. Fields the user or you edited are kept when the draft is regenerated. Keep the SEO title near 60 characters and the description near 155. `post_details_unavailable` means the draft predates post details and you tried to change an SEO field.
|
|
472
474
|
|
|
473
475
|
The live URL is where the post is published. `post_details.published_url` holds it (null until it is known) and `published_url_source` says where it came from: `export` (an export reported the post live, or a WordPress post the user published afterwards), `manual` (set with `--live-url` or in the app), `auto_detect` (CoAuthor found the page on the user's site) or `cleared` (removed on purpose). Set it when the user tells you where a post went live. A URL set by hand wins over later exports, and `--clear-live-url` removes it so CoAuthor does not look for it again. It must be an `http` or `https` address, and it is not one of the four SEO fields, so it never counts as an edited field.
|
|
474
476
|
|
|
477
|
+
Posts written without a target search (mostly drafted before SEO mode, many with no post details at all) are still tracked by the monthly check: CoAuthor finds the live page and picks a search to track. `post-details show` returns `data.tracking`: `{published_url, published_url_source, tracking_keyword, tracking_keyword_source}`, the live address and search used for tracking (post details first, then CoAuthor's own record), where `tracking_keyword_source` is `ranked` or `suggested` (CoAuthor picked it), `manual` (set with `--track-search`) or `null`. `--live-url` and `--clear-live-url` work for these posts even without post details. `--track-search` sets the search (1 to 120 characters, kept over later picks; changing the address makes CoAuthor pick again unless you set the search by hand) and `--clear-track-search` asks for a new pick at the next check. `--clear-live-url` stops tracking the post. A post that has a target search of its own answers `post_has_target_search`: its tracked search is that one.
|
|
478
|
+
|
|
475
479
|
For SEO posts on a profile with a website, `post_details.incoming_link_suggestions` lists existing pages on the user's site that could link to the new post: `{status, suggestions: [{url, title, anchor, sentence}]}`. `status` is `ready`, `none`, or `index_not_ready` (the site was still being indexed when the draft was written; links appear on the next post). It is read-only. After the post is published, offer the user the sentences to add on those pages, linking the anchor text to the new post's URL. It is `null` for other posts.
|
|
476
480
|
|
|
477
481
|
For SEO posts, `post-details show` also returns `seo`: the target `keyword`, its `market`, `seo_research_credits`, and a `checks` list computed from the current draft and title. Each check has an `id`, a `status` (`pass`, `warn`, `fail`, or `skip` when there is nothing to measure) and a plain `detail`. The ids are `keyword_in_title`, `keyword_in_intro` (first 100 words), `secondary_in_h2`, `table_stakes`, `angle_section`, `questions_answered`, `internal_link`, `outbound_sources` and `length`. A `fail` on the title is worth fixing before publishing: edit it with `project rename`. A `warn` on `keyword_in_intro` is fine when the keyword wouldn't read naturally in the opening, so don't force it in. `secondary_in_h2` and `questions_answered` are optional: they report `pass` or `skip`, never `warn`. `seo` is `null` for other posts.
|
|
@@ -670,18 +674,20 @@ Errors: `plan_stale` (the profile's website or market changed; run `generate` to
|
|
|
670
674
|
|
|
671
675
|
### Monthly check
|
|
672
676
|
|
|
673
|
-
Once a month CoAuthor looks up where each published post (one with a
|
|
677
|
+
Once a month CoAuthor looks up where each published post (one with a search to track and a live URL) ranks on Google, refreshes the plan's ranking data and the chance of its top ideas, and records the result. It uses credits, about 30 a month, and the account's first check is free. It is on by default for a plan.
|
|
674
678
|
|
|
675
679
|
`coauthor seo-plan monthly-check on|off [--profile <id>] --json` switches it for that profile's plan and returns `data.enabled` and `data.next_check_at` (`null` when off). Turning it on picks the next date at least 25 days after the last check, so switching does not buy an early check. `show` returns `data.monthly_check` with `enabled`, `next_check_at`, `last_check_at`, `estimate_credits` and `first_check_free`; it is `null` while monthly checks are not switched on for the account, and then there is nothing to switch. Do not turn it off on your own judgment: it is what keeps the plan's rankings and chances current. Errors: `not_enabled`, `profile_not_found`, `plan_not_found` (make the plan first), `invalid_input`.
|
|
676
680
|
|
|
677
681
|
Posts are only tracked once their live URL is known: set it with `coauthor post-details set <id> --live-url <url>` (see `references/publishing-and-export.md`).
|
|
678
682
|
|
|
683
|
+
Posts written without a target search (mostly drafted before SEO mode) are tracked automatically: CoAuthor finds the live page on the site and picks a search for it, and tracking starts at once. The pick is shown in the results so the user can change it, and it costs about one credit more per month for each extra tracked search. Set or change the search with `coauthor post-details set <id> --track-search "<search>"` (`--clear-track-search` has CoAuthor pick again at the next check), and stop tracking a post with `--clear-live-url`. A post whose live page is not found yet shows under `data.missing_urls` with `needs_search: true`; give it an address (and optionally a search) the same way.
|
|
684
|
+
|
|
679
685
|
#### Results
|
|
680
686
|
|
|
681
687
|
`coauthor seo-plan results [--profile <id>] --json` shows what the last monthly check found; the human output is a short list. The same fields come back from `show` (`data.results`, `data.missing_urls`, `data.last_check`, `data.monthly_check`).
|
|
682
688
|
|
|
683
|
-
- `data.results` has one row per tracked post (a live address and a
|
|
684
|
-
- `data.missing_urls` lists posts that have
|
|
689
|
+
- `data.results` has one row per tracked post (a live address and a search), best news first (moved up, then page one by position, then the rest, then posts no check has read yet): `project_id`, `title`, `keyword`, `tracked_url`, `position`, `previous_position`, `movement`, `ranking_url`, `checked_at` and `tracking`. `tracking` is `null` for a post written for a target search; for a post written without one it is `{keyword, source}`: the search tracked now (`keyword` is `""` while the next check will pick one; it can differ from the row's `keyword`, which is what the last reading used) and who chose it (`source`: `ranked` or `suggested` = CoAuthor picked it, `manual` = the user did, `null` = not picked yet). `position` is Google's organic position; page one means 10 or better. It is `null` when the post's address is not within the top results the check looked at (`data.last_check.depth`, 30 by default), and `movement` is then `not_found`; if `ranking_url` is set, another page of the same site ranks for that search instead, which is worth telling the user. `movement` is `up` or `down` only for a move of 3 places or more, or a move onto or off page one; `same` is steady; `new` means the first reading of that search and address, so there is nothing to compare with yet; `pending` means the post went live after the last check and has no reading yet (`position` and `checked_at` are `null`; the next check reads it).
|
|
690
|
+
- `data.missing_urls` lists posts that have no live address (`project_id`, `title`, `keyword`, `needs_search`, `publication_status`: `needs_search` is `true`, with `keyword` `""`, for a post written without a target search that has no search to track yet, so the next check picks one; `publication_status`: `published`, `submitted`, or `null` when nobody marked the post); only posts explicitly marked as still being edited are left out. Most posts are unmarked, so a `null` post may not be live yet: ask the user before setting an address. They are not tracked until you set one with `coauthor post-details set <project-id> --live-url <url>` (add `--track-search "<search>"` to choose the search for a post without a target search); the next check picks it up.
|
|
685
691
|
- `data.last_check` is `{status, finished_at, partial, partial_reason, plan_refresh_skipped, error_code, credits_charged, free, depth}`. `partial` means the check stopped early (for example credits ran out); `plan_refresh_skipped` (`stale` or `failed`) means the plan's own chances were not refreshed because the plan needs updating, so run `coauthor seo-plan generate`. `status` `skipped` with `error_code` `insufficient_credits` means the account had too few credits and nothing was spent.
|
|
686
692
|
- Everything is empty or `null` while monthly checks are not switched on for the account, and before the first check has run.
|
|
687
693
|
|
|
@@ -744,8 +750,9 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
744
750
|
| `invalid_keyword` | The keyword is empty or longer than 200 characters. | Pass a plain search phrase. |
|
|
745
751
|
| `invalid_seo_mode` | `--seo` or `set-mode` got something other than `optimize`, `my-way` or `off`, or `--seo off` was combined with `--keyword`. | Pass one of the three modes; drop `--keyword` with `off`. |
|
|
746
752
|
| `no_search_target` | `search-brief set-mode optimize` or `my-way` on a project with no target keyword. | Set one with `search-brief set-keyword`, or let the outline pick one. |
|
|
747
|
-
| `post_details_unavailable` | The draft was made before post details launched, so it has
|
|
748
|
-
| `invalid_post_details` | `post-details set` got something other than text for a field,
|
|
753
|
+
| `post_details_unavailable` | The draft was made before post details launched, so it has no SEO fields to edit (`--live-url` and `--track-search` still work). | Pass the slug and description to the export directly. |
|
|
754
|
+
| `invalid_post_details` | `post-details set` got something other than text for a field, a live URL that is not an `http` or `https` address, or a `--track-search` that is empty or over 120 characters. | Pass plain text with `--seo-title`, `--description`, `--slug`, or `--excerpt`, a full address with `--live-url`, and a search of 1 to 120 characters with `--track-search`. |
|
|
755
|
+
| `post_has_target_search` | `post-details set --track-search` on a post that was written for a target search. | Nothing to do: that post is tracked with its target search. Change it with `search-brief set-keyword` if the user wants another. |
|
|
749
756
|
| `structured_brief` | `image generate --prompt` on a comparison or technical-diagram image, which is built from structured fields. | Generate without `--prompt`, then `image edit --edit-prompt "..."`. |
|
|
750
757
|
| `uploaded_image` | `image generate` on an image the user replaced with their own file. | Use `image edit --edit-prompt "..."`, or `image replace` again. |
|
|
751
758
|
| `not_a_panel` | `image replace` on an article image. | Only slideshow and video panels can be replaced from the CLI. |
|