@clickminded/coauthor-cli 0.0.67 → 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 +2 -1
- package/dist/commands.js +70 -15
- package/dist/parser.js +3 -0
- package/package.json +1 -1
- package/skills/coauthor/SKILL.md +1 -1
- package/skills/coauthor/references/interactive-widgets.md +3 -1
- package/skills/coauthor/references/publishing-and-export.md +6 -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 +18 -8
package/README.md
CHANGED
|
@@ -80,8 +80,9 @@ 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
|
+
coauthor draft get <id> --format markdown --widgets embed --json # interactives as live iframes, for a site you control
|
|
85
86
|
coauthor export wordpress <id> --yes --json # creates a WordPress draft post (--slug to override)
|
|
86
87
|
coauthor credits <id> --json
|
|
87
88
|
coauthor integrations list --json # WordPress sites and X accounts
|
package/dist/commands.js
CHANGED
|
@@ -631,11 +631,21 @@ async function runDraftCommand(action, input, context) {
|
|
|
631
631
|
if (frontmatter && format?.trim().toLowerCase() !== 'markdown') {
|
|
632
632
|
throw new Error('--frontmatter only applies to --format markdown.');
|
|
633
633
|
}
|
|
634
|
+
const widgets = getString(input.values, 'widgets')?.trim().toLowerCase();
|
|
635
|
+
if (widgets !== undefined) {
|
|
636
|
+
if (!['image', 'embed'].includes(widgets))
|
|
637
|
+
throw new Error(`--widgets must be image or embed (got "${widgets}").`);
|
|
638
|
+
if (!['markdown', 'html'].includes(format?.trim().toLowerCase() ?? '')) {
|
|
639
|
+
throw new Error('--widgets only applies to --format markdown or html.');
|
|
640
|
+
}
|
|
641
|
+
}
|
|
634
642
|
const query = new URLSearchParams();
|
|
635
643
|
if (format)
|
|
636
644
|
query.set('format', format);
|
|
637
645
|
if (frontmatter)
|
|
638
646
|
query.set('frontmatter', '1');
|
|
647
|
+
if (widgets)
|
|
648
|
+
query.set('widgets', widgets);
|
|
639
649
|
const suffix = query.toString();
|
|
640
650
|
const data = await client.request({ path: suffix ? `${basePath}/get?${suffix}` : `${basePath}/get` });
|
|
641
651
|
return { ok: true, data };
|
|
@@ -737,6 +747,18 @@ function postSeoMessage(data) {
|
|
|
737
747
|
parts.push(`${count('fail')} missing`);
|
|
738
748
|
return `Targeting "${seo.keyword}": SEO checklist ${parts.join(', ')}. Details in data.seo.checks.`;
|
|
739
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
|
+
}
|
|
740
762
|
async function runPostDetailsCommand(action, input, client) {
|
|
741
763
|
const projectId = requireProjectId(input);
|
|
742
764
|
const path = `projects/${encodeURIComponent(projectId)}/post-details`;
|
|
@@ -744,7 +766,7 @@ async function runPostDetailsCommand(action, input, client) {
|
|
|
744
766
|
const data = await client.request({ path });
|
|
745
767
|
const details = getResponseValue(data, 'post_details');
|
|
746
768
|
return details === null
|
|
747
|
-
? { 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 }
|
|
748
770
|
: { ok: true, message: postSeoMessage(data), data };
|
|
749
771
|
}
|
|
750
772
|
if (action === 'set') {
|
|
@@ -768,8 +790,21 @@ async function runPostDetailsCommand(action, input, client) {
|
|
|
768
790
|
else if (clearLiveUrl) {
|
|
769
791
|
body.published_url = null;
|
|
770
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
|
+
}
|
|
771
806
|
if (Object.keys(body).length === 0) {
|
|
772
|
-
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]');
|
|
773
808
|
}
|
|
774
809
|
return { ok: true, data: await client.request({ method: 'PATCH', path, body }) };
|
|
775
810
|
}
|
|
@@ -1964,7 +1999,7 @@ function widgetStateLabel(widget) {
|
|
|
1964
1999
|
function widgetSpec(widget) {
|
|
1965
2000
|
return widget.spec && typeof widget.spec === 'object' && !Array.isArray(widget.spec) ? widget.spec : {};
|
|
1966
2001
|
}
|
|
1967
|
-
function describeWidget(widget) {
|
|
2002
|
+
function describeWidget(widget, options = {}) {
|
|
1968
2003
|
const spec = widgetSpec(widget);
|
|
1969
2004
|
const lines = [
|
|
1970
2005
|
`${String(widget.id)} ${String(spec.title ?? '(untitled)')} [${widgetStateLabel(widget)}]`,
|
|
@@ -1975,6 +2010,9 @@ function describeWidget(widget) {
|
|
|
1975
2010
|
];
|
|
1976
2011
|
if (typeof widget.embed_url === 'string')
|
|
1977
2012
|
lines.push(` embed: ${widget.embed_url}`);
|
|
2013
|
+
if (options.embedCode && typeof widget.embed_code === 'string' && widget.embed_code) {
|
|
2014
|
+
lines.push(' embed code:', ...widget.embed_code.split('\n').map((line) => ` ${line}`));
|
|
2015
|
+
}
|
|
1978
2016
|
if (widget.fact_check_warning)
|
|
1979
2017
|
lines.push(` fact check: ${String(widget.fact_check_warning)}`);
|
|
1980
2018
|
const error = widgetError(widget);
|
|
@@ -1989,7 +2027,7 @@ function widgetsListMessage(data) {
|
|
|
1989
2027
|
}
|
|
1990
2028
|
const model = getResponseValue(data, 'model');
|
|
1991
2029
|
const placeholders = widgets.filter((widget) => widget.current_version == null && widget.build_state === 'idle').length;
|
|
1992
|
-
const lines = widgets.map(describeWidget);
|
|
2030
|
+
const lines = widgets.map((widget) => describeWidget(widget, { embedCode: true }));
|
|
1993
2031
|
if (model) {
|
|
1994
2032
|
lines.push('', `Build model: ${String(model.label ?? model.id)}. One build spends up to ${String(model.cap)} credits (an edit up to ${String(model.edit_cap)}).`);
|
|
1995
2033
|
}
|
|
@@ -2046,7 +2084,7 @@ function widgetsWaitResult(projectId, result, resumeCommand, doneWord) {
|
|
|
2046
2084
|
}
|
|
2047
2085
|
return {
|
|
2048
2086
|
ok: true,
|
|
2049
|
-
message: `${widgets.length} interactive${widgets.length === 1 ? '' : 's'} ${doneWord}.\n${widgets.map(describeWidget).join('\n')}`,
|
|
2087
|
+
message: `${widgets.length} interactive${widgets.length === 1 ? '' : 's'} ${doneWord}.\n${widgets.map((widget) => describeWidget(widget)).join('\n')}`,
|
|
2050
2088
|
messageIncludesData: true,
|
|
2051
2089
|
data,
|
|
2052
2090
|
};
|
|
@@ -2088,7 +2126,7 @@ async function runWidgetsCommand(action, input, client) {
|
|
|
2088
2126
|
const waited = await waitForWidgets(client, projectId, [id], [widget]);
|
|
2089
2127
|
return widgetsWaitResult(projectId, waited, `coauthor widgets status ${projectId} ${id} --wait`, 'ready');
|
|
2090
2128
|
}
|
|
2091
|
-
return { ok: true, message: widget ? describeWidget(widget) : undefined, messageIncludesData: Boolean(widget), data };
|
|
2129
|
+
return { ok: true, message: widget ? describeWidget(widget, { embedCode: true }) : undefined, messageIncludesData: Boolean(widget), data };
|
|
2092
2130
|
}
|
|
2093
2131
|
if (action === 'build') {
|
|
2094
2132
|
const id = needWidget('build');
|
|
@@ -2371,6 +2409,19 @@ function resultChange(row, depth) {
|
|
|
2371
2409
|
default: return 'steady';
|
|
2372
2410
|
}
|
|
2373
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
|
+
}
|
|
2374
2425
|
function seoPlanCheckReason(check) {
|
|
2375
2426
|
if (!check || check.status === 'queued' || check.status === 'running')
|
|
2376
2427
|
return null;
|
|
@@ -2422,7 +2473,7 @@ function seoPlanResultsMessage(data) {
|
|
|
2422
2473
|
].filter(Boolean).join(' · '), '');
|
|
2423
2474
|
for (const row of rows) {
|
|
2424
2475
|
const position = typeof row.position === 'number' ? `#${row.position}` : '--';
|
|
2425
|
-
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)}]`);
|
|
2426
2477
|
lines.push(` ${planString(row, 'tracked_url') ?? ''} (project ${planString(row, 'project_id') ?? ''})`);
|
|
2427
2478
|
const otherPage = planString(row, 'ranking_url');
|
|
2428
2479
|
if (row.movement === 'not_found' && otherPage)
|
|
@@ -2430,13 +2481,15 @@ function seoPlanResultsMessage(data) {
|
|
|
2430
2481
|
}
|
|
2431
2482
|
}
|
|
2432
2483
|
else {
|
|
2433
|
-
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.');
|
|
2434
2485
|
}
|
|
2435
2486
|
const missing = Array.isArray(view.missing_urls) ? view.missing_urls.map(planRecord) : [];
|
|
2436
2487
|
if (missing.length > 0) {
|
|
2437
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>\`:`);
|
|
2438
|
-
for (const row of missing.slice(0, RESULT_ROWS_SHOWN))
|
|
2439
|
-
|
|
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
|
+
}
|
|
2440
2493
|
if (missing.length > RESULT_ROWS_SHOWN)
|
|
2441
2494
|
lines.push(` and ${missing.length - RESULT_ROWS_SHOWN} more (see --json data.missing_urls).`);
|
|
2442
2495
|
}
|
|
@@ -3450,7 +3503,7 @@ export function helpResult(command = []) {
|
|
|
3450
3503
|
' research run|status|structured',
|
|
3451
3504
|
' draft generate|status|get|save|revise',
|
|
3452
3505
|
' draft revision show|apply|discard',
|
|
3453
|
-
' draft get supports --format json|markdown|html|text (--frontmatter adds post details to markdown)',
|
|
3506
|
+
' draft get supports --format json|markdown|html|text (--frontmatter adds post details to markdown; --widgets embed exports interactives as live iframes)',
|
|
3454
3507
|
' post-details show|set',
|
|
3455
3508
|
' seo markets [--country <country>] [--language <language>]',
|
|
3456
3509
|
' search-brief show|set-keyword|set-mode',
|
|
@@ -3541,10 +3594,11 @@ function commandHelp(command) {
|
|
|
3541
3594
|
'--widget-model (interactives beta) picks the model that builds interactives: claude-opus-5-5 (default) or claude-sonnet-5-5.',
|
|
3542
3595
|
].join('\n'),
|
|
3543
3596
|
'draft get': [
|
|
3544
|
-
'Usage: coauthor draft get <project-id> [--format json|markdown|html|text] [--frontmatter] [--json]',
|
|
3597
|
+
'Usage: coauthor draft get <project-id> [--format json|markdown|html|text] [--frontmatter] [--widgets image|embed] [--json]',
|
|
3545
3598
|
'',
|
|
3546
3599
|
'Retrieves a saved generated draft. Chat responses are available through coauthor chat show.',
|
|
3547
3600
|
'--frontmatter (markdown only) prepends YAML frontmatter from the post details: title, seo_title, description, slug, excerpt, and the featured image. Posts without post details get no frontmatter.',
|
|
3601
|
+
'--widgets (markdown or html only) chooses how built interactives export. image (default) is the linked poster image, safe for email and newsletters. embed is the live sandboxed iframe plus one embed.js script, for a website you control (Astro, Hugo, Next, custom HTML). In markdown the iframe is a raw HTML block that is also valid MDX.',
|
|
3548
3602
|
].join('\n'),
|
|
3549
3603
|
'draft save': [
|
|
3550
3604
|
'Usage: coauthor draft save <project-id> --data @payload.json [--force] [--json]',
|
|
@@ -3591,7 +3645,7 @@ function commandHelp(command) {
|
|
|
3591
3645
|
'dismiss hides an idea from the plan; --undo brings it back.',
|
|
3592
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.',
|
|
3593
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.',
|
|
3594
|
-
'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.',
|
|
3595
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.',
|
|
3596
3650
|
].join('\n'),
|
|
3597
3651
|
integrations: [
|
|
@@ -3724,12 +3778,13 @@ function commandHelp(command) {
|
|
|
3724
3778
|
].join('\n'),
|
|
3725
3779
|
'post-details': [
|
|
3726
3780
|
'Usage: coauthor post-details show <project-id> [--json]',
|
|
3727
|
-
' 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]',
|
|
3728
3782
|
'',
|
|
3729
3783
|
'Post details are the SEO title, meta description, slug and excerpt CoAuthor writes after a draft. Exports use them as defaults.',
|
|
3730
3784
|
'set changes only the fields you pass; an empty value clears a field. Edited fields are kept when the draft is regenerated.',
|
|
3731
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.',
|
|
3732
|
-
'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.',
|
|
3733
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).',
|
|
3734
3789
|
].join('\n'),
|
|
3735
3790
|
share: [
|
package/dist/parser.js
CHANGED
|
@@ -56,10 +56,13 @@ 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 },
|
|
62
64
|
frontmatter: { type: 'boolean', default: false },
|
|
65
|
+
widgets: { type: 'string' },
|
|
63
66
|
country: { type: 'string' },
|
|
64
67
|
language: { type: 'string' },
|
|
65
68
|
status: { type: 'string' },
|
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
|
|
|
@@ -27,7 +27,9 @@ coauthor models preferences set --widget-model claude-opus-5-5|claude-sonnet-5-5
|
|
|
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.
|
|
30
|
-
-
|
|
30
|
+
- `status` and `list` print an `embed code:` block for each built widget (an iframe plus the one `embed.js` script, ready to paste into any page) and return it as `embed_code` in the JSON.
|
|
31
|
+
- By default a built widget exports as its poster image linked to the live version in markdown and HTML (`draft get --format markdown`). Add `--widgets embed` to get the live sandboxed iframe instead: `coauthor draft get <id> --format markdown --widgets embed --json` (or `--format html`). Use `embed` when publishing to a website the user controls (Astro, Hugo, Next.js, plain HTML). Keep the default image form for email, newsletters, and anywhere that strips iframes. `--widgets` only applies to `--format markdown` and `html`; `--format text` stays the caption plus the link. WordPress export chooses automatically and ignores the flag.
|
|
32
|
+
- The markdown embed form is a raw HTML block (`<figure class="coauthor-widget"><iframe ...></iframe></figure>`) and one `<script src="https://figurehost.com/embed.js" async></script>` at the end of the document. The attributes are valid in plain Markdown and in MDX (no inline `style`, braces in captions escaped). If the site renders its own layout and already loads `embed.js` once, delete the trailing script line to avoid loading it twice. The iframe keeps its `sandbox="allow-scripts"` and resizes itself once `embed.js` runs.
|
|
31
33
|
|
|
32
34
|
## Limitations to tell the user
|
|
33
35
|
|
|
@@ -5,6 +5,7 @@
|
|
|
5
5
|
```sh
|
|
6
6
|
coauthor draft get <id> --format markdown --json # data.markdown, images as markdown image links
|
|
7
7
|
coauthor draft get <id> --format html --json # data.html, images as <img> tags
|
|
8
|
+
coauthor draft get <id> --format markdown --widgets embed --json # website you control: interactives as live iframes (see interactive-widgets.md)
|
|
8
9
|
coauthor draft get <id> --format text --json # data.text, plain text with image URLs
|
|
9
10
|
coauthor draft get <id> --format json --json # data.content, the editor document (for edits)
|
|
10
11
|
```
|
|
@@ -22,12 +23,16 @@ coauthor post-details show <id> --json # data.post_details (null for drafts ma
|
|
|
22
23
|
coauthor post-details set <id> --seo-title "..." --description "..." --slug "..." --excerpt "..." --json
|
|
23
24
|
coauthor post-details set <id> --live-url https://example.com/my-post/ --json # where the post is live
|
|
24
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
|
|
25
28
|
```
|
|
26
29
|
|
|
27
|
-
`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.
|
|
28
31
|
|
|
29
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.
|
|
30
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
|
+
|
|
31
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.
|
|
32
37
|
|
|
33
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
|
|
|
@@ -425,7 +425,9 @@ coauthor models preferences set --widget-model claude-opus-5-5|claude-sonnet-5-5
|
|
|
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.
|
|
428
|
-
-
|
|
428
|
+
- `status` and `list` print an `embed code:` block for each built widget (an iframe plus the one `embed.js` script, ready to paste into any page) and return it as `embed_code` in the JSON.
|
|
429
|
+
- By default a built widget exports as its poster image linked to the live version in markdown and HTML (`draft get --format markdown`). Add `--widgets embed` to get the live sandboxed iframe instead: `coauthor draft get <id> --format markdown --widgets embed --json` (or `--format html`). Use `embed` when publishing to a website the user controls (Astro, Hugo, Next.js, plain HTML). Keep the default image form for email, newsletters, and anywhere that strips iframes. `--widgets` only applies to `--format markdown` and `html`; `--format text` stays the caption plus the link. WordPress export chooses automatically and ignores the flag.
|
|
430
|
+
- The markdown embed form is a raw HTML block (`<figure class="coauthor-widget"><iframe ...></iframe></figure>`) and one `<script src="https://figurehost.com/embed.js" async></script>` at the end of the document. The attributes are valid in plain Markdown and in MDX (no inline `style`, braces in captions escaped). If the site renders its own layout and already loads `embed.js` once, delete the trailing script line to avoid loading it twice. The iframe keeps its `sandbox="allow-scripts"` and resizes itself once `embed.js` runs.
|
|
429
431
|
|
|
430
432
|
### Limitations to tell the user
|
|
431
433
|
|
|
@@ -446,6 +448,7 @@ Error codes: `references/troubleshooting.md`.
|
|
|
446
448
|
```sh
|
|
447
449
|
coauthor draft get <id> --format markdown --json # data.markdown, images as markdown image links
|
|
448
450
|
coauthor draft get <id> --format html --json # data.html, images as <img> tags
|
|
451
|
+
coauthor draft get <id> --format markdown --widgets embed --json # website you control: interactives as live iframes (see interactive-widgets.md)
|
|
449
452
|
coauthor draft get <id> --format text --json # data.text, plain text with image URLs
|
|
450
453
|
coauthor draft get <id> --format json --json # data.content, the editor document (for edits)
|
|
451
454
|
```
|
|
@@ -463,12 +466,16 @@ coauthor post-details show <id> --json # data.post_details (null for drafts ma
|
|
|
463
466
|
coauthor post-details set <id> --seo-title "..." --description "..." --slug "..." --excerpt "..." --json
|
|
464
467
|
coauthor post-details set <id> --live-url https://example.com/my-post/ --json # where the post is live
|
|
465
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
|
|
466
471
|
```
|
|
467
472
|
|
|
468
|
-
`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.
|
|
469
474
|
|
|
470
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.
|
|
471
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
|
+
|
|
472
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.
|
|
473
480
|
|
|
474
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.
|
|
@@ -667,18 +674,20 @@ Errors: `plan_stale` (the profile's website or market changed; run `generate` to
|
|
|
667
674
|
|
|
668
675
|
### Monthly check
|
|
669
676
|
|
|
670
|
-
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.
|
|
671
678
|
|
|
672
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`.
|
|
673
680
|
|
|
674
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`).
|
|
675
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
|
+
|
|
676
685
|
#### Results
|
|
677
686
|
|
|
678
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`).
|
|
679
688
|
|
|
680
|
-
- `data.results` has one row per tracked post (a live address and a
|
|
681
|
-
- `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.
|
|
682
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.
|
|
683
692
|
- Everything is empty or `null` while monthly checks are not switched on for the account, and before the first check has run.
|
|
684
693
|
|
|
@@ -741,8 +750,9 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
741
750
|
| `invalid_keyword` | The keyword is empty or longer than 200 characters. | Pass a plain search phrase. |
|
|
742
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`. |
|
|
743
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. |
|
|
744
|
-
| `post_details_unavailable` | The draft was made before post details launched, so it has
|
|
745
|
-
| `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. |
|
|
746
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 "..."`. |
|
|
747
757
|
| `uploaded_image` | `image generate` on an image the user replaced with their own file. | Use `image edit --edit-prompt "..."`, or `image replace` again. |
|
|
748
758
|
| `not_a_panel` | `image replace` on an article image. | Only slideshow and video panels can be replaced from the CLI. |
|