@clickminded/coauthor-cli 0.0.68 → 0.0.70
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 +53 -9
- package/dist/parser.js +2 -0
- package/package.json +1 -1
- package/skills/coauthor/SKILL.md +1 -1
- package/skills/coauthor/references/interactive-widgets.md +2 -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 +16 -8
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
|
}
|
|
@@ -1944,6 +1969,7 @@ async function runProfileCommand(action, input, client) {
|
|
|
1944
1969
|
throw new Error('Usage: coauthor profile <list|show|update>');
|
|
1945
1970
|
}
|
|
1946
1971
|
const WIDGET_EDIT_INSTRUCTION_MAX_CHARS = 500;
|
|
1972
|
+
const WIDGET_SCENE_NOTICE_TEXT = 'Add an OpenAI key in AI settings to get illustrated interactives.';
|
|
1947
1973
|
function widgetList(data) {
|
|
1948
1974
|
const value = getResponseValue(data, 'widgets');
|
|
1949
1975
|
return Array.isArray(value)
|
|
@@ -1990,6 +2016,8 @@ function describeWidget(widget, options = {}) {
|
|
|
1990
2016
|
}
|
|
1991
2017
|
if (widget.fact_check_warning)
|
|
1992
2018
|
lines.push(` fact check: ${String(widget.fact_check_warning)}`);
|
|
2019
|
+
if (widget.scene_notice === 'byok_no_openai_key')
|
|
2020
|
+
lines.push(` ${WIDGET_SCENE_NOTICE_TEXT}`);
|
|
1993
2021
|
const error = widgetError(widget);
|
|
1994
2022
|
if (error)
|
|
1995
2023
|
lines.push(` error: ${String(error.code)}: ${String(error.message)}`);
|
|
@@ -2384,6 +2412,19 @@ function resultChange(row, depth) {
|
|
|
2384
2412
|
default: return 'steady';
|
|
2385
2413
|
}
|
|
2386
2414
|
}
|
|
2415
|
+
// A post written without a target search carries `tracking: {keyword, source}`: who picked its search, and what the next check will use.
|
|
2416
|
+
function resultTrackingNote(row) {
|
|
2417
|
+
if (row.tracking === null || row.tracking === undefined)
|
|
2418
|
+
return '';
|
|
2419
|
+
const tracking = planRecord(row.tracking);
|
|
2420
|
+
const tracked = planString(tracking, 'keyword') ?? '';
|
|
2421
|
+
const reading = planString(row, 'keyword') ?? '';
|
|
2422
|
+
if (tracked === '')
|
|
2423
|
+
return ' · next check picks a new search';
|
|
2424
|
+
const picked = tracked === reading && (tracking.source === 'ranked' || tracking.source === 'suggested') ? ' (picked by CoAuthor)' : '';
|
|
2425
|
+
const next = tracked === reading ? '' : ` · next check uses "${tracked}"`;
|
|
2426
|
+
return `${picked}${next}`;
|
|
2427
|
+
}
|
|
2387
2428
|
function seoPlanCheckReason(check) {
|
|
2388
2429
|
if (!check || check.status === 'queued' || check.status === 'running')
|
|
2389
2430
|
return null;
|
|
@@ -2435,7 +2476,7 @@ function seoPlanResultsMessage(data) {
|
|
|
2435
2476
|
].filter(Boolean).join(' · '), '');
|
|
2436
2477
|
for (const row of rows) {
|
|
2437
2478
|
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') ?? ''}]`);
|
|
2479
|
+
lines.push(` ${position.padEnd(4)} ${resultChange(row, depth).padEnd(16)} ${planString(row, 'title') ?? 'Untitled'} [search: ${planString(row, 'keyword') ?? ''}${resultTrackingNote(row)}]`);
|
|
2439
2480
|
lines.push(` ${planString(row, 'tracked_url') ?? ''} (project ${planString(row, 'project_id') ?? ''})`);
|
|
2440
2481
|
const otherPage = planString(row, 'ranking_url');
|
|
2441
2482
|
if (row.movement === 'not_found' && otherPage)
|
|
@@ -2443,13 +2484,15 @@ function seoPlanResultsMessage(data) {
|
|
|
2443
2484
|
}
|
|
2444
2485
|
}
|
|
2445
2486
|
else {
|
|
2446
|
-
lines.push('No posts are tracked yet. A post is tracked once it has a
|
|
2487
|
+
lines.push('No posts are tracked yet. A post is tracked once it has a live address and a search to track.');
|
|
2447
2488
|
}
|
|
2448
2489
|
const missing = Array.isArray(view.missing_urls) ? view.missing_urls.map(planRecord) : [];
|
|
2449
2490
|
if (missing.length > 0) {
|
|
2450
2491
|
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
|
-
|
|
2492
|
+
for (const row of missing.slice(0, RESULT_ROWS_SHOWN)) {
|
|
2493
|
+
const search = row.needs_search === true ? 'no target search yet' : `search: ${planString(row, 'keyword') ?? ''}`;
|
|
2494
|
+
lines.push(` ${planString(row, 'project_id') ?? ''} ${planString(row, 'title') ?? 'Untitled'} [${search}]`);
|
|
2495
|
+
}
|
|
2453
2496
|
if (missing.length > RESULT_ROWS_SHOWN)
|
|
2454
2497
|
lines.push(` and ${missing.length - RESULT_ROWS_SHOWN} more (see --json data.missing_urls).`);
|
|
2455
2498
|
}
|
|
@@ -3605,7 +3648,7 @@ function commandHelp(command) {
|
|
|
3605
3648
|
'dismiss hides an idea from the plan; --undo brings it back.',
|
|
3606
3649
|
'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
3650
|
'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
|
|
3651
|
+
'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
3652
|
'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
3653
|
].join('\n'),
|
|
3611
3654
|
integrations: [
|
|
@@ -3738,12 +3781,13 @@ function commandHelp(command) {
|
|
|
3738
3781
|
].join('\n'),
|
|
3739
3782
|
'post-details': [
|
|
3740
3783
|
'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]',
|
|
3784
|
+
' 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
3785
|
'',
|
|
3743
3786
|
'Post details are the SEO title, meta description, slug and excerpt CoAuthor writes after a draft. Exports use them as defaults.',
|
|
3744
3787
|
'set changes only the fields you pass; an empty value clears a field. Edited fields are kept when the draft is regenerated.',
|
|
3745
3788
|
'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
|
|
3789
|
+
'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).',
|
|
3790
|
+
'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
3791
|
'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
3792
|
].join('\n'),
|
|
3749
3793
|
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,7 +23,7 @@ coauthor models preferences set --widget-model claude-opus-5-5|claude-sonnet-5-5
|
|
|
23
23
|
```
|
|
24
24
|
|
|
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
|
-
- `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
|
|
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 usually takes 1-4 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
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.
|
|
@@ -37,6 +37,7 @@ coauthor models preferences set --widget-model claude-opus-5-5|claude-sonnet-5-5
|
|
|
37
37
|
- **WordPress:** live embeds need a WordPress user who can post unfiltered HTML. Otherwise they export as images linked to the live version, and WordPress may strip embeds on save, which also falls back to the linked image.
|
|
38
38
|
- **Own API keys (Pro):** when included credits run low and the user builds with their own keys, interactives need an Anthropic API key (`widget_requires_anthropic_key`). They add it in CoAuthor's AI settings, never in chat.
|
|
39
39
|
- **Fact check:** a built widget may carry `fact_check_warning`. Show it to the user before publishing.
|
|
40
|
+
- **Illustrated interactives:** a built widget may carry `scene_notice: "byok_no_openai_key"` (null otherwise). It means the build used the user's own keys and has no OpenAI key, so the interactive was built without illustrations. Tell the user: Add an OpenAI key in AI settings to get illustrated interactives. They add it in CoAuthor's AI settings, never in chat.
|
|
40
41
|
- Interactives never appear in unbuilt form: placeholders are left out of every export.
|
|
41
42
|
|
|
42
43
|
Error codes: `references/troubleshooting.md`.
|
|
@@ -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
|
|
|
@@ -421,7 +421,7 @@ coauthor models preferences set --widget-model claude-opus-5-5|claude-sonnet-5-5
|
|
|
421
421
|
```
|
|
422
422
|
|
|
423
423
|
- `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"`.
|
|
424
|
-
- `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
|
|
424
|
+
- `build` and `edit` queue the build and return at once (`already_running: true` if it was already building: calling again is safe). A build usually takes 1-4 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.
|
|
425
425
|
- `build-all` with no ids builds every placeholder; with ids, only those.
|
|
426
426
|
- `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.
|
|
427
427
|
- `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.
|
|
@@ -435,6 +435,7 @@ coauthor models preferences set --widget-model claude-opus-5-5|claude-sonnet-5-5
|
|
|
435
435
|
- **WordPress:** live embeds need a WordPress user who can post unfiltered HTML. Otherwise they export as images linked to the live version, and WordPress may strip embeds on save, which also falls back to the linked image.
|
|
436
436
|
- **Own API keys (Pro):** when included credits run low and the user builds with their own keys, interactives need an Anthropic API key (`widget_requires_anthropic_key`). They add it in CoAuthor's AI settings, never in chat.
|
|
437
437
|
- **Fact check:** a built widget may carry `fact_check_warning`. Show it to the user before publishing.
|
|
438
|
+
- **Illustrated interactives:** a built widget may carry `scene_notice: "byok_no_openai_key"` (null otherwise). It means the build used the user's own keys and has no OpenAI key, so the interactive was built without illustrations. Tell the user: Add an OpenAI key in AI settings to get illustrated interactives. They add it in CoAuthor's AI settings, never in chat.
|
|
438
439
|
- Interactives never appear in unbuilt form: placeholders are left out of every export.
|
|
439
440
|
|
|
440
441
|
Error codes: `references/troubleshooting.md`.
|
|
@@ -466,12 +467,16 @@ coauthor post-details show <id> --json # data.post_details (null for drafts ma
|
|
|
466
467
|
coauthor post-details set <id> --seo-title "..." --description "..." --slug "..." --excerpt "..." --json
|
|
467
468
|
coauthor post-details set <id> --live-url https://example.com/my-post/ --json # where the post is live
|
|
468
469
|
coauthor post-details set <id> --clear-live-url --json
|
|
470
|
+
coauthor post-details set <id> --track-search "welcome email examples" --json # posts written without a target search: the search to track
|
|
471
|
+
coauthor post-details set <id> --clear-track-search --json # CoAuthor picks the search again at the next check
|
|
469
472
|
```
|
|
470
473
|
|
|
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.
|
|
474
|
+
`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
475
|
|
|
473
476
|
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
477
|
|
|
478
|
+
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.
|
|
479
|
+
|
|
475
480
|
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
481
|
|
|
477
482
|
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 +675,20 @@ Errors: `plan_stale` (the profile's website or market changed; run `generate` to
|
|
|
670
675
|
|
|
671
676
|
### Monthly check
|
|
672
677
|
|
|
673
|
-
Once a month CoAuthor looks up where each published post (one with a
|
|
678
|
+
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
679
|
|
|
675
680
|
`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
681
|
|
|
677
682
|
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
683
|
|
|
684
|
+
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.
|
|
685
|
+
|
|
679
686
|
#### Results
|
|
680
687
|
|
|
681
688
|
`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
689
|
|
|
683
|
-
- `data.results` has one row per tracked post (a live address and a
|
|
684
|
-
- `data.missing_urls` lists posts that have
|
|
690
|
+
- `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).
|
|
691
|
+
- `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
692
|
- `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
693
|
- Everything is empty or `null` while monthly checks are not switched on for the account, and before the first check has run.
|
|
687
694
|
|
|
@@ -744,8 +751,9 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
744
751
|
| `invalid_keyword` | The keyword is empty or longer than 200 characters. | Pass a plain search phrase. |
|
|
745
752
|
| `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
753
|
| `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,
|
|
754
|
+
| `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. |
|
|
755
|
+
| `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`. |
|
|
756
|
+
| `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
757
|
| `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
758
|
| `uploaded_image` | `image generate` on an image the user replaced with their own file. | Use `image edit --edit-prompt "..."`, or `image replace` again. |
|
|
751
759
|
| `not_a_panel` | `image replace` on an article image. | Only slideshow and video panels can be replaced from the CLI. |
|