@clickminded/coauthor-cli 0.0.54 → 0.0.56
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -0
- package/dist/commands.js +291 -5
- package/dist/parser.js +5 -1
- package/package.json +1 -1
- package/skills/coauthor/SKILL.md +3 -3
- package/skills/coauthor/references/credits-and-plans.md +1 -0
- package/skills/coauthor/references/interactive-widgets.md +40 -0
- package/skills/coauthor/references/troubleshooting.md +10 -0
- package/skills/cursor/coauthor-cli.mdc +57 -3
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
|
package/dist/commands.js
CHANGED
|
@@ -37,6 +37,8 @@ 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);
|
|
42
44
|
if (scope === 'seo-plan')
|
|
@@ -492,8 +494,8 @@ async function runModelsCommand(action, input, client) {
|
|
|
492
494
|
}
|
|
493
495
|
if (subaction === 'set') {
|
|
494
496
|
const body = modelOverrideBody(input);
|
|
495
|
-
if (!body.planningModel && !body.writingModel) {
|
|
496
|
-
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>]');
|
|
497
499
|
}
|
|
498
500
|
const data = await client.request({ method: 'POST', path: 'models/preferences', body });
|
|
499
501
|
return { ok: true, message: 'Model preferences updated', data };
|
|
@@ -509,6 +511,9 @@ function modelOverrideBody(input) {
|
|
|
509
511
|
body.planningModel = planningModel;
|
|
510
512
|
if (writingModel)
|
|
511
513
|
body.writingModel = writingModel;
|
|
514
|
+
const widgetModel = getString(input.values, 'widget-model');
|
|
515
|
+
if (widgetModel)
|
|
516
|
+
body.widgetModel = widgetModel;
|
|
512
517
|
return body;
|
|
513
518
|
}
|
|
514
519
|
function formatModelsList(data) {
|
|
@@ -536,6 +541,9 @@ function formatModelsList(data) {
|
|
|
536
541
|
formatGroup('Planning models (--planning-model)', models.planning),
|
|
537
542
|
'',
|
|
538
543
|
formatGroup('Writing models (--writing-model)', models.writing),
|
|
544
|
+
...(models.widgets
|
|
545
|
+
? ['', formatGroup('Interactive widget models (--widget-model, beta)', models.widgets)]
|
|
546
|
+
: []),
|
|
539
547
|
].join('\n');
|
|
540
548
|
}
|
|
541
549
|
async function runArtifactCommand(artifact, action, input, client) {
|
|
@@ -1893,7 +1901,266 @@ async function runProfileCommand(action, input, client) {
|
|
|
1893
1901
|
throw new Error('Usage: coauthor profile show <profile-id>');
|
|
1894
1902
|
return { ok: true, data: await client.request({ path: `profiles/${encodeURIComponent(profileId)}` }) };
|
|
1895
1903
|
}
|
|
1896
|
-
|
|
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
|
+
const alreadyDone = !updated && getResponseString(data, 'document_status') === 'already_removed';
|
|
2134
|
+
const placeholderId = placeholder?.placeholder_id ? String(placeholder.placeholder_id) : '<placeholder-id>';
|
|
2135
|
+
return {
|
|
2136
|
+
ok: true,
|
|
2137
|
+
message: [
|
|
2138
|
+
`The interactive is replaced by an image placeholder${placeholder?.placeholder_id ? ` (${placeholderId})` : ''}.`,
|
|
2139
|
+
updated
|
|
2140
|
+
? 'The draft was updated.'
|
|
2141
|
+
: alreadyDone
|
|
2142
|
+
? 'Already done: the draft no longer has this interactive.'
|
|
2143
|
+
: `The draft was NOT updated${note ? `: ${note}` : '.'}`,
|
|
2144
|
+
`Generate the image with: coauthor image generate ${projectId} --placeholder-id ${placeholderId}`,
|
|
2145
|
+
].join('\n'),
|
|
2146
|
+
data,
|
|
2147
|
+
};
|
|
2148
|
+
}
|
|
2149
|
+
if (action === 'delete') {
|
|
2150
|
+
const id = needWidget('delete');
|
|
2151
|
+
if (!getBoolean(input.values, 'yes')) {
|
|
2152
|
+
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.');
|
|
2153
|
+
}
|
|
2154
|
+
const data = await client.request({ method: 'DELETE', path: `${base}/${encodeURIComponent(id)}` });
|
|
2155
|
+
const updated = getResponseValue(data, 'document_updated') === true;
|
|
2156
|
+
const note = getResponseString(data, 'document_note');
|
|
2157
|
+
return {
|
|
2158
|
+
ok: true,
|
|
2159
|
+
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}` : '.'}`}`,
|
|
2160
|
+
data,
|
|
2161
|
+
};
|
|
2162
|
+
}
|
|
2163
|
+
throw new Error(usage);
|
|
1897
2164
|
}
|
|
1898
2165
|
function siteMessage(data, request) {
|
|
1899
2166
|
const site = getResponseValue(data, 'site');
|
|
@@ -2987,7 +3254,8 @@ export function helpResult(command = []) {
|
|
|
2987
3254
|
' research-plan show|generate|revise|save|approve',
|
|
2988
3255
|
' repurpose list|generate|show|save|status|render|download',
|
|
2989
3256
|
' brief review|answer',
|
|
2990
|
-
' profile list|show',
|
|
3257
|
+
' profile list|show|update (update: --interactive-widgets on|off)',
|
|
3258
|
+
' widgets list|status|build|build-all|use-image|edit|delete (interactives, beta)',
|
|
2991
3259
|
' site status|reindex [--profile <profile-id>] (limited rollout)',
|
|
2992
3260
|
' seo-plan show|generate|write|dismiss (limited rollout)',
|
|
2993
3261
|
' source list|add|remove',
|
|
@@ -3059,15 +3327,32 @@ function commandHelp(command) {
|
|
|
3059
3327
|
'',
|
|
3060
3328
|
'Requires project_state "research_structured". If research is still running or structuring, inspect the returned status and next commands.',
|
|
3061
3329
|
].join('\n'),
|
|
3330
|
+
widgets: [
|
|
3331
|
+
'Usage: coauthor widgets list <project-id> [--wait] [--json]',
|
|
3332
|
+
' coauthor widgets status <project-id> <widget-id> [--wait] [--json]',
|
|
3333
|
+
' coauthor widgets build <project-id> <widget-id> [--wait] [--json]',
|
|
3334
|
+
' coauthor widgets build-all <project-id> [<widget-id>...] [--wait] [--json]',
|
|
3335
|
+
' coauthor widgets use-image <project-id> <widget-id> [--json]',
|
|
3336
|
+
' coauthor widgets edit <project-id> <widget-id> --instruction "..." --yes [--wait] [--json]',
|
|
3337
|
+
' coauthor widgets delete <project-id> <widget-id> --yes [--json]',
|
|
3338
|
+
'',
|
|
3339
|
+
'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.',
|
|
3340
|
+
'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.',
|
|
3341
|
+
'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.',
|
|
3342
|
+
'use-image swaps a placeholder that took over an image back to that image placeholder, and updates the draft.',
|
|
3343
|
+
'edit and delete change every published copy of the interactive, so they need --yes. delete cannot be undone.',
|
|
3344
|
+
'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).',
|
|
3345
|
+
].join('\n'),
|
|
3062
3346
|
'models list': [
|
|
3063
3347
|
'Usage: coauthor models list [--json]',
|
|
3064
3348
|
'',
|
|
3065
3349
|
'Lists user-visible planning and writing model IDs for --planning-model and --writing-model.',
|
|
3066
3350
|
].join('\n'),
|
|
3067
3351
|
'models preferences': [
|
|
3068
|
-
'Usage: coauthor models preferences <show|set> [--planning-model <id>] [--writing-model <id>] [--json]',
|
|
3352
|
+
'Usage: coauthor models preferences <show|set> [--planning-model <id>] [--writing-model <id>] [--widget-model <id>] [--json]',
|
|
3069
3353
|
'',
|
|
3070
3354
|
'Shows or updates saved primary planning/writing model preferences while preserving fallback order.',
|
|
3355
|
+
'--widget-model (interactives beta) picks the model that builds interactives: claude-opus-5-5 (default) or claude-sonnet-5-5.',
|
|
3071
3356
|
].join('\n'),
|
|
3072
3357
|
'draft get': [
|
|
3073
3358
|
'Usage: coauthor draft get <project-id> [--format json|markdown|html|text] [--frontmatter] [--json]',
|
|
@@ -3092,6 +3377,7 @@ function commandHelp(command) {
|
|
|
3092
3377
|
profile: [
|
|
3093
3378
|
'Usage: coauthor profile list [--json]',
|
|
3094
3379
|
' coauthor profile show <profile-id> [--json]',
|
|
3380
|
+
' coauthor profile update <profile-id> --interactive-widgets on|off [--json] (interactives beta)',
|
|
3095
3381
|
'',
|
|
3096
3382
|
'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.',
|
|
3097
3383
|
].join('\n'),
|
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' },
|
|
@@ -180,7 +182,9 @@ function commandLength(positionals) {
|
|
|
180
182
|
if (first === 'log')
|
|
181
183
|
return second && ['add', 'show'].includes(second) ? 2 : 1;
|
|
182
184
|
if (first === 'profile')
|
|
183
|
-
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;
|
|
184
188
|
if (first === 'site')
|
|
185
189
|
return second && ['status', 'reindex'].includes(second) ? 2 : 1;
|
|
186
190
|
if (first === 'seo-plan')
|
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
|
|
|
@@ -78,4 +78,4 @@ Details, item fields, and what each kind means: `references/seo-content-plan.md`
|
|
|
78
78
|
|
|
79
79
|
## Not in the CLI yet
|
|
80
80
|
|
|
81
|
-
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.
|
|
@@ -25,3 +25,4 @@ Paused work is saved. Resume it with `coauthor workflow resume <id> --wait --jso
|
|
|
25
25
|
- `coauthor models list` shows the planning and writing models available.
|
|
26
26
|
- Override for one run with `--planning-model <id>` (outline, research plan) and `--writing-model <id>` (draft, thread). There is no global `--model`.
|
|
27
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, `document_status` says why: `already_removed` means a repeat (the swap was already done, nothing to fix); `not_updated` is a real failure and `document_note` has the manual fix. The call is safe to repeat.
|
|
29
|
+
- `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`.
|
|
@@ -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`. |
|
|
@@ -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
|
|
|
@@ -80,7 +80,7 @@ Details, item fields, and what each kind means: `references/seo-content-plan.md`
|
|
|
80
80
|
|
|
81
81
|
## Not in the CLI yet
|
|
82
82
|
|
|
83
|
-
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.
|
|
84
84
|
|
|
85
85
|
# Reference sections
|
|
86
86
|
|
|
@@ -291,6 +291,7 @@ Paused work is saved. Resume it with `coauthor workflow resume <id> --wait --jso
|
|
|
291
291
|
- `coauthor models list` shows the planning and writing models available.
|
|
292
292
|
- Override for one run with `--planning-model <id>` (outline, research plan) and `--writing-model <id>` (draft, thread). There is no global `--model`.
|
|
293
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`.
|
|
294
295
|
|
|
295
296
|
## references/editing-drafts.md
|
|
296
297
|
|
|
@@ -389,6 +390,49 @@ Images cost credits each time they are generated or edited, so check the brief a
|
|
|
389
390
|
|
|
390
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.
|
|
391
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, `document_status` says why: `already_removed` means a repeat (the swap was already done, nothing to fix); `not_updated` is a real failure and `document_note` has the manual fix. The call is safe to repeat.
|
|
423
|
+
- `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
|
+
|
|
392
436
|
## references/publishing-and-export.md
|
|
393
437
|
|
|
394
438
|
## Publishing and export
|
|
@@ -641,6 +685,16 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
641
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. |
|
|
642
686
|
| `insufficient_scope` | The token can't publish. | `coauthor auth login --with-publish`. |
|
|
643
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. |
|
|
644
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. |
|
|
645
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. |
|
|
646
700
|
| `reindex_too_soon` | `site reindex` within 15 minutes of the last read. | Wait, or check `coauthor site status`. |
|