@clickminded/coauthor-cli 0.0.53 → 0.0.55
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 +6 -0
- package/dist/commands.js +554 -5
- package/dist/parser.js +10 -1
- package/package.json +1 -1
- package/skills/coauthor/SKILL.md +14 -3
- package/skills/coauthor/references/credits-and-plans.md +2 -0
- package/skills/coauthor/references/interactive-widgets.md +40 -0
- package/skills/coauthor/references/seo-content-plan.md +73 -0
- package/skills/coauthor/references/troubleshooting.md +34 -1
- package/skills/cursor/coauthor-cli.mdc +169 -4
package/README.md
CHANGED
|
@@ -73,6 +73,8 @@ coauthor image list <id> --json
|
|
|
73
73
|
coauthor image generate <id> --placeholder-id <id or placeholder_id> [--prompt "what it should show"] --json
|
|
74
74
|
coauthor image status <id> [--artifact article|slideshow|video] --json
|
|
75
75
|
coauthor image replace <id> --placeholder-id <panel id> --file <path> --json # slideshow/video panels only
|
|
76
|
+
coauthor widgets list <id> --json # interactives (beta): placeholders and built figures, with credit caps
|
|
77
|
+
coauthor widgets build-all <id> --wait --json # spends credits: show the placeholders to the user first
|
|
76
78
|
coauthor repurpose generate <id> --format all --json # X thread and post, LinkedIn, Facebook, email newsletter
|
|
77
79
|
coauthor repurpose download <id> --out ./social # copy-ready files plus the article
|
|
78
80
|
coauthor share <id> --json # public read-only link
|
|
@@ -85,6 +87,10 @@ coauthor integrations list --json # WordPress sites
|
|
|
85
87
|
coauthor seo markets --country Mexico --language Spanish --json # Google search data coverage for a market
|
|
86
88
|
coauthor search-brief show <id> --json # SEO mode: target keyword and what ranks (limited rollout)
|
|
87
89
|
coauthor search-brief set-keyword <id> "email marketing" --json # target your own keyword (--confirm-reset after an outline)
|
|
90
|
+
coauthor seo-plan generate --wait --json # SEO content plan for the default profile: ~420 credits, 5-12 minutes (limited rollout)
|
|
91
|
+
coauthor seo-plan show --kind post --json # strategy, Do next moves, counts, and the post ideas
|
|
92
|
+
coauthor seo-plan write <item-id> --json # open a project for a post idea, then continue with workflow run
|
|
93
|
+
coauthor seo-plan dismiss <item-id> --json # hide an idea (--undo brings it back)
|
|
88
94
|
```
|
|
89
95
|
|
|
90
96
|
Run `coauthor --help` or `coauthor <command> --help` for every command and option. `--json` gives machine-readable output, `--wait` waits for long-running work, and JSON options such as `--data` and `--contract` accept `@file.json` (or `@-` for stdin).
|
package/dist/commands.js
CHANGED
|
@@ -37,8 +37,12 @@ export async function runCommand(input, context) {
|
|
|
37
37
|
return runLogCommand(action, input, context.client);
|
|
38
38
|
if (scope === 'profile')
|
|
39
39
|
return runProfileCommand(action, input, context.client);
|
|
40
|
+
if (scope === 'widgets')
|
|
41
|
+
return runWidgetsCommand(action, input, context.client);
|
|
40
42
|
if (scope === 'site')
|
|
41
43
|
return runSiteCommand(action, input, context.client);
|
|
44
|
+
if (scope === 'seo-plan')
|
|
45
|
+
return runSeoPlanCommand(action, input, context.client);
|
|
42
46
|
if (scope === 'integrations')
|
|
43
47
|
return { ok: true, data: await context.client.request({ path: 'integrations' }) };
|
|
44
48
|
if (scope === 'source')
|
|
@@ -490,8 +494,8 @@ async function runModelsCommand(action, input, client) {
|
|
|
490
494
|
}
|
|
491
495
|
if (subaction === 'set') {
|
|
492
496
|
const body = modelOverrideBody(input);
|
|
493
|
-
if (!body.planningModel && !body.writingModel) {
|
|
494
|
-
throw new Error('Usage: coauthor models preferences set [--planning-model <id>] [--writing-model <id>]');
|
|
497
|
+
if (!body.planningModel && !body.writingModel && !body.widgetModel) {
|
|
498
|
+
throw new Error('Usage: coauthor models preferences set [--planning-model <id>] [--writing-model <id>] [--widget-model <id>]');
|
|
495
499
|
}
|
|
496
500
|
const data = await client.request({ method: 'POST', path: 'models/preferences', body });
|
|
497
501
|
return { ok: true, message: 'Model preferences updated', data };
|
|
@@ -507,6 +511,9 @@ function modelOverrideBody(input) {
|
|
|
507
511
|
body.planningModel = planningModel;
|
|
508
512
|
if (writingModel)
|
|
509
513
|
body.writingModel = writingModel;
|
|
514
|
+
const widgetModel = getString(input.values, 'widget-model');
|
|
515
|
+
if (widgetModel)
|
|
516
|
+
body.widgetModel = widgetModel;
|
|
510
517
|
return body;
|
|
511
518
|
}
|
|
512
519
|
function formatModelsList(data) {
|
|
@@ -534,6 +541,9 @@ function formatModelsList(data) {
|
|
|
534
541
|
formatGroup('Planning models (--planning-model)', models.planning),
|
|
535
542
|
'',
|
|
536
543
|
formatGroup('Writing models (--writing-model)', models.writing),
|
|
544
|
+
...(models.widgets
|
|
545
|
+
? ['', formatGroup('Interactive widget models (--widget-model, beta)', models.widgets)]
|
|
546
|
+
: []),
|
|
537
547
|
].join('\n');
|
|
538
548
|
}
|
|
539
549
|
async function runArtifactCommand(artifact, action, input, client) {
|
|
@@ -1891,7 +1901,260 @@ async function runProfileCommand(action, input, client) {
|
|
|
1891
1901
|
throw new Error('Usage: coauthor profile show <profile-id>');
|
|
1892
1902
|
return { ok: true, data: await client.request({ path: `profiles/${encodeURIComponent(profileId)}` }) };
|
|
1893
1903
|
}
|
|
1894
|
-
|
|
1904
|
+
if (action === 'update') {
|
|
1905
|
+
const profileId = input.positionals[0];
|
|
1906
|
+
const value = getString(input.values, 'interactive-widgets');
|
|
1907
|
+
if (!profileId || value === undefined) {
|
|
1908
|
+
throw new Error('Usage: coauthor profile update <profile-id> --interactive-widgets on|off');
|
|
1909
|
+
}
|
|
1910
|
+
const normalized = value.trim().toLowerCase();
|
|
1911
|
+
if (!['on', 'off'].includes(normalized))
|
|
1912
|
+
throw new Error(`--interactive-widgets must be on or off (got "${value}").`);
|
|
1913
|
+
const data = await client.request({
|
|
1914
|
+
method: 'PATCH',
|
|
1915
|
+
path: `profiles/${encodeURIComponent(profileId)}`,
|
|
1916
|
+
body: { interactive_widgets_enabled: normalized === 'on' },
|
|
1917
|
+
});
|
|
1918
|
+
return { ok: true, message: `Interactives are ${normalized} for this profile.`, data };
|
|
1919
|
+
}
|
|
1920
|
+
throw new Error('Usage: coauthor profile <list|show|update>');
|
|
1921
|
+
}
|
|
1922
|
+
const WIDGET_EDIT_INSTRUCTION_MAX_CHARS = 500;
|
|
1923
|
+
function widgetList(data) {
|
|
1924
|
+
const value = getResponseValue(data, 'widgets');
|
|
1925
|
+
return Array.isArray(value)
|
|
1926
|
+
? value.filter((entry) => Boolean(entry) && typeof entry === 'object' && !Array.isArray(entry))
|
|
1927
|
+
: [];
|
|
1928
|
+
}
|
|
1929
|
+
function widgetRecord(data) {
|
|
1930
|
+
const value = getResponseValue(data, 'widget');
|
|
1931
|
+
return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
|
|
1932
|
+
}
|
|
1933
|
+
function widgetIsBuilding(widget) {
|
|
1934
|
+
return widget.build_state === 'queued' || widget.build_state === 'building';
|
|
1935
|
+
}
|
|
1936
|
+
function widgetError(widget) {
|
|
1937
|
+
return widget.error && typeof widget.error === 'object' && !Array.isArray(widget.error) ? widget.error : null;
|
|
1938
|
+
}
|
|
1939
|
+
function widgetStateLabel(widget) {
|
|
1940
|
+
if (widget.build_state === 'queued')
|
|
1941
|
+
return 'queued';
|
|
1942
|
+
if (widget.build_state === 'building')
|
|
1943
|
+
return 'building';
|
|
1944
|
+
if (widget.build_state === 'failed') {
|
|
1945
|
+
const error = widgetError(widget);
|
|
1946
|
+
return `build failed${typeof error?.code === 'string' ? ` (${error.code})` : ''}`;
|
|
1947
|
+
}
|
|
1948
|
+
return widget.current_version == null ? 'placeholder, not built' : `built, v${widget.current_version}`;
|
|
1949
|
+
}
|
|
1950
|
+
function widgetSpec(widget) {
|
|
1951
|
+
return widget.spec && typeof widget.spec === 'object' && !Array.isArray(widget.spec) ? widget.spec : {};
|
|
1952
|
+
}
|
|
1953
|
+
function describeWidget(widget) {
|
|
1954
|
+
const spec = widgetSpec(widget);
|
|
1955
|
+
const lines = [
|
|
1956
|
+
`${String(widget.id)} ${String(spec.title ?? '(untitled)')} [${widgetStateLabel(widget)}]`,
|
|
1957
|
+
` aha: ${String(spec.aha ?? '')}`,
|
|
1958
|
+
` move: ${String(spec.move ?? '')}`,
|
|
1959
|
+
` picture: ${String(spec.visual ?? '')}`,
|
|
1960
|
+
` credit cap: ${String(widget.credit_cap ?? '?')} to build, ${String(widget.edit_credit_cap ?? '?')} to edit${widget.replaces_image === true ? '; replaces an image (use-image keeps the image instead)' : ''}`,
|
|
1961
|
+
];
|
|
1962
|
+
if (typeof widget.embed_url === 'string')
|
|
1963
|
+
lines.push(` embed: ${widget.embed_url}`);
|
|
1964
|
+
if (widget.fact_check_warning)
|
|
1965
|
+
lines.push(` fact check: ${String(widget.fact_check_warning)}`);
|
|
1966
|
+
const error = widgetError(widget);
|
|
1967
|
+
if (error)
|
|
1968
|
+
lines.push(` error: ${String(error.code)}: ${String(error.message)}`);
|
|
1969
|
+
return lines.join('\n');
|
|
1970
|
+
}
|
|
1971
|
+
function widgetsListMessage(data) {
|
|
1972
|
+
const widgets = widgetList(data);
|
|
1973
|
+
if (widgets.length === 0) {
|
|
1974
|
+
return 'No interactives in this project. Drafts plan them when interactives are on for the profile (coauthor profile update <profile-id> --interactive-widgets on).';
|
|
1975
|
+
}
|
|
1976
|
+
const model = getResponseValue(data, 'model');
|
|
1977
|
+
const placeholders = widgets.filter((widget) => widget.current_version == null && widget.build_state === 'idle').length;
|
|
1978
|
+
const lines = widgets.map(describeWidget);
|
|
1979
|
+
if (model) {
|
|
1980
|
+
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)}).`);
|
|
1981
|
+
}
|
|
1982
|
+
if (placeholders > 0) {
|
|
1983
|
+
lines.push('Placeholders cost nothing until built. Show them to the user and get a yes before building: coauthor widgets build <project-id> <widget-id> (or build-all).');
|
|
1984
|
+
}
|
|
1985
|
+
return lines.join('\n');
|
|
1986
|
+
}
|
|
1987
|
+
// Polls until nothing is queued or building, under the 10-minute agent shell limit. A timeout is a
|
|
1988
|
+
// resumable still_running result, never an error. `watch` limits the check to those widget ids.
|
|
1989
|
+
async function waitForWidgets(client, projectId, watch, first) {
|
|
1990
|
+
const deadline = Date.now() + waitTimeoutMs(9 * 60_000);
|
|
1991
|
+
const pollMs = Math.max(waitPollMs(), 0);
|
|
1992
|
+
const base = `projects/${encodeURIComponent(projectId)}/widgets`;
|
|
1993
|
+
const read = async () => {
|
|
1994
|
+
if (watch && watch.length === 1) {
|
|
1995
|
+
const widget = widgetRecord(await client.request({ path: `${base}/${encodeURIComponent(watch[0])}` }));
|
|
1996
|
+
return widget ? [widget] : [];
|
|
1997
|
+
}
|
|
1998
|
+
const all = widgetList(await client.request({ path: base }));
|
|
1999
|
+
return watch ? all.filter((widget) => watch.includes(String(widget.id))) : all;
|
|
2000
|
+
};
|
|
2001
|
+
let widgets = first;
|
|
2002
|
+
while (widgets.some(widgetIsBuilding) && Date.now() < deadline) {
|
|
2003
|
+
await sleep(Math.min(pollMs, 15_000));
|
|
2004
|
+
widgets = await read();
|
|
2005
|
+
}
|
|
2006
|
+
return { widgets, building: widgets.some(widgetIsBuilding) };
|
|
2007
|
+
}
|
|
2008
|
+
function widgetsWaitResult(projectId, result, resumeCommand, doneWord) {
|
|
2009
|
+
const { widgets } = result;
|
|
2010
|
+
const data = { widgets };
|
|
2011
|
+
if (result.building) {
|
|
2012
|
+
const building = widgets.filter(widgetIsBuilding).length;
|
|
2013
|
+
return {
|
|
2014
|
+
ok: false,
|
|
2015
|
+
status: 'still_running',
|
|
2016
|
+
exitCode: 2,
|
|
2017
|
+
resume_command: resumeCommand,
|
|
2018
|
+
message: `${building} interactive${building === 1 ? ' is' : 's are'} still building. Check again with: ${resumeCommand}`,
|
|
2019
|
+
data,
|
|
2020
|
+
};
|
|
2021
|
+
}
|
|
2022
|
+
const failed = widgets.filter((widget) => widget.build_state === 'failed');
|
|
2023
|
+
if (failed.length > 0) {
|
|
2024
|
+
const first = failed[0];
|
|
2025
|
+
const error = widgetError(first);
|
|
2026
|
+
return {
|
|
2027
|
+
ok: false,
|
|
2028
|
+
status: typeof error?.code === 'string' ? error.code : 'widget_build_failed',
|
|
2029
|
+
message: `${failed.length} interactive${failed.length === 1 ? '' : 's'} failed: ${String(error?.message ?? 'the build failed')} Failed builds are not charged. Retry with: coauthor widgets build ${projectId} ${String(first.id)}`,
|
|
2030
|
+
data,
|
|
2031
|
+
};
|
|
2032
|
+
}
|
|
2033
|
+
return {
|
|
2034
|
+
ok: true,
|
|
2035
|
+
message: `${widgets.length} interactive${widgets.length === 1 ? '' : 's'} ${doneWord}.\n${widgets.map(describeWidget).join('\n')}`,
|
|
2036
|
+
messageIncludesData: true,
|
|
2037
|
+
data,
|
|
2038
|
+
};
|
|
2039
|
+
}
|
|
2040
|
+
function widgetIdList(value) {
|
|
2041
|
+
return Array.isArray(value) ? value.map(String) : [];
|
|
2042
|
+
}
|
|
2043
|
+
async function runWidgetsCommand(action, input, client) {
|
|
2044
|
+
const usage = 'Usage: coauthor widgets <list|status|build|build-all|use-image|edit|delete> <project-id> [<widget-id>]';
|
|
2045
|
+
if (!action)
|
|
2046
|
+
throw new Error(usage);
|
|
2047
|
+
const projectId = input.positionals[0];
|
|
2048
|
+
if (!projectId)
|
|
2049
|
+
throw new Error(usage);
|
|
2050
|
+
const base = `projects/${encodeURIComponent(projectId)}/widgets`;
|
|
2051
|
+
const wait = getBoolean(input.values, 'wait');
|
|
2052
|
+
const widgetId = input.positionals[1];
|
|
2053
|
+
const needWidget = (name) => {
|
|
2054
|
+
if (!widgetId)
|
|
2055
|
+
throw new Error(`Usage: coauthor widgets ${name} <project-id> <widget-id>`);
|
|
2056
|
+
return widgetId;
|
|
2057
|
+
};
|
|
2058
|
+
const idempotencyKey = getString(input.values, 'idempotency-key')?.trim() || undefined;
|
|
2059
|
+
if (action === 'list') {
|
|
2060
|
+
let data = await client.request({ path: base });
|
|
2061
|
+
if (wait && widgetList(data).some(widgetIsBuilding)) {
|
|
2062
|
+
const waited = await waitForWidgets(client, projectId, null, widgetList(data));
|
|
2063
|
+
if (waited.building)
|
|
2064
|
+
return widgetsWaitResult(projectId, waited, `coauthor widgets list ${projectId} --wait`, 'ready');
|
|
2065
|
+
data = await client.request({ path: base });
|
|
2066
|
+
}
|
|
2067
|
+
return { ok: true, message: widgetsListMessage(data), messageIncludesData: true, data };
|
|
2068
|
+
}
|
|
2069
|
+
if (action === 'status') {
|
|
2070
|
+
const id = needWidget('status');
|
|
2071
|
+
const data = await client.request({ path: `${base}/${encodeURIComponent(id)}` });
|
|
2072
|
+
const widget = widgetRecord(data);
|
|
2073
|
+
if (wait && widget && widgetIsBuilding(widget)) {
|
|
2074
|
+
const waited = await waitForWidgets(client, projectId, [id], [widget]);
|
|
2075
|
+
return widgetsWaitResult(projectId, waited, `coauthor widgets status ${projectId} ${id} --wait`, 'ready');
|
|
2076
|
+
}
|
|
2077
|
+
return { ok: true, message: widget ? describeWidget(widget) : undefined, messageIncludesData: Boolean(widget), data };
|
|
2078
|
+
}
|
|
2079
|
+
if (action === 'build') {
|
|
2080
|
+
const id = needWidget('build');
|
|
2081
|
+
const data = await client.request({ method: 'POST', path: `${base}/${encodeURIComponent(id)}/build`, idempotencyKey });
|
|
2082
|
+
const already = getResponseValue(data, 'already_running') === true;
|
|
2083
|
+
const head = `${already ? 'Already building' : 'Build started'}: spends up to ${String(getResponseValue(data, 'credit_cap') ?? '?')} credits (failed builds are not charged).`;
|
|
2084
|
+
const resume = `coauthor widgets status ${projectId} ${id} --wait`;
|
|
2085
|
+
if (!wait)
|
|
2086
|
+
return { ok: true, message: `${head} Check with: ${resume}`, data };
|
|
2087
|
+
const widget = widgetRecord(data);
|
|
2088
|
+
return widgetsWaitResult(projectId, await waitForWidgets(client, projectId, [id], widget ? [widget] : []), resume, 'built');
|
|
2089
|
+
}
|
|
2090
|
+
if (action === 'build-all') {
|
|
2091
|
+
const ids = input.positionals.slice(1);
|
|
2092
|
+
const body = ids.length > 0 ? { widget_ids: ids } : {};
|
|
2093
|
+
const data = await client.request({ method: 'POST', path: `${base}/build-all`, body, idempotencyKey });
|
|
2094
|
+
const queued = widgetIdList(getResponseValue(data, 'queued'));
|
|
2095
|
+
const running = widgetIdList(getResponseValue(data, 'already_running'));
|
|
2096
|
+
const skipped = getResponseValue(data, 'skipped');
|
|
2097
|
+
const skippedText = Array.isArray(skipped) && skipped.length > 0
|
|
2098
|
+
? ` Skipped: ${skipped.map((entry) => `${String(entry.id)} (${String(entry.reason)})`).join(', ')}.`
|
|
2099
|
+
: '';
|
|
2100
|
+
if (queued.length === 0 && running.length === 0)
|
|
2101
|
+
return { ok: true, message: `Nothing to build.${skippedText}`, data };
|
|
2102
|
+
const head = `Started ${queued.length} build${queued.length === 1 ? '' : 's'}: spends up to ${String(getResponseValue(data, 'max_credits') ?? '?')} credits in total (failed builds are not charged).${skippedText}`;
|
|
2103
|
+
const resume = `coauthor widgets list ${projectId} --wait`;
|
|
2104
|
+
if (!wait)
|
|
2105
|
+
return { ok: true, message: `${head} Check with: ${resume}`, data };
|
|
2106
|
+
return widgetsWaitResult(projectId, await waitForWidgets(client, projectId, [...queued, ...running], widgetList(data)), resume, 'built');
|
|
2107
|
+
}
|
|
2108
|
+
if (action === 'edit') {
|
|
2109
|
+
const id = needWidget('edit');
|
|
2110
|
+
const instruction = getString(input.values, 'instruction')?.trim();
|
|
2111
|
+
if (!instruction)
|
|
2112
|
+
throw new Error('Usage: coauthor widgets edit <project-id> <widget-id> --instruction "..." --yes');
|
|
2113
|
+
if (instruction.length > WIDGET_EDIT_INSTRUCTION_MAX_CHARS) {
|
|
2114
|
+
throw new Error(`--instruction must be ${WIDGET_EDIT_INSTRUCTION_MAX_CHARS} characters or fewer (got ${instruction.length}).`);
|
|
2115
|
+
}
|
|
2116
|
+
if (!getBoolean(input.values, 'yes')) {
|
|
2117
|
+
throw new Error('Editing an interactive changes every published copy of it (blog posts and WordPress pages that embed it) and spends credits. Re-run with --yes to confirm.');
|
|
2118
|
+
}
|
|
2119
|
+
const data = await client.request({ method: 'POST', path: `${base}/${encodeURIComponent(id)}/edit`, body: { instruction }, idempotencyKey });
|
|
2120
|
+
const head = `Edit started: spends up to ${String(getResponseValue(data, 'credit_cap') ?? '?')} credits. The change applies to every published copy.`;
|
|
2121
|
+
const resume = `coauthor widgets status ${projectId} ${id} --wait`;
|
|
2122
|
+
if (!wait)
|
|
2123
|
+
return { ok: true, message: `${head} Check with: ${resume}`, data };
|
|
2124
|
+
const widget = widgetRecord(data);
|
|
2125
|
+
return widgetsWaitResult(projectId, await waitForWidgets(client, projectId, [id], widget ? [widget] : []), resume, 'edited');
|
|
2126
|
+
}
|
|
2127
|
+
if (action === 'use-image') {
|
|
2128
|
+
const id = needWidget('use-image');
|
|
2129
|
+
const data = await client.request({ method: 'POST', path: `${base}/${encodeURIComponent(id)}/use-image` });
|
|
2130
|
+
const placeholder = getResponseValue(data, 'placeholder');
|
|
2131
|
+
const updated = getResponseValue(data, 'document_updated') === true;
|
|
2132
|
+
const note = getResponseString(data, 'document_note');
|
|
2133
|
+
return {
|
|
2134
|
+
ok: true,
|
|
2135
|
+
message: [
|
|
2136
|
+
`The interactive is replaced by an image placeholder${placeholder?.placeholder_id ? ` (${String(placeholder.placeholder_id)})` : ''}.`,
|
|
2137
|
+
updated ? 'The draft was updated.' : `The draft was NOT updated${note ? `: ${note}` : '.'}`,
|
|
2138
|
+
`Generate the image with: coauthor image generate ${projectId} --placeholder-id <placeholder-id>`,
|
|
2139
|
+
].join('\n'),
|
|
2140
|
+
data,
|
|
2141
|
+
};
|
|
2142
|
+
}
|
|
2143
|
+
if (action === 'delete') {
|
|
2144
|
+
const id = needWidget('delete');
|
|
2145
|
+
if (!getBoolean(input.values, 'yes')) {
|
|
2146
|
+
throw new Error('Deleting an interactive removes it everywhere: every published copy (blog posts, WordPress pages) stops showing it, and it cannot be restored. Re-run with --yes to confirm.');
|
|
2147
|
+
}
|
|
2148
|
+
const data = await client.request({ method: 'DELETE', path: `${base}/${encodeURIComponent(id)}` });
|
|
2149
|
+
const updated = getResponseValue(data, 'document_updated') === true;
|
|
2150
|
+
const note = getResponseString(data, 'document_note');
|
|
2151
|
+
return {
|
|
2152
|
+
ok: true,
|
|
2153
|
+
message: `Deleted ${id}${getResponseValue(data, 'was_published') === true ? ' everywhere, including every published copy' : ''}. ${updated ? 'The draft was updated.' : `The draft was NOT updated${note ? `: ${note}` : '.'}`}`,
|
|
2154
|
+
data,
|
|
2155
|
+
};
|
|
2156
|
+
}
|
|
2157
|
+
throw new Error(usage);
|
|
1895
2158
|
}
|
|
1896
2159
|
function siteMessage(data, request) {
|
|
1897
2160
|
const site = getResponseValue(data, 'site');
|
|
@@ -1935,6 +2198,259 @@ async function runSiteCommand(action, input, client) {
|
|
|
1935
2198
|
const data = await client.request({ path });
|
|
1936
2199
|
return { ok: true, message: siteMessage(data), data };
|
|
1937
2200
|
}
|
|
2201
|
+
// ─── SEO content plan (limited rollout) ──────────────────────────────────────
|
|
2202
|
+
const SEO_PLAN_KINDS = ['post', 'improve', 'page', 'left_out', 'covered', 'not_checked'];
|
|
2203
|
+
const SEO_PLAN_KIND_LABELS = {
|
|
2204
|
+
post: 'posts to write',
|
|
2205
|
+
improve: 'pages to improve',
|
|
2206
|
+
page: 'page ideas',
|
|
2207
|
+
left_out: 'searches left out',
|
|
2208
|
+
covered: 'already covered',
|
|
2209
|
+
not_checked: 'not checked',
|
|
2210
|
+
};
|
|
2211
|
+
const SEO_PLAN_USAGE = [
|
|
2212
|
+
'Usage: coauthor seo-plan show [--profile <profile-id>] [--kind post|improve|page|left_out|covered|not_checked] [--stage <stage>] [--chance <chance>] [--limit <n>] [--json]',
|
|
2213
|
+
' coauthor seo-plan generate [--profile <profile-id>] [--adjust "<text>"] [--wait] [--json]',
|
|
2214
|
+
' coauthor seo-plan write <item-id> [--json]',
|
|
2215
|
+
' coauthor seo-plan dismiss <item-id> [--undo] [--json]',
|
|
2216
|
+
].join('\n');
|
|
2217
|
+
function planRecord(value) {
|
|
2218
|
+
return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
|
|
2219
|
+
}
|
|
2220
|
+
function planString(record, key) {
|
|
2221
|
+
const value = record[key];
|
|
2222
|
+
return typeof value === 'string' && value.trim() ? value.trim() : null;
|
|
2223
|
+
}
|
|
2224
|
+
async function resolveProfileOption(input, client) {
|
|
2225
|
+
const given = getString(input.values, 'profile') ?? input.positionals[0];
|
|
2226
|
+
if (given)
|
|
2227
|
+
return given;
|
|
2228
|
+
const profiles = await client.request({ path: 'profiles' });
|
|
2229
|
+
const fallback = getResponseValue(profiles, 'default_profile_id');
|
|
2230
|
+
if (typeof fallback !== 'string' || !fallback)
|
|
2231
|
+
throw new Error('No writer profile found. Create one in the CoAuthor web app.');
|
|
2232
|
+
return fallback;
|
|
2233
|
+
}
|
|
2234
|
+
function httpErrorCode(error) {
|
|
2235
|
+
if (!(error instanceof AgentHttpError))
|
|
2236
|
+
return null;
|
|
2237
|
+
const body = planRecord(error.responseBody);
|
|
2238
|
+
const code = planRecord(body.error).code;
|
|
2239
|
+
return typeof code === 'string' ? code : null;
|
|
2240
|
+
}
|
|
2241
|
+
function seoPlanItemLine(item) {
|
|
2242
|
+
const keyword = planString(item, 'primary_keyword');
|
|
2243
|
+
const title = planString(item, 'title') ?? keyword ?? '(untitled)';
|
|
2244
|
+
const facts = [
|
|
2245
|
+
typeof item.volume === 'number' ? `${item.volume}/mo` : null,
|
|
2246
|
+
planString(item, 'stage'),
|
|
2247
|
+
planString(item, 'chance'),
|
|
2248
|
+
].filter(Boolean).join(', ');
|
|
2249
|
+
const id = planString(item, 'id') ?? '';
|
|
2250
|
+
const head = ` ${id} ${title}`;
|
|
2251
|
+
const search = keyword && keyword !== title ? ` [search: ${keyword}]` : '';
|
|
2252
|
+
const where = planString(item, 'existing_url');
|
|
2253
|
+
const position = typeof item.existing_position === 'number' ? ` (position ${item.existing_position})` : '';
|
|
2254
|
+
const hint = planString(item, 'improve_hint') ?? planString(item, 'reason') ?? planString(item, 'note');
|
|
2255
|
+
const written = planString(item, 'project_id') ? ` -> project ${planString(item, 'project_id')}` : '';
|
|
2256
|
+
const dismissed = item.dismissed === true ? ' (dismissed)' : '';
|
|
2257
|
+
return [
|
|
2258
|
+
`${head}${search}${facts ? ` (${facts})` : ''}${written}${dismissed}`,
|
|
2259
|
+
where ? ` ${where}${position}` : null,
|
|
2260
|
+
hint ? ` ${hint}` : null,
|
|
2261
|
+
].filter(Boolean).join('\n');
|
|
2262
|
+
}
|
|
2263
|
+
function seoPlanShowMessage(data, kind) {
|
|
2264
|
+
const view = planRecord(data);
|
|
2265
|
+
const plan = view.plan === null || view.plan === undefined ? null : planRecord(view.plan);
|
|
2266
|
+
const estimate = typeof view.estimate_credits === 'number' ? view.estimate_credits : null;
|
|
2267
|
+
const status = plan ? planString(plan, 'status') : null;
|
|
2268
|
+
if (!plan || status === 'idle') {
|
|
2269
|
+
return `No SEO content plan for this profile yet. Make one with \`coauthor seo-plan generate --wait\`${estimate ? ` (about ${estimate} credits)` : ''}.`;
|
|
2270
|
+
}
|
|
2271
|
+
const lines = [];
|
|
2272
|
+
if (status === 'queued' || status === 'running') {
|
|
2273
|
+
const step = planString(planRecord(plan.progress), 'step') ?? planString(planRecord(plan.progress), 'label');
|
|
2274
|
+
lines.push(`A plan is being made${step ? ` (${step})` : ''}. Check again with \`coauthor seo-plan show\`.${plan.generated_at ? ' The ideas below are from the previous plan.' : ''}`);
|
|
2275
|
+
}
|
|
2276
|
+
else if (status === 'failed') {
|
|
2277
|
+
const code = planString(plan, 'error_code');
|
|
2278
|
+
lines.push(`The last plan run failed${code ? ` (${code})` : ''}: ${planString(plan, 'error_message') ?? 'unknown error'}. Try again with \`coauthor seo-plan generate --wait\`.`);
|
|
2279
|
+
}
|
|
2280
|
+
if (view.stale === true)
|
|
2281
|
+
lines.push('The profile\'s website or market changed since this plan was made. `coauthor seo-plan generate` updates it.');
|
|
2282
|
+
const strategy = planString(plan, 'strategy_line');
|
|
2283
|
+
if (strategy)
|
|
2284
|
+
lines.push(`Strategy: ${strategy}`);
|
|
2285
|
+
const competitors = planString(plan, 'competitors_line');
|
|
2286
|
+
if (competitors)
|
|
2287
|
+
lines.push(`Competitors: ${competitors}`);
|
|
2288
|
+
const doNext = Array.isArray(view.do_next) ? view.do_next.map(planRecord) : [];
|
|
2289
|
+
if (doNext.length > 0) {
|
|
2290
|
+
lines.push('', 'Do next:');
|
|
2291
|
+
doNext.forEach((item, index) => {
|
|
2292
|
+
lines.push(`${index + 1}.${seoPlanItemLine(item).slice(1)}`);
|
|
2293
|
+
const why = planString(item, 'why');
|
|
2294
|
+
if (why)
|
|
2295
|
+
lines.push(` ${why}`);
|
|
2296
|
+
});
|
|
2297
|
+
}
|
|
2298
|
+
const counts = planRecord(view.counts_by_kind);
|
|
2299
|
+
const summary = SEO_PLAN_KINDS
|
|
2300
|
+
.map((entry) => (typeof counts[entry] === 'number' && counts[entry] > 0 ? `${counts[entry]} ${SEO_PLAN_KIND_LABELS[entry]}` : null))
|
|
2301
|
+
.filter(Boolean);
|
|
2302
|
+
lines.push('', summary.length > 0 ? `Ideas: ${summary.join(', ')}.` : 'The plan has no ideas.');
|
|
2303
|
+
const items = Array.isArray(view.items) ? view.items.map(planRecord) : [];
|
|
2304
|
+
const total = typeof view.total === 'number' ? view.total : items.length;
|
|
2305
|
+
if (items.length > 0 || total > 0) {
|
|
2306
|
+
lines.push('', `${SEO_PLAN_KIND_LABELS[kind] ?? kind} (${items.length === total ? total : `${items.length} of ${total}`}):`);
|
|
2307
|
+
for (const item of items)
|
|
2308
|
+
lines.push(seoPlanItemLine(item));
|
|
2309
|
+
if (kind === 'post')
|
|
2310
|
+
lines.push('', 'Write one with `coauthor seo-plan write <item-id>`; hide one with `coauthor seo-plan dismiss <item-id>`.');
|
|
2311
|
+
}
|
|
2312
|
+
else {
|
|
2313
|
+
lines.push('', `Nothing to show for ${SEO_PLAN_KIND_LABELS[kind] ?? kind}.`);
|
|
2314
|
+
}
|
|
2315
|
+
return lines.join('\n');
|
|
2316
|
+
}
|
|
2317
|
+
function seoPlanWaitFailure(status) {
|
|
2318
|
+
const code = planString(status, 'error_code');
|
|
2319
|
+
const message = planString(status, 'error_message') ?? 'The plan run failed.';
|
|
2320
|
+
return {
|
|
2321
|
+
ok: false,
|
|
2322
|
+
status: code ?? 'failed',
|
|
2323
|
+
message: `The plan run failed${code ? ` (${code})` : ''}: ${message}`,
|
|
2324
|
+
data: status,
|
|
2325
|
+
};
|
|
2326
|
+
}
|
|
2327
|
+
// Polls the plan's status (capped under the 10-minute agent shell limit) until it stops queued/running.
|
|
2328
|
+
async function waitForSeoPlan(client, profileId, started) {
|
|
2329
|
+
const statusPath = `profiles/${encodeURIComponent(profileId)}/seo-plan/status`;
|
|
2330
|
+
const resume = `coauthor seo-plan generate --profile ${profileId} --wait`;
|
|
2331
|
+
const deadline = Date.now() + waitTimeoutMs(9 * 60_000);
|
|
2332
|
+
const pollMs = Math.max(waitPollMs(), 0);
|
|
2333
|
+
let status = planRecord(await client.request({ path: statusPath }));
|
|
2334
|
+
while (status.done !== true && Date.now() < deadline) {
|
|
2335
|
+
await sleep(Math.min(pollMs, 15_000));
|
|
2336
|
+
status = planRecord(await client.request({ path: statusPath }));
|
|
2337
|
+
}
|
|
2338
|
+
if (status.done !== true) {
|
|
2339
|
+
const step = planString(planRecord(status.progress), 'step') ?? planString(planRecord(status.progress), 'label');
|
|
2340
|
+
return {
|
|
2341
|
+
ok: false,
|
|
2342
|
+
status: 'still_running',
|
|
2343
|
+
exitCode: 2,
|
|
2344
|
+
resume_command: resume,
|
|
2345
|
+
message: `The plan is still being made${step ? ` (${step})` : ''}. Plans take about 5 to 12 minutes. Keep waiting with: ${resume}`,
|
|
2346
|
+
data: (started ?? status),
|
|
2347
|
+
};
|
|
2348
|
+
}
|
|
2349
|
+
if (status.status === 'failed')
|
|
2350
|
+
return seoPlanWaitFailure(status);
|
|
2351
|
+
return {
|
|
2352
|
+
ok: true,
|
|
2353
|
+
message: `The plan is ready. See it with \`coauthor seo-plan show --profile ${profileId}\`.`,
|
|
2354
|
+
data: status,
|
|
2355
|
+
};
|
|
2356
|
+
}
|
|
2357
|
+
async function runSeoPlanCommand(action, input, client) {
|
|
2358
|
+
if (!action || !['show', 'generate', 'write', 'dismiss'].includes(action))
|
|
2359
|
+
throw new Error(SEO_PLAN_USAGE);
|
|
2360
|
+
if (action === 'show') {
|
|
2361
|
+
const kind = (getString(input.values, 'kind') ?? 'post').trim().toLowerCase().replace(/-/g, '_');
|
|
2362
|
+
if (!SEO_PLAN_KINDS.includes(kind)) {
|
|
2363
|
+
throw new Error(`--kind must be one of ${SEO_PLAN_KINDS.join(', ')}. Run \`coauthor seo-plan --help\` for usage.`);
|
|
2364
|
+
}
|
|
2365
|
+
const limit = getString(input.values, 'limit');
|
|
2366
|
+
if (limit !== undefined && !/^[1-9]\d*$/.test(limit))
|
|
2367
|
+
throw new Error('--limit must be a whole number from 1 to 500. Run `coauthor seo-plan --help` for usage.');
|
|
2368
|
+
const profileId = await resolveProfileOption(input, client);
|
|
2369
|
+
const query = new URLSearchParams({ kind });
|
|
2370
|
+
for (const name of ['stage', 'chance', 'limit']) {
|
|
2371
|
+
const value = getString(input.values, name);
|
|
2372
|
+
if (value)
|
|
2373
|
+
query.set(name, value);
|
|
2374
|
+
}
|
|
2375
|
+
const data = await client.request({ path: `profiles/${encodeURIComponent(profileId)}/seo-plan?${query.toString()}` });
|
|
2376
|
+
return { ok: true, message: seoPlanShowMessage(data, kind), messageIncludesData: true, data };
|
|
2377
|
+
}
|
|
2378
|
+
if (action === 'generate') {
|
|
2379
|
+
const adjust = getString(input.values, 'adjust');
|
|
2380
|
+
if (input.values.adjust !== undefined && !adjust?.trim())
|
|
2381
|
+
throw new Error('--adjust needs text, for example --adjust "focus on B2B buyers". Run `coauthor seo-plan --help` for usage.');
|
|
2382
|
+
if (adjust && adjust.length > 2000)
|
|
2383
|
+
throw new Error('--adjust can be at most 2000 characters.');
|
|
2384
|
+
const wait = getBoolean(input.values, 'wait');
|
|
2385
|
+
const profileId = await resolveProfileOption(input, client);
|
|
2386
|
+
const idempotencyKey = getString(input.values, 'idempotency-key')?.trim() || randomUUID();
|
|
2387
|
+
let started;
|
|
2388
|
+
try {
|
|
2389
|
+
started = await client.request({
|
|
2390
|
+
method: 'POST',
|
|
2391
|
+
path: `profiles/${encodeURIComponent(profileId)}/seo-plan`,
|
|
2392
|
+
body: adjust?.trim() ? { adjustments: adjust.trim() } : {},
|
|
2393
|
+
idempotencyKey,
|
|
2394
|
+
});
|
|
2395
|
+
}
|
|
2396
|
+
catch (error) {
|
|
2397
|
+
// One plan runs per account at a time. When --wait finds this profile's plan already running
|
|
2398
|
+
// (an earlier --wait timed out), join it instead of failing.
|
|
2399
|
+
if (wait && httpErrorCode(error) === 'plan_running') {
|
|
2400
|
+
const status = planRecord(await client.request({ path: `profiles/${encodeURIComponent(profileId)}/seo-plan/status` }));
|
|
2401
|
+
if (status.done === false)
|
|
2402
|
+
return waitForSeoPlan(client, profileId, null);
|
|
2403
|
+
}
|
|
2404
|
+
throw error;
|
|
2405
|
+
}
|
|
2406
|
+
const estimate = getResponseNumber(started, 'estimate_credits');
|
|
2407
|
+
const queued = `Plan queued${estimate ? ` (about ${estimate} credits, charged as it runs)` : ''}. It takes about 5 to 12 minutes.`;
|
|
2408
|
+
if (!wait) {
|
|
2409
|
+
return {
|
|
2410
|
+
ok: true,
|
|
2411
|
+
message: `${queued} Follow it with \`coauthor seo-plan generate --profile ${profileId} --wait\` or \`coauthor seo-plan show --profile ${profileId}\`.`,
|
|
2412
|
+
idempotency_key: idempotencyKey,
|
|
2413
|
+
data: started,
|
|
2414
|
+
};
|
|
2415
|
+
}
|
|
2416
|
+
const result = await waitForSeoPlan(client, profileId, started);
|
|
2417
|
+
return { ...result, idempotency_key: idempotencyKey };
|
|
2418
|
+
}
|
|
2419
|
+
const itemId = input.positionals[0];
|
|
2420
|
+
if (action === 'write') {
|
|
2421
|
+
if (!itemId)
|
|
2422
|
+
throw new Error('Usage: coauthor seo-plan write <item-id>');
|
|
2423
|
+
const data = await client.request({ method: 'POST', path: `seo-plan/items/${encodeURIComponent(itemId)}/write`, body: {} });
|
|
2424
|
+
const projectId = getResponseString(data, 'project_id') ?? '';
|
|
2425
|
+
const startPrompt = getResponseString(data, 'start_prompt');
|
|
2426
|
+
return {
|
|
2427
|
+
ok: true,
|
|
2428
|
+
message: [
|
|
2429
|
+
`${getResponseValue(data, 'created') === true ? 'Created' : 'Already created'} project ${projectId} for this idea.`,
|
|
2430
|
+
startPrompt ? `Start prompt: ${startPrompt}` : null,
|
|
2431
|
+
`The project is already set up from the plan (keyword, format, product placement, linked posts). Continue with the normal project flow: \`coauthor workflow run ${projectId} --target outline --wait\`, review the outline, then research and draft.`,
|
|
2432
|
+
].filter(Boolean).join('\n'),
|
|
2433
|
+
messageIncludesData: true,
|
|
2434
|
+
data,
|
|
2435
|
+
};
|
|
2436
|
+
}
|
|
2437
|
+
if (!itemId)
|
|
2438
|
+
throw new Error('Usage: coauthor seo-plan dismiss <item-id> [--undo]');
|
|
2439
|
+
const undo = getBoolean(input.values, 'undo');
|
|
2440
|
+
const data = await client.request({
|
|
2441
|
+
method: 'POST',
|
|
2442
|
+
path: `seo-plan/items/${encodeURIComponent(itemId)}/dismiss`,
|
|
2443
|
+
body: { dismissed: !undo },
|
|
2444
|
+
});
|
|
2445
|
+
return {
|
|
2446
|
+
ok: true,
|
|
2447
|
+
message: undo
|
|
2448
|
+
? `Restored ${itemId} to the plan.`
|
|
2449
|
+
: `Hid ${itemId} from the plan. Bring it back with \`coauthor seo-plan dismiss ${itemId} --undo\`.`,
|
|
2450
|
+
messageIncludesData: true,
|
|
2451
|
+
data,
|
|
2452
|
+
};
|
|
2453
|
+
}
|
|
1938
2454
|
const SOURCE_TYPES = { pdf: 'application/pdf', txt: 'text/plain', md: 'text/markdown', markdown: 'text/markdown' };
|
|
1939
2455
|
// Mirrors the server: base64 over the API caps PDFs at ~3.3 MB; text at 512 KB.
|
|
1940
2456
|
const MAX_SOURCE_PDF_BYTES = 3_300_000;
|
|
@@ -2732,8 +3248,10 @@ export function helpResult(command = []) {
|
|
|
2732
3248
|
' research-plan show|generate|revise|save|approve',
|
|
2733
3249
|
' repurpose list|generate|show|save|status|render|download',
|
|
2734
3250
|
' brief review|answer',
|
|
2735
|
-
' profile list|show',
|
|
3251
|
+
' profile list|show|update (update: --interactive-widgets on|off)',
|
|
3252
|
+
' widgets list|status|build|build-all|use-image|edit|delete (interactives, beta)',
|
|
2736
3253
|
' site status|reindex [--profile <profile-id>] (limited rollout)',
|
|
3254
|
+
' seo-plan show|generate|write|dismiss (limited rollout)',
|
|
2737
3255
|
' source list|add|remove',
|
|
2738
3256
|
' integrations list',
|
|
2739
3257
|
' log add|show',
|
|
@@ -2803,15 +3321,32 @@ function commandHelp(command) {
|
|
|
2803
3321
|
'',
|
|
2804
3322
|
'Requires project_state "research_structured". If research is still running or structuring, inspect the returned status and next commands.',
|
|
2805
3323
|
].join('\n'),
|
|
3324
|
+
widgets: [
|
|
3325
|
+
'Usage: coauthor widgets list <project-id> [--wait] [--json]',
|
|
3326
|
+
' coauthor widgets status <project-id> <widget-id> [--wait] [--json]',
|
|
3327
|
+
' coauthor widgets build <project-id> <widget-id> [--wait] [--json]',
|
|
3328
|
+
' coauthor widgets build-all <project-id> [<widget-id>...] [--wait] [--json]',
|
|
3329
|
+
' coauthor widgets use-image <project-id> <widget-id> [--json]',
|
|
3330
|
+
' coauthor widgets edit <project-id> <widget-id> --instruction "..." --yes [--wait] [--json]',
|
|
3331
|
+
' coauthor widgets delete <project-id> <widget-id> --yes [--json]',
|
|
3332
|
+
'',
|
|
3333
|
+
'Interactives (beta) are small interactive figures that drafts plan as placeholders when the profile has interactives on. list shows each one: id, title, aha, move, picture, credit cap, whether it replaces an image, and its state.',
|
|
3334
|
+
'Building spends credits (about 55 with Claude Opus 5.5, 35 with Claude Sonnet 5.5; an edit costs 0.75x; failed builds are free). Show the placeholders to the user and get their OK before build or build-all.',
|
|
3335
|
+
'build-all without ids builds every placeholder. --wait follows the builds for up to 9 minutes, then prints still_running (exit 2) with the command to resume.',
|
|
3336
|
+
'use-image swaps a placeholder that took over an image back to that image placeholder, and updates the draft.',
|
|
3337
|
+
'edit and delete change every published copy of the interactive, so they need --yes. delete cannot be undone.',
|
|
3338
|
+
'Needs the interactives beta (widgets_not_enabled otherwise), an active plan, and enough credits (widget_credit_cap_exceeds_balance) or, with your own keys, an Anthropic key (widget_requires_anthropic_key).',
|
|
3339
|
+
].join('\n'),
|
|
2806
3340
|
'models list': [
|
|
2807
3341
|
'Usage: coauthor models list [--json]',
|
|
2808
3342
|
'',
|
|
2809
3343
|
'Lists user-visible planning and writing model IDs for --planning-model and --writing-model.',
|
|
2810
3344
|
].join('\n'),
|
|
2811
3345
|
'models preferences': [
|
|
2812
|
-
'Usage: coauthor models preferences <show|set> [--planning-model <id>] [--writing-model <id>] [--json]',
|
|
3346
|
+
'Usage: coauthor models preferences <show|set> [--planning-model <id>] [--writing-model <id>] [--widget-model <id>] [--json]',
|
|
2813
3347
|
'',
|
|
2814
3348
|
'Shows or updates saved primary planning/writing model preferences while preserving fallback order.',
|
|
3349
|
+
'--widget-model (interactives beta) picks the model that builds interactives: claude-opus-5-5 (default) or claude-sonnet-5-5.',
|
|
2815
3350
|
].join('\n'),
|
|
2816
3351
|
'draft get': [
|
|
2817
3352
|
'Usage: coauthor draft get <project-id> [--format json|markdown|html|text] [--frontmatter] [--json]',
|
|
@@ -2836,6 +3371,7 @@ function commandHelp(command) {
|
|
|
2836
3371
|
profile: [
|
|
2837
3372
|
'Usage: coauthor profile list [--json]',
|
|
2838
3373
|
' coauthor profile show <profile-id> [--json]',
|
|
3374
|
+
' coauthor profile update <profile-id> --interactive-widgets on|off [--json] (interactives beta)',
|
|
2839
3375
|
'',
|
|
2840
3376
|
'Writer profiles hold the voice, writer and business context, and visual style. New projects use the default (most recently used) profile unless you pass --profile to project create. A project keeps its profile for good.',
|
|
2841
3377
|
].join('\n'),
|
|
@@ -2847,6 +3383,19 @@ function commandHelp(command) {
|
|
|
2847
3383
|
'status shows the website, its index status (pending, indexing, ready, blocked, failed) and how many pages are indexed. Without --profile it uses the default profile.',
|
|
2848
3384
|
'reindex starts a fresh read (free). It answers already_indexing during a crawl and reindex_too_soon within 15 minutes of the last one; no_website when the profile has no website.',
|
|
2849
3385
|
].join('\n'),
|
|
3386
|
+
'seo-plan': [
|
|
3387
|
+
'Usage: coauthor seo-plan show [--profile <profile-id>] [--kind post|improve|page|left_out|covered|not_checked] [--stage ready-to-buy|comparing|learning] [--chance easy|stretch|long-shot] [--limit <n>] [--json]',
|
|
3388
|
+
' coauthor seo-plan generate [--profile <profile-id>] [--adjust "<text>"] [--wait] [--json]',
|
|
3389
|
+
' coauthor seo-plan write <item-id> [--json]',
|
|
3390
|
+
' coauthor seo-plan dismiss <item-id> [--undo] [--json]',
|
|
3391
|
+
'',
|
|
3392
|
+
'SEO content plan (limited rollout): a business-wide keyword plan for a writer profile, built from live search data and the profile\'s website. Without --profile it uses the default profile.',
|
|
3393
|
+
'show prints the strategy, the Do next moves, counts per kind, and the ideas of one kind (default post). Kinds: post (written post ideas), improve (existing pages to improve), page (page ideas, not blog posts), left_out (searches skipped, with a reason), covered, not_checked.',
|
|
3394
|
+
'generate makes or updates the plan (about 420 credits, most plans 300-500, charged as it runs; the account needs 500 credits remaining to start). --adjust gives a one-line steer. --wait polls for up to 9 minutes, then exits 2 with still_running; run the same command again to keep waiting.',
|
|
3395
|
+
'write <item-id> opens a project for a post idea, already set up from the plan, and prints its id and the start prompt. Continue with the normal project flow. Writing the same idea again returns the same project.',
|
|
3396
|
+
'dismiss hides an idea from the plan; --undo brings it back.',
|
|
3397
|
+
'Errors: not_enabled, profile_not_found, profile_archived, site_required, site_indexing, market_confirmation_needed, market_not_supported, insufficient_credits, plan_running, worker_unavailable, plan_stale, plan_updated, not_writable, plan_item_not_found.',
|
|
3398
|
+
].join('\n'),
|
|
2850
3399
|
integrations: [
|
|
2851
3400
|
'Usage: coauthor integrations list [--json]',
|
|
2852
3401
|
'',
|
package/dist/parser.js
CHANGED
|
@@ -66,6 +66,8 @@ const OPTIONS = {
|
|
|
66
66
|
'execution-token': { type: 'string' },
|
|
67
67
|
'planning-model': { type: 'string' },
|
|
68
68
|
'writing-model': { type: 'string' },
|
|
69
|
+
'widget-model': { type: 'string' },
|
|
70
|
+
'interactive-widgets': { type: 'string' },
|
|
69
71
|
'alt-text': { type: 'string' },
|
|
70
72
|
description: { type: 'string' },
|
|
71
73
|
'file-slug': { type: 'string' },
|
|
@@ -81,6 +83,9 @@ const OPTIONS = {
|
|
|
81
83
|
variant: { type: 'string' },
|
|
82
84
|
all: { type: 'boolean', default: false },
|
|
83
85
|
kind: { type: 'string' },
|
|
86
|
+
chance: { type: 'string' },
|
|
87
|
+
adjust: { type: 'string' },
|
|
88
|
+
undo: { type: 'boolean', default: false },
|
|
84
89
|
apply: { type: 'boolean', default: false },
|
|
85
90
|
accept: { type: 'string' },
|
|
86
91
|
reject: { type: 'string' },
|
|
@@ -177,9 +182,13 @@ function commandLength(positionals) {
|
|
|
177
182
|
if (first === 'log')
|
|
178
183
|
return second && ['add', 'show'].includes(second) ? 2 : 1;
|
|
179
184
|
if (first === 'profile')
|
|
180
|
-
return second && ['list', 'show'].includes(second) ? 2 : 1;
|
|
185
|
+
return second && ['list', 'show', 'update'].includes(second) ? 2 : 1;
|
|
186
|
+
if (first === 'widgets')
|
|
187
|
+
return second && ['list', 'status', 'build', 'build-all', 'use-image', 'edit', 'delete'].includes(second) ? 2 : 1;
|
|
181
188
|
if (first === 'site')
|
|
182
189
|
return second && ['status', 'reindex'].includes(second) ? 2 : 1;
|
|
190
|
+
if (first === 'seo-plan')
|
|
191
|
+
return second && ['show', 'generate', 'write', 'dismiss'].includes(second) ? 2 : 1;
|
|
183
192
|
if (first === 'integrations')
|
|
184
193
|
return second === 'list' ? 2 : 1;
|
|
185
194
|
if (first === 'source')
|
package/package.json
CHANGED
package/skills/coauthor/SKILL.md
CHANGED
|
@@ -19,7 +19,7 @@ You drive it with the `coauthor` CLI. CoAuthor does the writing. **You are the u
|
|
|
19
19
|
|
|
20
20
|
- Always pass `--json` and read fields from the output. Failures arrive on stderr as JSON with `code`, `http_status`, and `details`.
|
|
21
21
|
- Keep each foreground command under your shell's time limit (Claude Code: 10 minutes). Prefix waiting commands with `COAUTHOR_CLI_WAIT_TIMEOUT_MS=540000`. If a command returns `timed_out` or `still_running`, run the resume or show command it gives you. Never start the same step twice.
|
|
22
|
-
- Get the user's explicit yes before anything public or live: `share` (creates a public link), `export … --yes`, `publish … --yes`.
|
|
22
|
+
- Get the user's explicit yes before anything public or live: `share` (creates a public link), `export … --yes`, `publish … --yes`. Also before building or editing interactives (`widgets build`, `build-all`, `edit`, `delete`): they spend credits, and edit and delete change published posts.
|
|
23
23
|
- Every blocked or paused status says what to do next. Follow it instead of retrying (see "When something stops").
|
|
24
24
|
- Once a draft exists, do not save, generate, or approve the brief, outline, or research plan unless the user wants to restart the piece: that marks the draft stale. Edit the draft instead.
|
|
25
25
|
- Never send markdown to `draft save`.
|
|
@@ -37,7 +37,7 @@ Typical timing: brief and outline under a minute; research and draft 3–10 minu
|
|
|
37
37
|
4. **Research-plan checkpoint.** `coauthor research-plan generate <id> --json` (tasks in `data.research_tasks`). Check every section has a task, every claim that needs proof points at the right sources (including URLs the user gave you), and deep research is used only where it matters. Fix it with `coauthor research-plan revise <id> --feedback "Add a task for the checklist section. Use https://… as a required source for the limits section." --json` and check `data.diff`, then `coauthor research-plan approve <id> --json` and log it.
|
|
38
38
|
5. **Research and draft.** `COAUTHOR_CLI_WAIT_TIMEOUT_MS=540000 coauthor workflow run <id> --target draft --wait --json`. It is done when the message says the draft completed (`data.draft_status.project_state` is `draft_generated`); ignore the stale `data.workflow.status`. On `timed_out`: `coauthor workflow resume <id> --target draft --wait --json`.
|
|
39
39
|
6. **Quality pass.** `coauthor draft get <id> --format markdown --json` and read `data.markdown` in full. Check it against the brief's must-include, must-avoid, and non-negotiables. Look for: notes about the research process ("the retrieved sources do not…"), invented "checked <date>" lines, numbered lists that restart at 1, garbled `*`, `_`, or code spans, literal `[ ]` in checklists, the same caveat repeated across sections, claims without a source or cited to a page that doesn't support them, contradictions, and a messy Sources list (generic titles like "Google", duplicate entries). Fix them in step 8.
|
|
40
|
-
7. **Images.** `coauthor image generate <id> --all --wait --json` generates every planned image and waits for them (one image: `coauthor image generate <id> --placeholder-id <placeholder id> --json`, using the `id` UUID from `image list`). CoAuthor decides how many images a draft gets, sometimes only the featured image; the CLI can't add more, so tell the user if they expected several. Open each image and check it does not state numbers or claims the article does not make, then rewrite its alt text to match what is actually visible (the stored alt text describes the plan, not the result). See `references/images-and-social.md`.
|
|
40
|
+
7. **Images.** `coauthor image generate <id> --all --wait --json` generates every planned image and waits for them (one image: `coauthor image generate <id> --placeholder-id <placeholder id> --json`, using the `id` UUID from `image list`). CoAuthor decides how many images a draft gets, sometimes only the featured image; the CLI can't add more, so tell the user if they expected several. Open each image and check it does not state numbers or claims the article does not make, then rewrite its alt text to match what is actually visible (the stored alt text describes the plan, not the result). See `references/images-and-social.md`. If the draft has interactive placeholders (beta), show them to the user and get a yes before building: `references/interactive-widgets.md`.
|
|
41
41
|
8. **Edits.** For prose changes: `coauthor draft revise <id> --instruction "..." --wait --json` (be specific: name the section and give a number, such as "cut the intro to under 60 words"), review each group's `before_markdown` and `after_markdown`, then `coauthor draft revision apply <id> <revision-id> --json` (optionally `--accept` or `--reject` with ids copied from `data.groups[].id`) or `coauthor draft revision discard <id> <revision-id> --json`. For exact text you already have, edit the document JSON and `draft save`. See `references/editing-drafts.md`.
|
|
42
42
|
9. **Deliver.** Give the user the final markdown (or `--format html`), the decision log (`coauthor log show <id> --json`: what you approved, what you asked CoAuthor to change, what you assumed), and the credits used (`coauthor credits <id> --json`). The user also sees the log in the project's workspace in the web app. With their yes: share link or WordPress export (`references/publishing-and-export.md`). For social posts and an email newsletter, `coauthor repurpose generate <id> --format all --json`, review `data.copy`, and `coauthor repurpose download <id> --out <dir>` (`references/repurposing.md`).
|
|
43
43
|
|
|
@@ -61,10 +61,21 @@ Typical timing: brief and outline under a minute; research and draft 3–10 minu
|
|
|
61
61
|
|
|
62
62
|
Everything else, including auth problems: `references/troubleshooting.md`. Credits, plans, and models: `references/credits-and-plans.md`.
|
|
63
63
|
|
|
64
|
+
## SEO content plan (limited rollout)
|
|
65
|
+
|
|
66
|
+
When the user wants to know what to write about for a business site, or asks for a keyword or content strategy, make a plan instead of guessing topics. A plan reads live search data and the profile's website, then lists post ideas that can win, pages to improve, and page ideas that are not blog posts.
|
|
67
|
+
|
|
68
|
+
- `coauthor seo-plan generate --wait --json` makes it: about 420 credits (most plans 300–500) and 5–12 minutes. Tell the user the cost first. After 9 minutes it exits 2 with `still_running`; run the same command again to keep waiting.
|
|
69
|
+
- `coauthor seo-plan show --json` reads it (strategy, Do next moves, counts, `--kind post|improve|page|left_out|covered|not_checked`).
|
|
70
|
+
- `coauthor seo-plan write <item-id> --json` opens a project for a `post` idea, already set up from the plan; continue with `workflow run <project-id> --target outline` as usual. Only `post` items are writable: `improve` items are edits to a page the site already has, and `page` items are site tasks.
|
|
71
|
+
- `coauthor seo-plan dismiss <item-id> [--undo] --json` hides an idea the user rules out.
|
|
72
|
+
|
|
73
|
+
Details, item fields, and what each kind means: `references/seo-content-plan.md`. If a command answers `not_enabled`, the account is outside the rollout; carry on without a plan.
|
|
74
|
+
|
|
64
75
|
## Housekeeping
|
|
65
76
|
|
|
66
77
|
`coauthor project rename <id> --title "..."` renames a project. `coauthor project duplicate <id> [--title "..."]` copies it with its brief, outline, research, draft, images, and posts (keeping its profile), for example to try a different angle without losing the original. `coauthor project delete <id> --yes` deletes it permanently, so only do it when the user asks, or for a test project you created yourself.
|
|
67
78
|
|
|
68
79
|
## Not in the CLI yet
|
|
69
80
|
|
|
70
|
-
Creating or editing
|
|
81
|
+
Creating writer profiles or editing a profile's voice and contexts (only the interactives switch can be set from the CLI), PDFs over about 3.3 MB, adding more images than CoAuthor planned, and correcting an SEO content plan's competitor list. Point the user to the CoAuthor web app at https://tools.clickminded.com/coauthor for these instead of improvising.
|
|
@@ -9,6 +9,7 @@ Rough costs, to set expectations before starting:
|
|
|
9
9
|
- A complete article (brief through draft) is typically about 300 credits.
|
|
10
10
|
- Images and extra rework rounds (regenerating, many revisions) drive cost more than word count does.
|
|
11
11
|
- Adding the repurposed formats in the web app (social posts, newsletter, slideshow) adds roughly 100–150 more.
|
|
12
|
+
- An SEO content plan (`coauthor seo-plan generate`) is about 420 credits (most plans 300–500) and needs 500 remaining to start. See `references/seo-content-plan.md`.
|
|
12
13
|
|
|
13
14
|
Tell the user the expected cost before large or repeated work, and report credits used at the end.
|
|
14
15
|
|
|
@@ -24,3 +25,4 @@ Paused work is saved. Resume it with `coauthor workflow resume <id> --wait --jso
|
|
|
24
25
|
- `coauthor models list` shows the planning and writing models available.
|
|
25
26
|
- Override for one run with `--planning-model <id>` (outline, research plan) and `--writing-model <id>` (draft, thread). There is no global `--model`.
|
|
26
27
|
- `coauthor models preferences show` and `coauthor models preferences set --planning-model <id> --writing-model <id>` read and change the saved defaults. Only change saved defaults when the user asks.
|
|
28
|
+
- Interactives (beta, rollout only) have their own model: `--widget-model claude-opus-5-5` (default, about 55 credits per build) or `claude-sonnet-5-5` (about 35). See `references/interactive-widgets.md`.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Interactives (beta)
|
|
2
|
+
|
|
3
|
+
An interactive is a small figure the reader can play with (a slider, a toggle, a calculator, a clickable diagram) that explains one idea from the article. It is built by AI, hosted by CoAuthor, and embedded in the published post. It is a beta feature, so it only exists for accounts in the rollout: every command here answers `widgets_not_enabled` otherwise.
|
|
4
|
+
|
|
5
|
+
## How it works
|
|
6
|
+
|
|
7
|
+
1. **Planning is free.** When interactives are on for the writer profile, a new draft plans placeholders (at most one per section). A placeholder is an `interactiveWidget` node in the draft with an idea (title, aha, move, picture). Nothing is built or charged yet. Turn the switch on for a profile with `coauthor profile update <profile-id> --interactive-widgets on` before drafting; existing drafts do not get interactives.
|
|
8
|
+
2. **Building spends credits.** `coauthor widgets build` is the paid step: about 55 credits with Claude Opus 5.5 (the default) or 35 with Claude Sonnet 5.5. An edit costs 0.75 of that (about 42 or 27). Those are caps, a build often costs less, and a build that fails costs nothing.
|
|
9
|
+
3. **Show the placeholders to the user first.** The same rule as the web app: list them, tell the user what each one shows and the total cost, and build only after their yes. Never run `build-all` as part of a flow the user did not approve.
|
|
10
|
+
|
|
11
|
+
## Commands
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
coauthor widgets list <project-id> [--wait] --json
|
|
15
|
+
coauthor widgets status <project-id> <widget-id> [--wait] --json
|
|
16
|
+
coauthor widgets build <project-id> <widget-id> [--wait] --json
|
|
17
|
+
coauthor widgets build-all <project-id> [<widget-id>...] [--wait] --json
|
|
18
|
+
coauthor widgets use-image <project-id> <widget-id> --json
|
|
19
|
+
coauthor widgets edit <project-id> <widget-id> --instruction "..." --yes [--wait] --json
|
|
20
|
+
coauthor widgets delete <project-id> <widget-id> --yes --json
|
|
21
|
+
coauthor profile update <profile-id> --interactive-widgets on|off --json
|
|
22
|
+
coauthor models preferences set --widget-model claude-opus-5-5|claude-sonnet-5-5 --json
|
|
23
|
+
```
|
|
24
|
+
|
|
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 a few minutes. With `--wait` the command follows it for up to 9 minutes; on `still_running` run the `resume_command` it prints. Rebuilding a built widget works the same and costs credits again. Retries after a failure wait a minute (`widget_rate_limited`), and after 3 failed builds in a day the account must wait.
|
|
27
|
+
- `build-all` with no ids builds every placeholder; with ids, only those.
|
|
28
|
+
- `use-image` is for a placeholder that took over a planned image (`replaces_image: true`). It turns the node in the draft back into an image placeholder (it updates the draft for you); then generate it with `coauthor image generate <project-id> --placeholder-id <placeholder-id>`. If `document_updated` is false, the response says why. The call is safe to repeat.
|
|
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
|
+
- A built widget exports as its poster image linked to the live version in markdown and HTML (`draft get --format markdown`), and live in WordPress when the connection allows it.
|
|
31
|
+
|
|
32
|
+
## Limitations to tell the user
|
|
33
|
+
|
|
34
|
+
- **Subscription lapse:** if the CoAuthor subscription ends, the hosted interactives stop showing in published posts. (Delete or keep the linked poster images if that matters.)
|
|
35
|
+
- **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.
|
|
36
|
+
- **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.
|
|
37
|
+
- **Fact check:** a built widget may carry `fact_check_warning`. Show it to the user before publishing.
|
|
38
|
+
- Interactives never appear in unbuilt form: placeholders are left out of every export.
|
|
39
|
+
|
|
40
|
+
Error codes: `references/troubleshooting.md`.
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# SEO content plan (limited rollout)
|
|
2
|
+
|
|
3
|
+
A plan is a business-wide keyword strategy for one writer profile: what the site should publish, what to fix on pages it already has, and what to skip. It is built from live Google search data and the profile's website (so the profile needs a website that `coauthor site status` reports as `ready`). One plan per profile; making it again updates it.
|
|
4
|
+
|
|
5
|
+
Accounts outside the rollout get `not_enabled` from every `seo-plan` command. Carry on without a plan and pick topics yourself.
|
|
6
|
+
|
|
7
|
+
## When to use it
|
|
8
|
+
|
|
9
|
+
- The user asks what to write about, what their blog should cover, or which keyword to go after, and the topic is a business site, not a one-off essay.
|
|
10
|
+
- Before a batch of posts: a plan picks posts that can win for this site and orders them.
|
|
11
|
+
- Not for a post the user already has a topic for. Write it as usual (`project create`, optionally `--keyword`).
|
|
12
|
+
|
|
13
|
+
## Cost and timing
|
|
14
|
+
|
|
15
|
+
- A plan costs about 420 credits (most plans 300 to 500), charged as it runs, and takes about 5 to 12 minutes. `generate` prints an estimate; tell the user before you start, and get a yes if they have not asked for a plan.
|
|
16
|
+
- The account needs at least 500 credits remaining to start, otherwise `insufficient_credits` (nothing is spent).
|
|
17
|
+
- Reading the plan (`show`), writing from it, and dismissing ideas cost nothing. Writing a post from an idea then costs credits like any other piece.
|
|
18
|
+
- Only one plan runs per account at a time (`plan_running`).
|
|
19
|
+
|
|
20
|
+
## Commands
|
|
21
|
+
|
|
22
|
+
```
|
|
23
|
+
coauthor seo-plan generate [--profile <id>] [--adjust "<text>"] [--wait] --json
|
|
24
|
+
COAUTHOR_CLI_WAIT_TIMEOUT_MS=540000 coauthor seo-plan generate --wait --json
|
|
25
|
+
coauthor seo-plan show [--profile <id>] [--kind post|improve|page|left_out|covered|not_checked] [--stage ready-to-buy|comparing|learning] [--chance easy|stretch|long-shot] [--limit <n>] --json
|
|
26
|
+
coauthor seo-plan write <item-id> --json
|
|
27
|
+
coauthor seo-plan dismiss <item-id> [--undo] --json
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
- Without `--profile` the default profile is used. Run `coauthor profile list --json` first when the user has several profiles and the request names a site or brand.
|
|
31
|
+
- `generate` returns at once with `data.plan_id` and `data.estimate_credits`. With `--wait` it polls until the plan is ready. After 9 minutes it exits with code 2 and `still_running`; run the same `generate ... --wait` command again to keep waiting (it joins the running plan; it does not start a second one).
|
|
32
|
+
- `--adjust` is a short steer for this run, for example `--adjust "focus on B2B buyers, skip anything about hiring"`. Use it when the user wants a different emphasis. Competitors are found automatically; the user corrects them in the web app.
|
|
33
|
+
- `show` returns `data.plan` (`strategy_line`, `competitors_line`, `status`), `data.do_next` (the five best next moves), `data.counts_by_kind`, and `data.items` for one `--kind` (default `post`). Items are sorted as the web app shows them.
|
|
34
|
+
- A plan run that fails says why in `data.error_code` and `data.error_message` (see `references/troubleshooting.md`). Credits for a failed run are only charged for work that finished.
|
|
35
|
+
|
|
36
|
+
## Reading the plan
|
|
37
|
+
|
|
38
|
+
Each item has a `kind`, which decides what you can do with it:
|
|
39
|
+
|
|
40
|
+
| `kind` | What it is | What to do |
|
|
41
|
+
| --- | --- | --- |
|
|
42
|
+
| `post` | A blog post idea that can rank. | **Write this**: `coauthor seo-plan write <item-id>`. |
|
|
43
|
+
| `improve` | The site already has a page for this search (`existing_url`, `existing_position`). | **Improve this page**: do not write a new post (it would compete with the old one). Tell the user what `improve_hint` says; the edit happens on their site. |
|
|
44
|
+
| `page` | The search wants a product, pricing, landing, category or tool page, not an article. | **Page idea**: not a blog post and not writable. Give it to the user as a site task (`page_kind` says what kind). |
|
|
45
|
+
| `left_out` | A search the plan skipped, with the `reason` (another brand's name, the wrong meaning, videos or forums only, and so on). | Nothing. Mention it only if the user asks why something is missing. |
|
|
46
|
+
| `covered` | The site already ranks well for it. | Nothing. |
|
|
47
|
+
| `not_checked` | Ideas the plan did not have budget to check. | Optional; a later update may check them. |
|
|
48
|
+
|
|
49
|
+
Other fields to use when you recommend an idea:
|
|
50
|
+
|
|
51
|
+
- `stage`: `Ready to buy`, `Comparing options` or `Learning`. It sets how strong the post's call to action is.
|
|
52
|
+
- `chance`: `Easy for you`, `Stretch` or `Long shot`, relative to this site, with `chance_reason` naming the domains that are beatable or stronger. Quote that reason; never describe a Stretch or Long shot idea as low difficulty. `core_kd` is the raw keyword difficulty, for detail only.
|
|
53
|
+
- `volume`: monthly searches for the idea and its related searches. `keywords` are the related searches the post also covers.
|
|
54
|
+
- `do_next_rank` (1 to 5) marks the plan's own top moves.
|
|
55
|
+
- Alternatives, comparison and best-of posts place the user's product on merit, as one fairly judged option with its limits, and carry a one-line disclosure ("We make <product>"). Competitor prices and features come from fetched pages and are dated. Do not ask CoAuthor to put the product first, and do not remove the disclosure in edits.
|
|
56
|
+
|
|
57
|
+
## Write this
|
|
58
|
+
|
|
59
|
+
`coauthor seo-plan write <item-id> --json` opens a project for a `post` item and returns `data.project_id`, `data.created` and `data.start_prompt`. The project is already set up from the plan: the keyword, the post format, where the product goes, the related searches, and the posts it should link to. You do not need a brief interview or a keyword step.
|
|
60
|
+
|
|
61
|
+
Continue with the normal flow from the project id: `coauthor workflow run <project-id> --target outline --wait --json`, review the outline as usual, approve it, then research and draft (see the main skill). The start prompt is the message the web app opens the chat with; you can use it as the post's working title and intent.
|
|
62
|
+
|
|
63
|
+
Writing the same idea twice returns the same project (`created: false`). It never makes a duplicate.
|
|
64
|
+
|
|
65
|
+
Errors: `plan_stale` (the profile's website or market changed; run `generate` to update the plan, then pick again), `plan_updated` (the plan was rebuilt and that idea no longer exists; run `show` for the current list), `not_writable` (the item is not a `post`), `plan_item_not_found`.
|
|
66
|
+
|
|
67
|
+
## Dismiss
|
|
68
|
+
|
|
69
|
+
`coauthor seo-plan dismiss <item-id> --json` hides an idea the user does not want (it leaves the counts and `show`). `--undo` brings it back. Use it when the user rules an idea out; do not dismiss on your own judgment.
|
|
70
|
+
|
|
71
|
+
## What to tell the user
|
|
72
|
+
|
|
73
|
+
Summarize rather than dump: the `strategy_line`, the Do next moves with their `chance` and why, and the counts. Offer to write the first one or two posts. Mention `improve` items separately, because they are quick wins on pages that already rank.
|
|
@@ -13,7 +13,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
13
13
|
| `research_running_stale` | Research progress has not changed for 30+ minutes. | Check `coauthor research status <id> --json` a few minutes apart and look at `coauthor research structured <id> --json`. Rewinding (`coauthor workflow rewind <id> --target research --json`) discards the research done so far and costs credits to redo, so ask the user first. |
|
|
14
14
|
| `research_run_state_mismatch` | Research run and project state disagree. | Report it and use the `recovery_commands` in the output. |
|
|
15
15
|
| `blocked_by_research` | A draft was requested while research is still running. | Use the `recovery_commands`; usually just resume toward draft. |
|
|
16
|
-
| `credits_exhausted` | The plan's credits for this period are used up. Work is paused and saved. | Tell the user `reset_at`, `used`, and `remaining`. Resume with `coauthor workflow resume <id> --wait --json` after the reset. See `references/credits-and-plans.md`. |
|
|
16
|
+
| `credits_exhausted` | The plan's credits for this period are used up. Work is paused and saved. A plan run that ran out of credits stops with this as its `error_code` (it is not resumable: run `seo-plan generate` again after the reset). | Tell the user `reset_at`, `used`, and `remaining`. Resume with `coauthor workflow resume <id> --wait --json` after the reset. See `references/credits-and-plans.md`. |
|
|
17
17
|
| `requires_key` | Included credits are used up and the plan can continue with the user's own AI provider key. | The user adds a key in CoAuthor's AI settings (`settings_url`); never ask for it in chat. Then run `resume_command`. |
|
|
18
18
|
| `byok_not_allowed` | The plan can't use provider keys. | Wait for the credit reset, or the user upgrades in CoAuthor. |
|
|
19
19
|
| `coauthor_access_required` | No active CoAuthor subscription on this account. | Tell the user. `coauthor auth status` still works. |
|
|
@@ -30,6 +30,16 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
30
30
|
| `workflow_token_mismatch`, `conflict` | The project moved on since you read it (for example someone used the web app). | Re-read the state with `coauthor workflow status <id> --json` and continue from there. |
|
|
31
31
|
| `insufficient_scope` | The token can't publish. | `coauthor auth login --with-publish`. |
|
|
32
32
|
| `wordpress_connection_required` | Several WordPress sites are connected. | Ask which one from `details.connections`, add `--connection-id`. |
|
|
33
|
+
| `widgets_not_enabled` | Interactives (beta) aren't enabled for this account, or the writer profile has them off. | Tell the user. If `details.reason` is `toggle_off`, turn them on with `coauthor profile update <profile-id> --interactive-widgets on` (new drafts only). |
|
|
34
|
+
| `widget_requires_anthropic_key` | Interactives need an Anthropic API key when the user builds with their own keys. | The user adds one in CoAuthor's AI settings; never ask for it in chat. |
|
|
35
|
+
| `widget_credit_cap_exceeds_balance` | Not enough credits left for a build (`details.credits_needed`). | Tell the user, check `coauthor credits`, and top up or wait for the reset. Try the cheaper model with `coauthor models preferences set --widget-model claude-sonnet-5-5` if they agree. |
|
|
36
|
+
| `widget_build_failed` | A build failed (`error.message` on the widget). Nothing was charged. | Retry `coauthor widgets build`; after repeated failures tell the user. |
|
|
37
|
+
| `widget_not_found` | No such interactive in this project (or it was deleted). | `coauthor widgets list <project-id>` for the current ids. |
|
|
38
|
+
| `widget_build_in_progress` | Only shown inside skipped lists: the interactive is already building. | Wait with `coauthor widgets status <project-id> <widget-id> --wait`. Building twice is never needed. |
|
|
39
|
+
| `widget_rate_limited` | A retry came within a minute, or 3 builds already failed today. | Wait and retry later; don't loop. |
|
|
40
|
+
| `widget_not_built` | `widgets edit` on a placeholder. | Build it first. |
|
|
41
|
+
| `widget_no_image_fallback` | `widgets use-image` on a widget that did not replace an image. | Delete it or build it instead. |
|
|
42
|
+
| `widgets_temporarily_unavailable` | Interactive building is paused on CoAuthor's side. | Try again later. |
|
|
33
43
|
| `feature_unavailable` | SEO features (`search-brief`, `project create --keyword` or `--seo`, `site`) aren't enabled for this account yet, or search data is temporarily unavailable. | Continue without a target keyword; the post is written as usual. |
|
|
34
44
|
| `no_website` | `site status`/`site reindex` on a profile with no website. | Ask the user to add their website to the profile in the web app. |
|
|
35
45
|
| `reindex_too_soon` | `site reindex` within 15 minutes of the last read. | Wait, or check `coauthor site status`. |
|
|
@@ -44,6 +54,29 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
44
54
|
| `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 "..."`. |
|
|
45
55
|
| `uploaded_image` | `image generate` on an image the user replaced with their own file. | Use `image edit --edit-prompt "..."`, or `image replace` again. |
|
|
46
56
|
| `not_a_panel` | `image replace` on an article image. | Only slideshow and video panels can be replaced from the CLI. |
|
|
57
|
+
| `not_enabled` | `seo-plan` commands on an account outside the SEO content plan rollout. | Carry on without a plan and choose topics yourself. |
|
|
58
|
+
| `profile_not_found` | `--profile` isn't one of the user's profiles. | `coauthor profile list --json` and use an `id` from it. |
|
|
59
|
+
| `profile_archived` | `seo-plan generate` on an archived profile. | Use another profile, or the user restores it in the web app. |
|
|
60
|
+
| `site_required` | `seo-plan generate` on a profile with no website. | Ask the user to add the website to the profile in the web app. |
|
|
61
|
+
| `site_indexing` | CoAuthor is still reading the profile's website. | Check `coauthor site status`; run `generate` again when it is `ready` (a few minutes). Nothing was spent. |
|
|
62
|
+
| `market_confirmation_needed` | CoAuthor can't tell which country's search results to plan for. | The user confirms the search country in the profile settings in the web app, then run `generate` again. Nothing was spent. |
|
|
63
|
+
| `market_not_supported` | Search data doesn't fully cover the profile's country and language. | Give the user `details.explanation.message` and its alternatives; they change the profile's country or language in the web app. Nothing was spent. |
|
|
64
|
+
| `insufficient_credits` | A plan needs at least 500 credits remaining (`details.required`, `details.remaining`). | Tell the user; resume after the reset (`coauthor credits --json`). Nothing was spent. |
|
|
65
|
+
| `plan_running` | A plan is already being made on this account (only one runs at a time). | `coauthor seo-plan generate --profile <id> --wait` joins the running plan for that profile; otherwise wait and use `seo-plan show`. |
|
|
66
|
+
| `worker_unavailable` | The plan service couldn't be reached. Nothing was spent. | Try again in a few minutes. |
|
|
67
|
+
| `dataforseo_busy` | A plan run stopped because the search data provider was busy (`seo-plan show` or the `--wait` result carries it as `error_code`). | Run `coauthor seo-plan generate --wait` again in a few minutes. Work already done is cached, so a retry costs less. |
|
|
68
|
+
| `dataforseo_failed` | A plan run couldn't get the search data it needs. | Retry in a few minutes. If it repeats, tell the user. |
|
|
69
|
+
| `backlinks_unavailable` | A plan run couldn't read backlink data for the site, which it needs to judge difficulty. Nothing was spent. | Try again later; don't retry in a loop. |
|
|
70
|
+
| `llm_failed` | One of the plan's writing steps didn't complete. | Retry `seo-plan generate --wait`; finished steps are reused. |
|
|
71
|
+
| `plan_cost_cap` | A plan run reached its spending limit and stopped; what was used was charged. | Tell the user. Retry with a narrower `--adjust` (for example one product line or audience). |
|
|
72
|
+
| `plan_timeout`, `lease_expired`, `internal` | A plan run took too long or stopped unexpectedly. | Retry `seo-plan generate --wait` once; if it fails again, report the `error_code` to the user. |
|
|
73
|
+
| `invalid_input`, `invalid_filter` | `--adjust` over 2,000 characters, bad competitors, or a bad `--kind`, `--stage`, `--chance` or `--limit`. | Fix the value (`coauthor seo-plan --help` lists them). |
|
|
74
|
+
| `coauthor_access_required`, `entitlement_sync_unavailable` | See above; they apply to `seo-plan` too. | As above. |
|
|
75
|
+
| `plan_stale` | `seo-plan write` on an idea from a plan built for a website or market the profile no longer has. | `coauthor seo-plan generate --wait --json` to update the plan, then pick an idea again. |
|
|
76
|
+
| `plan_updated` | `seo-plan write` on an idea that a newer plan run replaced. | `coauthor seo-plan show --json` for the current ideas. |
|
|
77
|
+
| `not_writable` | `seo-plan write` on an item that isn't a `post` idea (improve, page idea, left out, covered). | Only `post` items are written. Improve and page ideas are tasks on the user's site. |
|
|
78
|
+
| `plan_item_not_found` | `seo-plan write` or `dismiss` with an unknown item id. | Take the `id` from `seo-plan show --json`. |
|
|
79
|
+
| `operation_in_progress` | A `seo-plan generate` with the same `--idempotency-key` is still being processed. | Wait a moment and check `coauthor seo-plan show`. |
|
|
47
80
|
| `usage_error` | The command or its flags are wrong; nothing was sent. | Check `coauthor help <command>` and fix the command. |
|
|
48
81
|
| `request_timeout`, `network_error` | No answer from CoAuthor in time, or the connection failed. | For reads, retry. For exports, publishes, and image generate/edit, check `coauthor operation status <idempotency_key>` before retrying. |
|
|
49
82
|
|
|
@@ -21,7 +21,7 @@ You drive it with the `coauthor` CLI. CoAuthor does the writing. **You are the u
|
|
|
21
21
|
|
|
22
22
|
- Always pass `--json` and read fields from the output. Failures arrive on stderr as JSON with `code`, `http_status`, and `details`.
|
|
23
23
|
- Keep each foreground command under your shell's time limit (Claude Code: 10 minutes). Prefix waiting commands with `COAUTHOR_CLI_WAIT_TIMEOUT_MS=540000`. If a command returns `timed_out` or `still_running`, run the resume or show command it gives you. Never start the same step twice.
|
|
24
|
-
- Get the user's explicit yes before anything public or live: `share` (creates a public link), `export … --yes`, `publish … --yes`.
|
|
24
|
+
- Get the user's explicit yes before anything public or live: `share` (creates a public link), `export … --yes`, `publish … --yes`. Also before building or editing interactives (`widgets build`, `build-all`, `edit`, `delete`): they spend credits, and edit and delete change published posts.
|
|
25
25
|
- Every blocked or paused status says what to do next. Follow it instead of retrying (see "When something stops").
|
|
26
26
|
- Once a draft exists, do not save, generate, or approve the brief, outline, or research plan unless the user wants to restart the piece: that marks the draft stale. Edit the draft instead.
|
|
27
27
|
- Never send markdown to `draft save`.
|
|
@@ -39,7 +39,7 @@ Typical timing: brief and outline under a minute; research and draft 3–10 minu
|
|
|
39
39
|
4. **Research-plan checkpoint.** `coauthor research-plan generate <id> --json` (tasks in `data.research_tasks`). Check every section has a task, every claim that needs proof points at the right sources (including URLs the user gave you), and deep research is used only where it matters. Fix it with `coauthor research-plan revise <id> --feedback "Add a task for the checklist section. Use https://… as a required source for the limits section." --json` and check `data.diff`, then `coauthor research-plan approve <id> --json` and log it.
|
|
40
40
|
5. **Research and draft.** `COAUTHOR_CLI_WAIT_TIMEOUT_MS=540000 coauthor workflow run <id> --target draft --wait --json`. It is done when the message says the draft completed (`data.draft_status.project_state` is `draft_generated`); ignore the stale `data.workflow.status`. On `timed_out`: `coauthor workflow resume <id> --target draft --wait --json`.
|
|
41
41
|
6. **Quality pass.** `coauthor draft get <id> --format markdown --json` and read `data.markdown` in full. Check it against the brief's must-include, must-avoid, and non-negotiables. Look for: notes about the research process ("the retrieved sources do not…"), invented "checked <date>" lines, numbered lists that restart at 1, garbled `*`, `_`, or code spans, literal `[ ]` in checklists, the same caveat repeated across sections, claims without a source or cited to a page that doesn't support them, contradictions, and a messy Sources list (generic titles like "Google", duplicate entries). Fix them in step 8.
|
|
42
|
-
7. **Images.** `coauthor image generate <id> --all --wait --json` generates every planned image and waits for them (one image: `coauthor image generate <id> --placeholder-id <placeholder id> --json`, using the `id` UUID from `image list`). CoAuthor decides how many images a draft gets, sometimes only the featured image; the CLI can't add more, so tell the user if they expected several. Open each image and check it does not state numbers or claims the article does not make, then rewrite its alt text to match what is actually visible (the stored alt text describes the plan, not the result). See `references/images-and-social.md`.
|
|
42
|
+
7. **Images.** `coauthor image generate <id> --all --wait --json` generates every planned image and waits for them (one image: `coauthor image generate <id> --placeholder-id <placeholder id> --json`, using the `id` UUID from `image list`). CoAuthor decides how many images a draft gets, sometimes only the featured image; the CLI can't add more, so tell the user if they expected several. Open each image and check it does not state numbers or claims the article does not make, then rewrite its alt text to match what is actually visible (the stored alt text describes the plan, not the result). See `references/images-and-social.md`. If the draft has interactive placeholders (beta), show them to the user and get a yes before building: `references/interactive-widgets.md`.
|
|
43
43
|
8. **Edits.** For prose changes: `coauthor draft revise <id> --instruction "..." --wait --json` (be specific: name the section and give a number, such as "cut the intro to under 60 words"), review each group's `before_markdown` and `after_markdown`, then `coauthor draft revision apply <id> <revision-id> --json` (optionally `--accept` or `--reject` with ids copied from `data.groups[].id`) or `coauthor draft revision discard <id> <revision-id> --json`. For exact text you already have, edit the document JSON and `draft save`. See `references/editing-drafts.md`.
|
|
44
44
|
9. **Deliver.** Give the user the final markdown (or `--format html`), the decision log (`coauthor log show <id> --json`: what you approved, what you asked CoAuthor to change, what you assumed), and the credits used (`coauthor credits <id> --json`). The user also sees the log in the project's workspace in the web app. With their yes: share link or WordPress export (`references/publishing-and-export.md`). For social posts and an email newsletter, `coauthor repurpose generate <id> --format all --json`, review `data.copy`, and `coauthor repurpose download <id> --out <dir>` (`references/repurposing.md`).
|
|
45
45
|
|
|
@@ -63,13 +63,24 @@ Typical timing: brief and outline under a minute; research and draft 3–10 minu
|
|
|
63
63
|
|
|
64
64
|
Everything else, including auth problems: `references/troubleshooting.md`. Credits, plans, and models: `references/credits-and-plans.md`.
|
|
65
65
|
|
|
66
|
+
## SEO content plan (limited rollout)
|
|
67
|
+
|
|
68
|
+
When the user wants to know what to write about for a business site, or asks for a keyword or content strategy, make a plan instead of guessing topics. A plan reads live search data and the profile's website, then lists post ideas that can win, pages to improve, and page ideas that are not blog posts.
|
|
69
|
+
|
|
70
|
+
- `coauthor seo-plan generate --wait --json` makes it: about 420 credits (most plans 300–500) and 5–12 minutes. Tell the user the cost first. After 9 minutes it exits 2 with `still_running`; run the same command again to keep waiting.
|
|
71
|
+
- `coauthor seo-plan show --json` reads it (strategy, Do next moves, counts, `--kind post|improve|page|left_out|covered|not_checked`).
|
|
72
|
+
- `coauthor seo-plan write <item-id> --json` opens a project for a `post` idea, already set up from the plan; continue with `workflow run <project-id> --target outline` as usual. Only `post` items are writable: `improve` items are edits to a page the site already has, and `page` items are site tasks.
|
|
73
|
+
- `coauthor seo-plan dismiss <item-id> [--undo] --json` hides an idea the user rules out.
|
|
74
|
+
|
|
75
|
+
Details, item fields, and what each kind means: `references/seo-content-plan.md`. If a command answers `not_enabled`, the account is outside the rollout; carry on without a plan.
|
|
76
|
+
|
|
66
77
|
## Housekeeping
|
|
67
78
|
|
|
68
79
|
`coauthor project rename <id> --title "..."` renames a project. `coauthor project duplicate <id> [--title "..."]` copies it with its brief, outline, research, draft, images, and posts (keeping its profile), for example to try a different angle without losing the original. `coauthor project delete <id> --yes` deletes it permanently, so only do it when the user asks, or for a test project you created yourself.
|
|
69
80
|
|
|
70
81
|
## Not in the CLI yet
|
|
71
82
|
|
|
72
|
-
Creating or editing
|
|
83
|
+
Creating writer profiles or editing a profile's voice and contexts (only the interactives switch can be set from the CLI), PDFs over about 3.3 MB, adding more images than CoAuthor planned, and correcting an SEO content plan's competitor list. Point the user to the CoAuthor web app at https://tools.clickminded.com/coauthor for these instead of improvising.
|
|
73
84
|
|
|
74
85
|
# Reference sections
|
|
75
86
|
|
|
@@ -264,6 +275,7 @@ Rough costs, to set expectations before starting:
|
|
|
264
275
|
- A complete article (brief through draft) is typically about 300 credits.
|
|
265
276
|
- Images and extra rework rounds (regenerating, many revisions) drive cost more than word count does.
|
|
266
277
|
- Adding the repurposed formats in the web app (social posts, newsletter, slideshow) adds roughly 100–150 more.
|
|
278
|
+
- An SEO content plan (`coauthor seo-plan generate`) is about 420 credits (most plans 300–500) and needs 500 remaining to start. See `references/seo-content-plan.md`.
|
|
267
279
|
|
|
268
280
|
Tell the user the expected cost before large or repeated work, and report credits used at the end.
|
|
269
281
|
|
|
@@ -279,6 +291,7 @@ Paused work is saved. Resume it with `coauthor workflow resume <id> --wait --jso
|
|
|
279
291
|
- `coauthor models list` shows the planning and writing models available.
|
|
280
292
|
- Override for one run with `--planning-model <id>` (outline, research plan) and `--writing-model <id>` (draft, thread). There is no global `--model`.
|
|
281
293
|
- `coauthor models preferences show` and `coauthor models preferences set --planning-model <id> --writing-model <id>` read and change the saved defaults. Only change saved defaults when the user asks.
|
|
294
|
+
- Interactives (beta, rollout only) have their own model: `--widget-model claude-opus-5-5` (default, about 55 credits per build) or `claude-sonnet-5-5` (about 35). See `references/interactive-widgets.md`.
|
|
282
295
|
|
|
283
296
|
## references/editing-drafts.md
|
|
284
297
|
|
|
@@ -377,6 +390,49 @@ Images cost credits each time they are generated or edited, so check the brief a
|
|
|
377
390
|
|
|
378
391
|
X posts, LinkedIn, Facebook, and email newsletter versions: see `references/repurposing.md`. Carousel slideshows and short vertical videos: same file, under Slideshow and Video.
|
|
379
392
|
|
|
393
|
+
## references/interactive-widgets.md
|
|
394
|
+
|
|
395
|
+
## Interactives (beta)
|
|
396
|
+
|
|
397
|
+
An interactive is a small figure the reader can play with (a slider, a toggle, a calculator, a clickable diagram) that explains one idea from the article. It is built by AI, hosted by CoAuthor, and embedded in the published post. It is a beta feature, so it only exists for accounts in the rollout: every command here answers `widgets_not_enabled` otherwise.
|
|
398
|
+
|
|
399
|
+
### How it works
|
|
400
|
+
|
|
401
|
+
1. **Planning is free.** When interactives are on for the writer profile, a new draft plans placeholders (at most one per section). A placeholder is an `interactiveWidget` node in the draft with an idea (title, aha, move, picture). Nothing is built or charged yet. Turn the switch on for a profile with `coauthor profile update <profile-id> --interactive-widgets on` before drafting; existing drafts do not get interactives.
|
|
402
|
+
2. **Building spends credits.** `coauthor widgets build` is the paid step: about 55 credits with Claude Opus 5.5 (the default) or 35 with Claude Sonnet 5.5. An edit costs 0.75 of that (about 42 or 27). Those are caps, a build often costs less, and a build that fails costs nothing.
|
|
403
|
+
3. **Show the placeholders to the user first.** The same rule as the web app: list them, tell the user what each one shows and the total cost, and build only after their yes. Never run `build-all` as part of a flow the user did not approve.
|
|
404
|
+
|
|
405
|
+
### Commands
|
|
406
|
+
|
|
407
|
+
```
|
|
408
|
+
coauthor widgets list <project-id> [--wait] --json
|
|
409
|
+
coauthor widgets status <project-id> <widget-id> [--wait] --json
|
|
410
|
+
coauthor widgets build <project-id> <widget-id> [--wait] --json
|
|
411
|
+
coauthor widgets build-all <project-id> [<widget-id>...] [--wait] --json
|
|
412
|
+
coauthor widgets use-image <project-id> <widget-id> --json
|
|
413
|
+
coauthor widgets edit <project-id> <widget-id> --instruction "..." --yes [--wait] --json
|
|
414
|
+
coauthor widgets delete <project-id> <widget-id> --yes --json
|
|
415
|
+
coauthor profile update <profile-id> --interactive-widgets on|off --json
|
|
416
|
+
coauthor models preferences set --widget-model claude-opus-5-5|claude-sonnet-5-5 --json
|
|
417
|
+
```
|
|
418
|
+
|
|
419
|
+
- `list` returns `data.widgets` (each with `id`, `spec.title`, `spec.aha`, `spec.move`, `spec.visual`, `credit_cap`, `edit_credit_cap`, `replaces_image`, `build_state`, `current_version`, `embed_url`, and `error` when a build failed), `data.availability` (`canBuild` and the reason when not), and `data.model` (the build model and its cap). A placeholder has `current_version: null` and `build_state: "idle"`.
|
|
420
|
+
- `build` and `edit` queue the build and return at once (`already_running: true` if it was already building: calling again is safe). A build takes a few minutes. With `--wait` the command follows it for up to 9 minutes; on `still_running` run the `resume_command` it prints. Rebuilding a built widget works the same and costs credits again. Retries after a failure wait a minute (`widget_rate_limited`), and after 3 failed builds in a day the account must wait.
|
|
421
|
+
- `build-all` with no ids builds every placeholder; with ids, only those.
|
|
422
|
+
- `use-image` is for a placeholder that took over a planned image (`replaces_image: true`). It turns the node in the draft back into an image placeholder (it updates the draft for you); then generate it with `coauthor image generate <project-id> --placeholder-id <placeholder-id>`. If `document_updated` is false, the response says why. The call is safe to repeat.
|
|
423
|
+
- `edit` takes a plain instruction of up to 500 characters and rebuilds the widget. `edit` and `delete` change every published copy, so both need `--yes`: confirm with the user first. `delete` removes the interactive everywhere, including posts already published, and cannot be undone. It also removes the node from the draft.
|
|
424
|
+
- A built widget exports as its poster image linked to the live version in markdown and HTML (`draft get --format markdown`), and live in WordPress when the connection allows it.
|
|
425
|
+
|
|
426
|
+
### Limitations to tell the user
|
|
427
|
+
|
|
428
|
+
- **Subscription lapse:** if the CoAuthor subscription ends, the hosted interactives stop showing in published posts. (Delete or keep the linked poster images if that matters.)
|
|
429
|
+
- **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.
|
|
430
|
+
- **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.
|
|
431
|
+
- **Fact check:** a built widget may carry `fact_check_warning`. Show it to the user before publishing.
|
|
432
|
+
- Interactives never appear in unbuilt form: placeholders are left out of every export.
|
|
433
|
+
|
|
434
|
+
Error codes: `references/troubleshooting.md`.
|
|
435
|
+
|
|
380
436
|
## references/publishing-and-export.md
|
|
381
437
|
|
|
382
438
|
## Publishing and export
|
|
@@ -519,6 +575,82 @@ Hand the user the folder, or paste from `data.copy`.
|
|
|
519
575
|
|
|
520
576
|
Only X can be posted directly. A thread posts with `coauthor publish thread <id> --yes` after the user's explicit OK. LinkedIn, Facebook, and email are copy-and-paste.
|
|
521
577
|
|
|
578
|
+
## references/seo-content-plan.md
|
|
579
|
+
|
|
580
|
+
## SEO content plan (limited rollout)
|
|
581
|
+
|
|
582
|
+
A plan is a business-wide keyword strategy for one writer profile: what the site should publish, what to fix on pages it already has, and what to skip. It is built from live Google search data and the profile's website (so the profile needs a website that `coauthor site status` reports as `ready`). One plan per profile; making it again updates it.
|
|
583
|
+
|
|
584
|
+
Accounts outside the rollout get `not_enabled` from every `seo-plan` command. Carry on without a plan and pick topics yourself.
|
|
585
|
+
|
|
586
|
+
### When to use it
|
|
587
|
+
|
|
588
|
+
- The user asks what to write about, what their blog should cover, or which keyword to go after, and the topic is a business site, not a one-off essay.
|
|
589
|
+
- Before a batch of posts: a plan picks posts that can win for this site and orders them.
|
|
590
|
+
- Not for a post the user already has a topic for. Write it as usual (`project create`, optionally `--keyword`).
|
|
591
|
+
|
|
592
|
+
### Cost and timing
|
|
593
|
+
|
|
594
|
+
- A plan costs about 420 credits (most plans 300 to 500), charged as it runs, and takes about 5 to 12 minutes. `generate` prints an estimate; tell the user before you start, and get a yes if they have not asked for a plan.
|
|
595
|
+
- The account needs at least 500 credits remaining to start, otherwise `insufficient_credits` (nothing is spent).
|
|
596
|
+
- Reading the plan (`show`), writing from it, and dismissing ideas cost nothing. Writing a post from an idea then costs credits like any other piece.
|
|
597
|
+
- Only one plan runs per account at a time (`plan_running`).
|
|
598
|
+
|
|
599
|
+
### Commands
|
|
600
|
+
|
|
601
|
+
```
|
|
602
|
+
coauthor seo-plan generate [--profile <id>] [--adjust "<text>"] [--wait] --json
|
|
603
|
+
COAUTHOR_CLI_WAIT_TIMEOUT_MS=540000 coauthor seo-plan generate --wait --json
|
|
604
|
+
coauthor seo-plan show [--profile <id>] [--kind post|improve|page|left_out|covered|not_checked] [--stage ready-to-buy|comparing|learning] [--chance easy|stretch|long-shot] [--limit <n>] --json
|
|
605
|
+
coauthor seo-plan write <item-id> --json
|
|
606
|
+
coauthor seo-plan dismiss <item-id> [--undo] --json
|
|
607
|
+
```
|
|
608
|
+
|
|
609
|
+
- Without `--profile` the default profile is used. Run `coauthor profile list --json` first when the user has several profiles and the request names a site or brand.
|
|
610
|
+
- `generate` returns at once with `data.plan_id` and `data.estimate_credits`. With `--wait` it polls until the plan is ready. After 9 minutes it exits with code 2 and `still_running`; run the same `generate ... --wait` command again to keep waiting (it joins the running plan; it does not start a second one).
|
|
611
|
+
- `--adjust` is a short steer for this run, for example `--adjust "focus on B2B buyers, skip anything about hiring"`. Use it when the user wants a different emphasis. Competitors are found automatically; the user corrects them in the web app.
|
|
612
|
+
- `show` returns `data.plan` (`strategy_line`, `competitors_line`, `status`), `data.do_next` (the five best next moves), `data.counts_by_kind`, and `data.items` for one `--kind` (default `post`). Items are sorted as the web app shows them.
|
|
613
|
+
- A plan run that fails says why in `data.error_code` and `data.error_message` (see `references/troubleshooting.md`). Credits for a failed run are only charged for work that finished.
|
|
614
|
+
|
|
615
|
+
### Reading the plan
|
|
616
|
+
|
|
617
|
+
Each item has a `kind`, which decides what you can do with it:
|
|
618
|
+
|
|
619
|
+
| `kind` | What it is | What to do |
|
|
620
|
+
| --- | --- | --- |
|
|
621
|
+
| `post` | A blog post idea that can rank. | **Write this**: `coauthor seo-plan write <item-id>`. |
|
|
622
|
+
| `improve` | The site already has a page for this search (`existing_url`, `existing_position`). | **Improve this page**: do not write a new post (it would compete with the old one). Tell the user what `improve_hint` says; the edit happens on their site. |
|
|
623
|
+
| `page` | The search wants a product, pricing, landing, category or tool page, not an article. | **Page idea**: not a blog post and not writable. Give it to the user as a site task (`page_kind` says what kind). |
|
|
624
|
+
| `left_out` | A search the plan skipped, with the `reason` (another brand's name, the wrong meaning, videos or forums only, and so on). | Nothing. Mention it only if the user asks why something is missing. |
|
|
625
|
+
| `covered` | The site already ranks well for it. | Nothing. |
|
|
626
|
+
| `not_checked` | Ideas the plan did not have budget to check. | Optional; a later update may check them. |
|
|
627
|
+
|
|
628
|
+
Other fields to use when you recommend an idea:
|
|
629
|
+
|
|
630
|
+
- `stage`: `Ready to buy`, `Comparing options` or `Learning`. It sets how strong the post's call to action is.
|
|
631
|
+
- `chance`: `Easy for you`, `Stretch` or `Long shot`, relative to this site, with `chance_reason` naming the domains that are beatable or stronger. Quote that reason; never describe a Stretch or Long shot idea as low difficulty. `core_kd` is the raw keyword difficulty, for detail only.
|
|
632
|
+
- `volume`: monthly searches for the idea and its related searches. `keywords` are the related searches the post also covers.
|
|
633
|
+
- `do_next_rank` (1 to 5) marks the plan's own top moves.
|
|
634
|
+
- Alternatives, comparison and best-of posts place the user's product on merit, as one fairly judged option with its limits, and carry a one-line disclosure ("We make <product>"). Competitor prices and features come from fetched pages and are dated. Do not ask CoAuthor to put the product first, and do not remove the disclosure in edits.
|
|
635
|
+
|
|
636
|
+
### Write this
|
|
637
|
+
|
|
638
|
+
`coauthor seo-plan write <item-id> --json` opens a project for a `post` item and returns `data.project_id`, `data.created` and `data.start_prompt`. The project is already set up from the plan: the keyword, the post format, where the product goes, the related searches, and the posts it should link to. You do not need a brief interview or a keyword step.
|
|
639
|
+
|
|
640
|
+
Continue with the normal flow from the project id: `coauthor workflow run <project-id> --target outline --wait --json`, review the outline as usual, approve it, then research and draft (see the main skill). The start prompt is the message the web app opens the chat with; you can use it as the post's working title and intent.
|
|
641
|
+
|
|
642
|
+
Writing the same idea twice returns the same project (`created: false`). It never makes a duplicate.
|
|
643
|
+
|
|
644
|
+
Errors: `plan_stale` (the profile's website or market changed; run `generate` to update the plan, then pick again), `plan_updated` (the plan was rebuilt and that idea no longer exists; run `show` for the current list), `not_writable` (the item is not a `post`), `plan_item_not_found`.
|
|
645
|
+
|
|
646
|
+
### Dismiss
|
|
647
|
+
|
|
648
|
+
`coauthor seo-plan dismiss <item-id> --json` hides an idea the user does not want (it leaves the counts and `show`). `--undo` brings it back. Use it when the user rules an idea out; do not dismiss on your own judgment.
|
|
649
|
+
|
|
650
|
+
### What to tell the user
|
|
651
|
+
|
|
652
|
+
Summarize rather than dump: the `strategy_line`, the Do next moves with their `chance` and why, and the counts. Offer to write the first one or two posts. Mention `improve` items separately, because they are quick wins on pages that already rank.
|
|
653
|
+
|
|
522
654
|
## references/troubleshooting.md
|
|
523
655
|
|
|
524
656
|
## Troubleshooting
|
|
@@ -536,7 +668,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
536
668
|
| `research_running_stale` | Research progress has not changed for 30+ minutes. | Check `coauthor research status <id> --json` a few minutes apart and look at `coauthor research structured <id> --json`. Rewinding (`coauthor workflow rewind <id> --target research --json`) discards the research done so far and costs credits to redo, so ask the user first. |
|
|
537
669
|
| `research_run_state_mismatch` | Research run and project state disagree. | Report it and use the `recovery_commands` in the output. |
|
|
538
670
|
| `blocked_by_research` | A draft was requested while research is still running. | Use the `recovery_commands`; usually just resume toward draft. |
|
|
539
|
-
| `credits_exhausted` | The plan's credits for this period are used up. Work is paused and saved. | Tell the user `reset_at`, `used`, and `remaining`. Resume with `coauthor workflow resume <id> --wait --json` after the reset. See `references/credits-and-plans.md`. |
|
|
671
|
+
| `credits_exhausted` | The plan's credits for this period are used up. Work is paused and saved. A plan run that ran out of credits stops with this as its `error_code` (it is not resumable: run `seo-plan generate` again after the reset). | Tell the user `reset_at`, `used`, and `remaining`. Resume with `coauthor workflow resume <id> --wait --json` after the reset. See `references/credits-and-plans.md`. |
|
|
540
672
|
| `requires_key` | Included credits are used up and the plan can continue with the user's own AI provider key. | The user adds a key in CoAuthor's AI settings (`settings_url`); never ask for it in chat. Then run `resume_command`. |
|
|
541
673
|
| `byok_not_allowed` | The plan can't use provider keys. | Wait for the credit reset, or the user upgrades in CoAuthor. |
|
|
542
674
|
| `coauthor_access_required` | No active CoAuthor subscription on this account. | Tell the user. `coauthor auth status` still works. |
|
|
@@ -553,6 +685,16 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
553
685
|
| `workflow_token_mismatch`, `conflict` | The project moved on since you read it (for example someone used the web app). | Re-read the state with `coauthor workflow status <id> --json` and continue from there. |
|
|
554
686
|
| `insufficient_scope` | The token can't publish. | `coauthor auth login --with-publish`. |
|
|
555
687
|
| `wordpress_connection_required` | Several WordPress sites are connected. | Ask which one from `details.connections`, add `--connection-id`. |
|
|
688
|
+
| `widgets_not_enabled` | Interactives (beta) aren't enabled for this account, or the writer profile has them off. | Tell the user. If `details.reason` is `toggle_off`, turn them on with `coauthor profile update <profile-id> --interactive-widgets on` (new drafts only). |
|
|
689
|
+
| `widget_requires_anthropic_key` | Interactives need an Anthropic API key when the user builds with their own keys. | The user adds one in CoAuthor's AI settings; never ask for it in chat. |
|
|
690
|
+
| `widget_credit_cap_exceeds_balance` | Not enough credits left for a build (`details.credits_needed`). | Tell the user, check `coauthor credits`, and top up or wait for the reset. Try the cheaper model with `coauthor models preferences set --widget-model claude-sonnet-5-5` if they agree. |
|
|
691
|
+
| `widget_build_failed` | A build failed (`error.message` on the widget). Nothing was charged. | Retry `coauthor widgets build`; after repeated failures tell the user. |
|
|
692
|
+
| `widget_not_found` | No such interactive in this project (or it was deleted). | `coauthor widgets list <project-id>` for the current ids. |
|
|
693
|
+
| `widget_build_in_progress` | Only shown inside skipped lists: the interactive is already building. | Wait with `coauthor widgets status <project-id> <widget-id> --wait`. Building twice is never needed. |
|
|
694
|
+
| `widget_rate_limited` | A retry came within a minute, or 3 builds already failed today. | Wait and retry later; don't loop. |
|
|
695
|
+
| `widget_not_built` | `widgets edit` on a placeholder. | Build it first. |
|
|
696
|
+
| `widget_no_image_fallback` | `widgets use-image` on a widget that did not replace an image. | Delete it or build it instead. |
|
|
697
|
+
| `widgets_temporarily_unavailable` | Interactive building is paused on CoAuthor's side. | Try again later. |
|
|
556
698
|
| `feature_unavailable` | SEO features (`search-brief`, `project create --keyword` or `--seo`, `site`) aren't enabled for this account yet, or search data is temporarily unavailable. | Continue without a target keyword; the post is written as usual. |
|
|
557
699
|
| `no_website` | `site status`/`site reindex` on a profile with no website. | Ask the user to add their website to the profile in the web app. |
|
|
558
700
|
| `reindex_too_soon` | `site reindex` within 15 minutes of the last read. | Wait, or check `coauthor site status`. |
|
|
@@ -567,6 +709,29 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
567
709
|
| `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 "..."`. |
|
|
568
710
|
| `uploaded_image` | `image generate` on an image the user replaced with their own file. | Use `image edit --edit-prompt "..."`, or `image replace` again. |
|
|
569
711
|
| `not_a_panel` | `image replace` on an article image. | Only slideshow and video panels can be replaced from the CLI. |
|
|
712
|
+
| `not_enabled` | `seo-plan` commands on an account outside the SEO content plan rollout. | Carry on without a plan and choose topics yourself. |
|
|
713
|
+
| `profile_not_found` | `--profile` isn't one of the user's profiles. | `coauthor profile list --json` and use an `id` from it. |
|
|
714
|
+
| `profile_archived` | `seo-plan generate` on an archived profile. | Use another profile, or the user restores it in the web app. |
|
|
715
|
+
| `site_required` | `seo-plan generate` on a profile with no website. | Ask the user to add the website to the profile in the web app. |
|
|
716
|
+
| `site_indexing` | CoAuthor is still reading the profile's website. | Check `coauthor site status`; run `generate` again when it is `ready` (a few minutes). Nothing was spent. |
|
|
717
|
+
| `market_confirmation_needed` | CoAuthor can't tell which country's search results to plan for. | The user confirms the search country in the profile settings in the web app, then run `generate` again. Nothing was spent. |
|
|
718
|
+
| `market_not_supported` | Search data doesn't fully cover the profile's country and language. | Give the user `details.explanation.message` and its alternatives; they change the profile's country or language in the web app. Nothing was spent. |
|
|
719
|
+
| `insufficient_credits` | A plan needs at least 500 credits remaining (`details.required`, `details.remaining`). | Tell the user; resume after the reset (`coauthor credits --json`). Nothing was spent. |
|
|
720
|
+
| `plan_running` | A plan is already being made on this account (only one runs at a time). | `coauthor seo-plan generate --profile <id> --wait` joins the running plan for that profile; otherwise wait and use `seo-plan show`. |
|
|
721
|
+
| `worker_unavailable` | The plan service couldn't be reached. Nothing was spent. | Try again in a few minutes. |
|
|
722
|
+
| `dataforseo_busy` | A plan run stopped because the search data provider was busy (`seo-plan show` or the `--wait` result carries it as `error_code`). | Run `coauthor seo-plan generate --wait` again in a few minutes. Work already done is cached, so a retry costs less. |
|
|
723
|
+
| `dataforseo_failed` | A plan run couldn't get the search data it needs. | Retry in a few minutes. If it repeats, tell the user. |
|
|
724
|
+
| `backlinks_unavailable` | A plan run couldn't read backlink data for the site, which it needs to judge difficulty. Nothing was spent. | Try again later; don't retry in a loop. |
|
|
725
|
+
| `llm_failed` | One of the plan's writing steps didn't complete. | Retry `seo-plan generate --wait`; finished steps are reused. |
|
|
726
|
+
| `plan_cost_cap` | A plan run reached its spending limit and stopped; what was used was charged. | Tell the user. Retry with a narrower `--adjust` (for example one product line or audience). |
|
|
727
|
+
| `plan_timeout`, `lease_expired`, `internal` | A plan run took too long or stopped unexpectedly. | Retry `seo-plan generate --wait` once; if it fails again, report the `error_code` to the user. |
|
|
728
|
+
| `invalid_input`, `invalid_filter` | `--adjust` over 2,000 characters, bad competitors, or a bad `--kind`, `--stage`, `--chance` or `--limit`. | Fix the value (`coauthor seo-plan --help` lists them). |
|
|
729
|
+
| `coauthor_access_required`, `entitlement_sync_unavailable` | See above; they apply to `seo-plan` too. | As above. |
|
|
730
|
+
| `plan_stale` | `seo-plan write` on an idea from a plan built for a website or market the profile no longer has. | `coauthor seo-plan generate --wait --json` to update the plan, then pick an idea again. |
|
|
731
|
+
| `plan_updated` | `seo-plan write` on an idea that a newer plan run replaced. | `coauthor seo-plan show --json` for the current ideas. |
|
|
732
|
+
| `not_writable` | `seo-plan write` on an item that isn't a `post` idea (improve, page idea, left out, covered). | Only `post` items are written. Improve and page ideas are tasks on the user's site. |
|
|
733
|
+
| `plan_item_not_found` | `seo-plan write` or `dismiss` with an unknown item id. | Take the `id` from `seo-plan show --json`. |
|
|
734
|
+
| `operation_in_progress` | A `seo-plan generate` with the same `--idempotency-key` is still being processed. | Wait a moment and check `coauthor seo-plan show`. |
|
|
570
735
|
| `usage_error` | The command or its flags are wrong; nothing was sent. | Check `coauthor help <command>` and fix the command. |
|
|
571
736
|
| `request_timeout`, `network_error` | No answer from CoAuthor in time, or the connection failed. | For reads, retry. For exports, publishes, and image generate/edit, check `coauthor operation status <idempotency_key>` before retrying. |
|
|
572
737
|
|