@clickminded/coauthor-cli 0.0.52 → 0.0.54
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 +4 -0
- package/dist/commands.js +270 -1
- package/dist/parser.js +5 -0
- package/package.json +1 -1
- package/skills/coauthor/SKILL.md +12 -1
- package/skills/coauthor/references/credits-and-plans.md +1 -0
- package/skills/coauthor/references/seo-content-plan.md +73 -0
- package/skills/coauthor/references/troubleshooting.md +24 -1
- package/skills/cursor/coauthor-cli.mdc +113 -2
package/README.md
CHANGED
|
@@ -85,6 +85,10 @@ coauthor integrations list --json # WordPress sites
|
|
|
85
85
|
coauthor seo markets --country Mexico --language Spanish --json # Google search data coverage for a market
|
|
86
86
|
coauthor search-brief show <id> --json # SEO mode: target keyword and what ranks (limited rollout)
|
|
87
87
|
coauthor search-brief set-keyword <id> "email marketing" --json # target your own keyword (--confirm-reset after an outline)
|
|
88
|
+
coauthor seo-plan generate --wait --json # SEO content plan for the default profile: ~420 credits, 5-12 minutes (limited rollout)
|
|
89
|
+
coauthor seo-plan show --kind post --json # strategy, Do next moves, counts, and the post ideas
|
|
90
|
+
coauthor seo-plan write <item-id> --json # open a project for a post idea, then continue with workflow run
|
|
91
|
+
coauthor seo-plan dismiss <item-id> --json # hide an idea (--undo brings it back)
|
|
88
92
|
```
|
|
89
93
|
|
|
90
94
|
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
|
@@ -39,6 +39,8 @@ export async function runCommand(input, context) {
|
|
|
39
39
|
return runProfileCommand(action, input, context.client);
|
|
40
40
|
if (scope === 'site')
|
|
41
41
|
return runSiteCommand(action, input, context.client);
|
|
42
|
+
if (scope === 'seo-plan')
|
|
43
|
+
return runSeoPlanCommand(action, input, context.client);
|
|
42
44
|
if (scope === 'integrations')
|
|
43
45
|
return { ok: true, data: await context.client.request({ path: 'integrations' }) };
|
|
44
46
|
if (scope === 'source')
|
|
@@ -1935,6 +1937,259 @@ async function runSiteCommand(action, input, client) {
|
|
|
1935
1937
|
const data = await client.request({ path });
|
|
1936
1938
|
return { ok: true, message: siteMessage(data), data };
|
|
1937
1939
|
}
|
|
1940
|
+
// ─── SEO content plan (limited rollout) ──────────────────────────────────────
|
|
1941
|
+
const SEO_PLAN_KINDS = ['post', 'improve', 'page', 'left_out', 'covered', 'not_checked'];
|
|
1942
|
+
const SEO_PLAN_KIND_LABELS = {
|
|
1943
|
+
post: 'posts to write',
|
|
1944
|
+
improve: 'pages to improve',
|
|
1945
|
+
page: 'page ideas',
|
|
1946
|
+
left_out: 'searches left out',
|
|
1947
|
+
covered: 'already covered',
|
|
1948
|
+
not_checked: 'not checked',
|
|
1949
|
+
};
|
|
1950
|
+
const SEO_PLAN_USAGE = [
|
|
1951
|
+
'Usage: coauthor seo-plan show [--profile <profile-id>] [--kind post|improve|page|left_out|covered|not_checked] [--stage <stage>] [--chance <chance>] [--limit <n>] [--json]',
|
|
1952
|
+
' coauthor seo-plan generate [--profile <profile-id>] [--adjust "<text>"] [--wait] [--json]',
|
|
1953
|
+
' coauthor seo-plan write <item-id> [--json]',
|
|
1954
|
+
' coauthor seo-plan dismiss <item-id> [--undo] [--json]',
|
|
1955
|
+
].join('\n');
|
|
1956
|
+
function planRecord(value) {
|
|
1957
|
+
return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
|
|
1958
|
+
}
|
|
1959
|
+
function planString(record, key) {
|
|
1960
|
+
const value = record[key];
|
|
1961
|
+
return typeof value === 'string' && value.trim() ? value.trim() : null;
|
|
1962
|
+
}
|
|
1963
|
+
async function resolveProfileOption(input, client) {
|
|
1964
|
+
const given = getString(input.values, 'profile') ?? input.positionals[0];
|
|
1965
|
+
if (given)
|
|
1966
|
+
return given;
|
|
1967
|
+
const profiles = await client.request({ path: 'profiles' });
|
|
1968
|
+
const fallback = getResponseValue(profiles, 'default_profile_id');
|
|
1969
|
+
if (typeof fallback !== 'string' || !fallback)
|
|
1970
|
+
throw new Error('No writer profile found. Create one in the CoAuthor web app.');
|
|
1971
|
+
return fallback;
|
|
1972
|
+
}
|
|
1973
|
+
function httpErrorCode(error) {
|
|
1974
|
+
if (!(error instanceof AgentHttpError))
|
|
1975
|
+
return null;
|
|
1976
|
+
const body = planRecord(error.responseBody);
|
|
1977
|
+
const code = planRecord(body.error).code;
|
|
1978
|
+
return typeof code === 'string' ? code : null;
|
|
1979
|
+
}
|
|
1980
|
+
function seoPlanItemLine(item) {
|
|
1981
|
+
const keyword = planString(item, 'primary_keyword');
|
|
1982
|
+
const title = planString(item, 'title') ?? keyword ?? '(untitled)';
|
|
1983
|
+
const facts = [
|
|
1984
|
+
typeof item.volume === 'number' ? `${item.volume}/mo` : null,
|
|
1985
|
+
planString(item, 'stage'),
|
|
1986
|
+
planString(item, 'chance'),
|
|
1987
|
+
].filter(Boolean).join(', ');
|
|
1988
|
+
const id = planString(item, 'id') ?? '';
|
|
1989
|
+
const head = ` ${id} ${title}`;
|
|
1990
|
+
const search = keyword && keyword !== title ? ` [search: ${keyword}]` : '';
|
|
1991
|
+
const where = planString(item, 'existing_url');
|
|
1992
|
+
const position = typeof item.existing_position === 'number' ? ` (position ${item.existing_position})` : '';
|
|
1993
|
+
const hint = planString(item, 'improve_hint') ?? planString(item, 'reason') ?? planString(item, 'note');
|
|
1994
|
+
const written = planString(item, 'project_id') ? ` -> project ${planString(item, 'project_id')}` : '';
|
|
1995
|
+
const dismissed = item.dismissed === true ? ' (dismissed)' : '';
|
|
1996
|
+
return [
|
|
1997
|
+
`${head}${search}${facts ? ` (${facts})` : ''}${written}${dismissed}`,
|
|
1998
|
+
where ? ` ${where}${position}` : null,
|
|
1999
|
+
hint ? ` ${hint}` : null,
|
|
2000
|
+
].filter(Boolean).join('\n');
|
|
2001
|
+
}
|
|
2002
|
+
function seoPlanShowMessage(data, kind) {
|
|
2003
|
+
const view = planRecord(data);
|
|
2004
|
+
const plan = view.plan === null || view.plan === undefined ? null : planRecord(view.plan);
|
|
2005
|
+
const estimate = typeof view.estimate_credits === 'number' ? view.estimate_credits : null;
|
|
2006
|
+
const status = plan ? planString(plan, 'status') : null;
|
|
2007
|
+
if (!plan || status === 'idle') {
|
|
2008
|
+
return `No SEO content plan for this profile yet. Make one with \`coauthor seo-plan generate --wait\`${estimate ? ` (about ${estimate} credits)` : ''}.`;
|
|
2009
|
+
}
|
|
2010
|
+
const lines = [];
|
|
2011
|
+
if (status === 'queued' || status === 'running') {
|
|
2012
|
+
const step = planString(planRecord(plan.progress), 'step') ?? planString(planRecord(plan.progress), 'label');
|
|
2013
|
+
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.' : ''}`);
|
|
2014
|
+
}
|
|
2015
|
+
else if (status === 'failed') {
|
|
2016
|
+
const code = planString(plan, 'error_code');
|
|
2017
|
+
lines.push(`The last plan run failed${code ? ` (${code})` : ''}: ${planString(plan, 'error_message') ?? 'unknown error'}. Try again with \`coauthor seo-plan generate --wait\`.`);
|
|
2018
|
+
}
|
|
2019
|
+
if (view.stale === true)
|
|
2020
|
+
lines.push('The profile\'s website or market changed since this plan was made. `coauthor seo-plan generate` updates it.');
|
|
2021
|
+
const strategy = planString(plan, 'strategy_line');
|
|
2022
|
+
if (strategy)
|
|
2023
|
+
lines.push(`Strategy: ${strategy}`);
|
|
2024
|
+
const competitors = planString(plan, 'competitors_line');
|
|
2025
|
+
if (competitors)
|
|
2026
|
+
lines.push(`Competitors: ${competitors}`);
|
|
2027
|
+
const doNext = Array.isArray(view.do_next) ? view.do_next.map(planRecord) : [];
|
|
2028
|
+
if (doNext.length > 0) {
|
|
2029
|
+
lines.push('', 'Do next:');
|
|
2030
|
+
doNext.forEach((item, index) => {
|
|
2031
|
+
lines.push(`${index + 1}.${seoPlanItemLine(item).slice(1)}`);
|
|
2032
|
+
const why = planString(item, 'why');
|
|
2033
|
+
if (why)
|
|
2034
|
+
lines.push(` ${why}`);
|
|
2035
|
+
});
|
|
2036
|
+
}
|
|
2037
|
+
const counts = planRecord(view.counts_by_kind);
|
|
2038
|
+
const summary = SEO_PLAN_KINDS
|
|
2039
|
+
.map((entry) => (typeof counts[entry] === 'number' && counts[entry] > 0 ? `${counts[entry]} ${SEO_PLAN_KIND_LABELS[entry]}` : null))
|
|
2040
|
+
.filter(Boolean);
|
|
2041
|
+
lines.push('', summary.length > 0 ? `Ideas: ${summary.join(', ')}.` : 'The plan has no ideas.');
|
|
2042
|
+
const items = Array.isArray(view.items) ? view.items.map(planRecord) : [];
|
|
2043
|
+
const total = typeof view.total === 'number' ? view.total : items.length;
|
|
2044
|
+
if (items.length > 0 || total > 0) {
|
|
2045
|
+
lines.push('', `${SEO_PLAN_KIND_LABELS[kind] ?? kind} (${items.length === total ? total : `${items.length} of ${total}`}):`);
|
|
2046
|
+
for (const item of items)
|
|
2047
|
+
lines.push(seoPlanItemLine(item));
|
|
2048
|
+
if (kind === 'post')
|
|
2049
|
+
lines.push('', 'Write one with `coauthor seo-plan write <item-id>`; hide one with `coauthor seo-plan dismiss <item-id>`.');
|
|
2050
|
+
}
|
|
2051
|
+
else {
|
|
2052
|
+
lines.push('', `Nothing to show for ${SEO_PLAN_KIND_LABELS[kind] ?? kind}.`);
|
|
2053
|
+
}
|
|
2054
|
+
return lines.join('\n');
|
|
2055
|
+
}
|
|
2056
|
+
function seoPlanWaitFailure(status) {
|
|
2057
|
+
const code = planString(status, 'error_code');
|
|
2058
|
+
const message = planString(status, 'error_message') ?? 'The plan run failed.';
|
|
2059
|
+
return {
|
|
2060
|
+
ok: false,
|
|
2061
|
+
status: code ?? 'failed',
|
|
2062
|
+
message: `The plan run failed${code ? ` (${code})` : ''}: ${message}`,
|
|
2063
|
+
data: status,
|
|
2064
|
+
};
|
|
2065
|
+
}
|
|
2066
|
+
// Polls the plan's status (capped under the 10-minute agent shell limit) until it stops queued/running.
|
|
2067
|
+
async function waitForSeoPlan(client, profileId, started) {
|
|
2068
|
+
const statusPath = `profiles/${encodeURIComponent(profileId)}/seo-plan/status`;
|
|
2069
|
+
const resume = `coauthor seo-plan generate --profile ${profileId} --wait`;
|
|
2070
|
+
const deadline = Date.now() + waitTimeoutMs(9 * 60_000);
|
|
2071
|
+
const pollMs = Math.max(waitPollMs(), 0);
|
|
2072
|
+
let status = planRecord(await client.request({ path: statusPath }));
|
|
2073
|
+
while (status.done !== true && Date.now() < deadline) {
|
|
2074
|
+
await sleep(Math.min(pollMs, 15_000));
|
|
2075
|
+
status = planRecord(await client.request({ path: statusPath }));
|
|
2076
|
+
}
|
|
2077
|
+
if (status.done !== true) {
|
|
2078
|
+
const step = planString(planRecord(status.progress), 'step') ?? planString(planRecord(status.progress), 'label');
|
|
2079
|
+
return {
|
|
2080
|
+
ok: false,
|
|
2081
|
+
status: 'still_running',
|
|
2082
|
+
exitCode: 2,
|
|
2083
|
+
resume_command: resume,
|
|
2084
|
+
message: `The plan is still being made${step ? ` (${step})` : ''}. Plans take about 5 to 12 minutes. Keep waiting with: ${resume}`,
|
|
2085
|
+
data: (started ?? status),
|
|
2086
|
+
};
|
|
2087
|
+
}
|
|
2088
|
+
if (status.status === 'failed')
|
|
2089
|
+
return seoPlanWaitFailure(status);
|
|
2090
|
+
return {
|
|
2091
|
+
ok: true,
|
|
2092
|
+
message: `The plan is ready. See it with \`coauthor seo-plan show --profile ${profileId}\`.`,
|
|
2093
|
+
data: status,
|
|
2094
|
+
};
|
|
2095
|
+
}
|
|
2096
|
+
async function runSeoPlanCommand(action, input, client) {
|
|
2097
|
+
if (!action || !['show', 'generate', 'write', 'dismiss'].includes(action))
|
|
2098
|
+
throw new Error(SEO_PLAN_USAGE);
|
|
2099
|
+
if (action === 'show') {
|
|
2100
|
+
const kind = (getString(input.values, 'kind') ?? 'post').trim().toLowerCase().replace(/-/g, '_');
|
|
2101
|
+
if (!SEO_PLAN_KINDS.includes(kind)) {
|
|
2102
|
+
throw new Error(`--kind must be one of ${SEO_PLAN_KINDS.join(', ')}. Run \`coauthor seo-plan --help\` for usage.`);
|
|
2103
|
+
}
|
|
2104
|
+
const limit = getString(input.values, 'limit');
|
|
2105
|
+
if (limit !== undefined && !/^[1-9]\d*$/.test(limit))
|
|
2106
|
+
throw new Error('--limit must be a whole number from 1 to 500. Run `coauthor seo-plan --help` for usage.');
|
|
2107
|
+
const profileId = await resolveProfileOption(input, client);
|
|
2108
|
+
const query = new URLSearchParams({ kind });
|
|
2109
|
+
for (const name of ['stage', 'chance', 'limit']) {
|
|
2110
|
+
const value = getString(input.values, name);
|
|
2111
|
+
if (value)
|
|
2112
|
+
query.set(name, value);
|
|
2113
|
+
}
|
|
2114
|
+
const data = await client.request({ path: `profiles/${encodeURIComponent(profileId)}/seo-plan?${query.toString()}` });
|
|
2115
|
+
return { ok: true, message: seoPlanShowMessage(data, kind), messageIncludesData: true, data };
|
|
2116
|
+
}
|
|
2117
|
+
if (action === 'generate') {
|
|
2118
|
+
const adjust = getString(input.values, 'adjust');
|
|
2119
|
+
if (input.values.adjust !== undefined && !adjust?.trim())
|
|
2120
|
+
throw new Error('--adjust needs text, for example --adjust "focus on B2B buyers". Run `coauthor seo-plan --help` for usage.');
|
|
2121
|
+
if (adjust && adjust.length > 2000)
|
|
2122
|
+
throw new Error('--adjust can be at most 2000 characters.');
|
|
2123
|
+
const wait = getBoolean(input.values, 'wait');
|
|
2124
|
+
const profileId = await resolveProfileOption(input, client);
|
|
2125
|
+
const idempotencyKey = getString(input.values, 'idempotency-key')?.trim() || randomUUID();
|
|
2126
|
+
let started;
|
|
2127
|
+
try {
|
|
2128
|
+
started = await client.request({
|
|
2129
|
+
method: 'POST',
|
|
2130
|
+
path: `profiles/${encodeURIComponent(profileId)}/seo-plan`,
|
|
2131
|
+
body: adjust?.trim() ? { adjustments: adjust.trim() } : {},
|
|
2132
|
+
idempotencyKey,
|
|
2133
|
+
});
|
|
2134
|
+
}
|
|
2135
|
+
catch (error) {
|
|
2136
|
+
// One plan runs per account at a time. When --wait finds this profile's plan already running
|
|
2137
|
+
// (an earlier --wait timed out), join it instead of failing.
|
|
2138
|
+
if (wait && httpErrorCode(error) === 'plan_running') {
|
|
2139
|
+
const status = planRecord(await client.request({ path: `profiles/${encodeURIComponent(profileId)}/seo-plan/status` }));
|
|
2140
|
+
if (status.done === false)
|
|
2141
|
+
return waitForSeoPlan(client, profileId, null);
|
|
2142
|
+
}
|
|
2143
|
+
throw error;
|
|
2144
|
+
}
|
|
2145
|
+
const estimate = getResponseNumber(started, 'estimate_credits');
|
|
2146
|
+
const queued = `Plan queued${estimate ? ` (about ${estimate} credits, charged as it runs)` : ''}. It takes about 5 to 12 minutes.`;
|
|
2147
|
+
if (!wait) {
|
|
2148
|
+
return {
|
|
2149
|
+
ok: true,
|
|
2150
|
+
message: `${queued} Follow it with \`coauthor seo-plan generate --profile ${profileId} --wait\` or \`coauthor seo-plan show --profile ${profileId}\`.`,
|
|
2151
|
+
idempotency_key: idempotencyKey,
|
|
2152
|
+
data: started,
|
|
2153
|
+
};
|
|
2154
|
+
}
|
|
2155
|
+
const result = await waitForSeoPlan(client, profileId, started);
|
|
2156
|
+
return { ...result, idempotency_key: idempotencyKey };
|
|
2157
|
+
}
|
|
2158
|
+
const itemId = input.positionals[0];
|
|
2159
|
+
if (action === 'write') {
|
|
2160
|
+
if (!itemId)
|
|
2161
|
+
throw new Error('Usage: coauthor seo-plan write <item-id>');
|
|
2162
|
+
const data = await client.request({ method: 'POST', path: `seo-plan/items/${encodeURIComponent(itemId)}/write`, body: {} });
|
|
2163
|
+
const projectId = getResponseString(data, 'project_id') ?? '';
|
|
2164
|
+
const startPrompt = getResponseString(data, 'start_prompt');
|
|
2165
|
+
return {
|
|
2166
|
+
ok: true,
|
|
2167
|
+
message: [
|
|
2168
|
+
`${getResponseValue(data, 'created') === true ? 'Created' : 'Already created'} project ${projectId} for this idea.`,
|
|
2169
|
+
startPrompt ? `Start prompt: ${startPrompt}` : null,
|
|
2170
|
+
`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.`,
|
|
2171
|
+
].filter(Boolean).join('\n'),
|
|
2172
|
+
messageIncludesData: true,
|
|
2173
|
+
data,
|
|
2174
|
+
};
|
|
2175
|
+
}
|
|
2176
|
+
if (!itemId)
|
|
2177
|
+
throw new Error('Usage: coauthor seo-plan dismiss <item-id> [--undo]');
|
|
2178
|
+
const undo = getBoolean(input.values, 'undo');
|
|
2179
|
+
const data = await client.request({
|
|
2180
|
+
method: 'POST',
|
|
2181
|
+
path: `seo-plan/items/${encodeURIComponent(itemId)}/dismiss`,
|
|
2182
|
+
body: { dismissed: !undo },
|
|
2183
|
+
});
|
|
2184
|
+
return {
|
|
2185
|
+
ok: true,
|
|
2186
|
+
message: undo
|
|
2187
|
+
? `Restored ${itemId} to the plan.`
|
|
2188
|
+
: `Hid ${itemId} from the plan. Bring it back with \`coauthor seo-plan dismiss ${itemId} --undo\`.`,
|
|
2189
|
+
messageIncludesData: true,
|
|
2190
|
+
data,
|
|
2191
|
+
};
|
|
2192
|
+
}
|
|
1938
2193
|
const SOURCE_TYPES = { pdf: 'application/pdf', txt: 'text/plain', md: 'text/markdown', markdown: 'text/markdown' };
|
|
1939
2194
|
// Mirrors the server: base64 over the API caps PDFs at ~3.3 MB; text at 512 KB.
|
|
1940
2195
|
const MAX_SOURCE_PDF_BYTES = 3_300_000;
|
|
@@ -2296,7 +2551,7 @@ async function slideshowStatus(projectId, base, wait, client) {
|
|
|
2296
2551
|
const nextStep = counts.generating > 0
|
|
2297
2552
|
? ` Check again with: coauthor repurpose status ${projectId} --format slideshow --wait`
|
|
2298
2553
|
: counts.failed > 0
|
|
2299
|
-
? ' Retry the failed panels in the web app (
|
|
2554
|
+
? ' Retry the failed panels in the web app (Repurpose > Slideshow) or with coauthor image generate, then download.'
|
|
2300
2555
|
: ` Save the PNGs with: coauthor repurpose download ${projectId} --format slideshow`;
|
|
2301
2556
|
return {
|
|
2302
2557
|
ok: counts.failed === 0 && !stillRunning,
|
|
@@ -2734,6 +2989,7 @@ export function helpResult(command = []) {
|
|
|
2734
2989
|
' brief review|answer',
|
|
2735
2990
|
' profile list|show',
|
|
2736
2991
|
' site status|reindex [--profile <profile-id>] (limited rollout)',
|
|
2992
|
+
' seo-plan show|generate|write|dismiss (limited rollout)',
|
|
2737
2993
|
' source list|add|remove',
|
|
2738
2994
|
' integrations list',
|
|
2739
2995
|
' log add|show',
|
|
@@ -2847,6 +3103,19 @@ function commandHelp(command) {
|
|
|
2847
3103
|
'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
3104
|
'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
3105
|
].join('\n'),
|
|
3106
|
+
'seo-plan': [
|
|
3107
|
+
'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]',
|
|
3108
|
+
' coauthor seo-plan generate [--profile <profile-id>] [--adjust "<text>"] [--wait] [--json]',
|
|
3109
|
+
' coauthor seo-plan write <item-id> [--json]',
|
|
3110
|
+
' coauthor seo-plan dismiss <item-id> [--undo] [--json]',
|
|
3111
|
+
'',
|
|
3112
|
+
'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.',
|
|
3113
|
+
'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.',
|
|
3114
|
+
'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.',
|
|
3115
|
+
'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.',
|
|
3116
|
+
'dismiss hides an idea from the plan; --undo brings it back.',
|
|
3117
|
+
'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.',
|
|
3118
|
+
].join('\n'),
|
|
2850
3119
|
integrations: [
|
|
2851
3120
|
'Usage: coauthor integrations list [--json]',
|
|
2852
3121
|
'',
|
package/dist/parser.js
CHANGED
|
@@ -81,6 +81,9 @@ const OPTIONS = {
|
|
|
81
81
|
variant: { type: 'string' },
|
|
82
82
|
all: { type: 'boolean', default: false },
|
|
83
83
|
kind: { type: 'string' },
|
|
84
|
+
chance: { type: 'string' },
|
|
85
|
+
adjust: { type: 'string' },
|
|
86
|
+
undo: { type: 'boolean', default: false },
|
|
84
87
|
apply: { type: 'boolean', default: false },
|
|
85
88
|
accept: { type: 'string' },
|
|
86
89
|
reject: { type: 'string' },
|
|
@@ -180,6 +183,8 @@ function commandLength(positionals) {
|
|
|
180
183
|
return second && ['list', 'show'].includes(second) ? 2 : 1;
|
|
181
184
|
if (first === 'site')
|
|
182
185
|
return second && ['status', 'reindex'].includes(second) ? 2 : 1;
|
|
186
|
+
if (first === 'seo-plan')
|
|
187
|
+
return second && ['show', 'generate', 'write', 'dismiss'].includes(second) ? 2 : 1;
|
|
183
188
|
if (first === 'integrations')
|
|
184
189
|
return second === 'list' ? 2 : 1;
|
|
185
190
|
if (first === 'source')
|
package/package.json
CHANGED
package/skills/coauthor/SKILL.md
CHANGED
|
@@ -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 writer profiles, PDFs over about 3.3 MB,
|
|
81
|
+
Creating or editing writer profiles, 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
|
|
|
@@ -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. |
|
|
@@ -44,6 +44,29 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
44
44
|
| `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
45
|
| `uploaded_image` | `image generate` on an image the user replaced with their own file. | Use `image edit --edit-prompt "..."`, or `image replace` again. |
|
|
46
46
|
| `not_a_panel` | `image replace` on an article image. | Only slideshow and video panels can be replaced from the CLI. |
|
|
47
|
+
| `not_enabled` | `seo-plan` commands on an account outside the SEO content plan rollout. | Carry on without a plan and choose topics yourself. |
|
|
48
|
+
| `profile_not_found` | `--profile` isn't one of the user's profiles. | `coauthor profile list --json` and use an `id` from it. |
|
|
49
|
+
| `profile_archived` | `seo-plan generate` on an archived profile. | Use another profile, or the user restores it in the web app. |
|
|
50
|
+
| `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. |
|
|
51
|
+
| `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. |
|
|
52
|
+
| `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. |
|
|
53
|
+
| `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. |
|
|
54
|
+
| `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. |
|
|
55
|
+
| `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`. |
|
|
56
|
+
| `worker_unavailable` | The plan service couldn't be reached. Nothing was spent. | Try again in a few minutes. |
|
|
57
|
+
| `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. |
|
|
58
|
+
| `dataforseo_failed` | A plan run couldn't get the search data it needs. | Retry in a few minutes. If it repeats, tell the user. |
|
|
59
|
+
| `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. |
|
|
60
|
+
| `llm_failed` | One of the plan's writing steps didn't complete. | Retry `seo-plan generate --wait`; finished steps are reused. |
|
|
61
|
+
| `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). |
|
|
62
|
+
| `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. |
|
|
63
|
+
| `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). |
|
|
64
|
+
| `coauthor_access_required`, `entitlement_sync_unavailable` | See above; they apply to `seo-plan` too. | As above. |
|
|
65
|
+
| `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. |
|
|
66
|
+
| `plan_updated` | `seo-plan write` on an idea that a newer plan run replaced. | `coauthor seo-plan show --json` for the current ideas. |
|
|
67
|
+
| `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. |
|
|
68
|
+
| `plan_item_not_found` | `seo-plan write` or `dismiss` with an unknown item id. | Take the `id` from `seo-plan show --json`. |
|
|
69
|
+
| `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
70
|
| `usage_error` | The command or its flags are wrong; nothing was sent. | Check `coauthor help <command>` and fix the command. |
|
|
48
71
|
| `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
72
|
|
|
@@ -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 writer profiles, PDFs over about 3.3 MB,
|
|
83
|
+
Creating or editing writer profiles, 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
|
|
|
@@ -519,6 +531,82 @@ Hand the user the folder, or paste from `data.copy`.
|
|
|
519
531
|
|
|
520
532
|
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
533
|
|
|
534
|
+
## references/seo-content-plan.md
|
|
535
|
+
|
|
536
|
+
## SEO content plan (limited rollout)
|
|
537
|
+
|
|
538
|
+
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.
|
|
539
|
+
|
|
540
|
+
Accounts outside the rollout get `not_enabled` from every `seo-plan` command. Carry on without a plan and pick topics yourself.
|
|
541
|
+
|
|
542
|
+
### When to use it
|
|
543
|
+
|
|
544
|
+
- 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.
|
|
545
|
+
- Before a batch of posts: a plan picks posts that can win for this site and orders them.
|
|
546
|
+
- Not for a post the user already has a topic for. Write it as usual (`project create`, optionally `--keyword`).
|
|
547
|
+
|
|
548
|
+
### Cost and timing
|
|
549
|
+
|
|
550
|
+
- 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.
|
|
551
|
+
- The account needs at least 500 credits remaining to start, otherwise `insufficient_credits` (nothing is spent).
|
|
552
|
+
- 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.
|
|
553
|
+
- Only one plan runs per account at a time (`plan_running`).
|
|
554
|
+
|
|
555
|
+
### Commands
|
|
556
|
+
|
|
557
|
+
```
|
|
558
|
+
coauthor seo-plan generate [--profile <id>] [--adjust "<text>"] [--wait] --json
|
|
559
|
+
COAUTHOR_CLI_WAIT_TIMEOUT_MS=540000 coauthor seo-plan generate --wait --json
|
|
560
|
+
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
|
|
561
|
+
coauthor seo-plan write <item-id> --json
|
|
562
|
+
coauthor seo-plan dismiss <item-id> [--undo] --json
|
|
563
|
+
```
|
|
564
|
+
|
|
565
|
+
- 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.
|
|
566
|
+
- `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).
|
|
567
|
+
- `--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.
|
|
568
|
+
- `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.
|
|
569
|
+
- 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.
|
|
570
|
+
|
|
571
|
+
### Reading the plan
|
|
572
|
+
|
|
573
|
+
Each item has a `kind`, which decides what you can do with it:
|
|
574
|
+
|
|
575
|
+
| `kind` | What it is | What to do |
|
|
576
|
+
| --- | --- | --- |
|
|
577
|
+
| `post` | A blog post idea that can rank. | **Write this**: `coauthor seo-plan write <item-id>`. |
|
|
578
|
+
| `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. |
|
|
579
|
+
| `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). |
|
|
580
|
+
| `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. |
|
|
581
|
+
| `covered` | The site already ranks well for it. | Nothing. |
|
|
582
|
+
| `not_checked` | Ideas the plan did not have budget to check. | Optional; a later update may check them. |
|
|
583
|
+
|
|
584
|
+
Other fields to use when you recommend an idea:
|
|
585
|
+
|
|
586
|
+
- `stage`: `Ready to buy`, `Comparing options` or `Learning`. It sets how strong the post's call to action is.
|
|
587
|
+
- `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.
|
|
588
|
+
- `volume`: monthly searches for the idea and its related searches. `keywords` are the related searches the post also covers.
|
|
589
|
+
- `do_next_rank` (1 to 5) marks the plan's own top moves.
|
|
590
|
+
- 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.
|
|
591
|
+
|
|
592
|
+
### Write this
|
|
593
|
+
|
|
594
|
+
`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.
|
|
595
|
+
|
|
596
|
+
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.
|
|
597
|
+
|
|
598
|
+
Writing the same idea twice returns the same project (`created: false`). It never makes a duplicate.
|
|
599
|
+
|
|
600
|
+
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`.
|
|
601
|
+
|
|
602
|
+
### Dismiss
|
|
603
|
+
|
|
604
|
+
`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.
|
|
605
|
+
|
|
606
|
+
### What to tell the user
|
|
607
|
+
|
|
608
|
+
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.
|
|
609
|
+
|
|
522
610
|
## references/troubleshooting.md
|
|
523
611
|
|
|
524
612
|
## Troubleshooting
|
|
@@ -536,7 +624,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
536
624
|
| `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
625
|
| `research_run_state_mismatch` | Research run and project state disagree. | Report it and use the `recovery_commands` in the output. |
|
|
538
626
|
| `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`. |
|
|
627
|
+
| `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
628
|
| `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
629
|
| `byok_not_allowed` | The plan can't use provider keys. | Wait for the credit reset, or the user upgrades in CoAuthor. |
|
|
542
630
|
| `coauthor_access_required` | No active CoAuthor subscription on this account. | Tell the user. `coauthor auth status` still works. |
|
|
@@ -567,6 +655,29 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
567
655
|
| `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
656
|
| `uploaded_image` | `image generate` on an image the user replaced with their own file. | Use `image edit --edit-prompt "..."`, or `image replace` again. |
|
|
569
657
|
| `not_a_panel` | `image replace` on an article image. | Only slideshow and video panels can be replaced from the CLI. |
|
|
658
|
+
| `not_enabled` | `seo-plan` commands on an account outside the SEO content plan rollout. | Carry on without a plan and choose topics yourself. |
|
|
659
|
+
| `profile_not_found` | `--profile` isn't one of the user's profiles. | `coauthor profile list --json` and use an `id` from it. |
|
|
660
|
+
| `profile_archived` | `seo-plan generate` on an archived profile. | Use another profile, or the user restores it in the web app. |
|
|
661
|
+
| `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. |
|
|
662
|
+
| `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. |
|
|
663
|
+
| `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. |
|
|
664
|
+
| `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. |
|
|
665
|
+
| `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. |
|
|
666
|
+
| `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`. |
|
|
667
|
+
| `worker_unavailable` | The plan service couldn't be reached. Nothing was spent. | Try again in a few minutes. |
|
|
668
|
+
| `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. |
|
|
669
|
+
| `dataforseo_failed` | A plan run couldn't get the search data it needs. | Retry in a few minutes. If it repeats, tell the user. |
|
|
670
|
+
| `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. |
|
|
671
|
+
| `llm_failed` | One of the plan's writing steps didn't complete. | Retry `seo-plan generate --wait`; finished steps are reused. |
|
|
672
|
+
| `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). |
|
|
673
|
+
| `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. |
|
|
674
|
+
| `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). |
|
|
675
|
+
| `coauthor_access_required`, `entitlement_sync_unavailable` | See above; they apply to `seo-plan` too. | As above. |
|
|
676
|
+
| `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. |
|
|
677
|
+
| `plan_updated` | `seo-plan write` on an idea that a newer plan run replaced. | `coauthor seo-plan show --json` for the current ideas. |
|
|
678
|
+
| `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. |
|
|
679
|
+
| `plan_item_not_found` | `seo-plan write` or `dismiss` with an unknown item id. | Take the `id` from `seo-plan show --json`. |
|
|
680
|
+
| `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
681
|
| `usage_error` | The command or its flags are wrong; nothing was sent. | Check `coauthor help <command>` and fix the command. |
|
|
571
682
|
| `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
683
|
|