@clickminded/coauthor-cli 0.0.66 → 0.0.68
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 -3
- package/dist/commands.js +31 -17
- package/dist/parser.js +1 -0
- package/package.json +1 -1
- package/skills/coauthor/SKILL.md +2 -2
- package/skills/coauthor/references/brief-and-contract.md +2 -2
- package/skills/coauthor/references/interactive-widgets.md +3 -1
- package/skills/coauthor/references/publishing-and-export.md +1 -0
- package/skills/coauthor/references/seo-content-plan.md +2 -2
- package/skills/coauthor/references/troubleshooting.md +1 -1
- package/skills/cursor/coauthor-cli.mdc +11 -8
package/README.md
CHANGED
|
@@ -46,7 +46,7 @@ A typical piece:
|
|
|
46
46
|
|
|
47
47
|
```sh
|
|
48
48
|
coauthor profile list --json # pick the writer profile (voice, context, image style)
|
|
49
|
-
coauthor site status --json # SEO mode: the profile website's page index
|
|
49
|
+
coauthor site status --json # SEO mode: the profile website's page index
|
|
50
50
|
coauthor project create --title "Post title" --contract @brief.json --profile <profile id> --json
|
|
51
51
|
coauthor source add <id> notes.pdf --json # optional reference documents, before research
|
|
52
52
|
coauthor workflow run <id> --target contract --briefing-mode strict --json # CoAuthor questions the brief
|
|
@@ -82,13 +82,14 @@ coauthor post-details show <id> --json # SEO title, meta
|
|
|
82
82
|
coauthor post-details set <id> --seo-title "..." --json # exports use these as defaults
|
|
83
83
|
coauthor post-details set <id> --live-url https://example.com/post/ # where the post is live (--clear-live-url removes it)
|
|
84
84
|
coauthor draft get <id> --format markdown --frontmatter --json # markdown with YAML frontmatter
|
|
85
|
+
coauthor draft get <id> --format markdown --widgets embed --json # interactives as live iframes, for a site you control
|
|
85
86
|
coauthor export wordpress <id> --yes --json # creates a WordPress draft post (--slug to override)
|
|
86
87
|
coauthor credits <id> --json
|
|
87
88
|
coauthor integrations list --json # WordPress sites and X accounts
|
|
88
89
|
coauthor seo markets --country Mexico --language Spanish --json # Google search data coverage for a market
|
|
89
|
-
coauthor search-brief show <id> --json # SEO mode: target keyword and what ranks
|
|
90
|
+
coauthor search-brief show <id> --json # SEO mode: target keyword and what ranks
|
|
90
91
|
coauthor search-brief set-keyword <id> "email marketing" --json # target your own keyword (--confirm-reset after an outline)
|
|
91
|
-
coauthor seo-plan generate --wait --json # SEO content plan for the default profile: ~420 credits, 5-12 minutes
|
|
92
|
+
coauthor seo-plan generate --wait --json # SEO content plan for the default profile: ~420 credits, 5-12 minutes
|
|
92
93
|
coauthor seo-plan show --kind post --json # strategy, Do next moves, counts, and the post ideas
|
|
93
94
|
coauthor seo-plan write <item-id> --json # open a project for a post idea, then continue with workflow run
|
|
94
95
|
coauthor seo-plan dismiss <item-id> --json # hide an idea (--undo brings it back)
|
package/dist/commands.js
CHANGED
|
@@ -631,11 +631,21 @@ async function runDraftCommand(action, input, context) {
|
|
|
631
631
|
if (frontmatter && format?.trim().toLowerCase() !== 'markdown') {
|
|
632
632
|
throw new Error('--frontmatter only applies to --format markdown.');
|
|
633
633
|
}
|
|
634
|
+
const widgets = getString(input.values, 'widgets')?.trim().toLowerCase();
|
|
635
|
+
if (widgets !== undefined) {
|
|
636
|
+
if (!['image', 'embed'].includes(widgets))
|
|
637
|
+
throw new Error(`--widgets must be image or embed (got "${widgets}").`);
|
|
638
|
+
if (!['markdown', 'html'].includes(format?.trim().toLowerCase() ?? '')) {
|
|
639
|
+
throw new Error('--widgets only applies to --format markdown or html.');
|
|
640
|
+
}
|
|
641
|
+
}
|
|
634
642
|
const query = new URLSearchParams();
|
|
635
643
|
if (format)
|
|
636
644
|
query.set('format', format);
|
|
637
645
|
if (frontmatter)
|
|
638
646
|
query.set('frontmatter', '1');
|
|
647
|
+
if (widgets)
|
|
648
|
+
query.set('widgets', widgets);
|
|
639
649
|
const suffix = query.toString();
|
|
640
650
|
const data = await client.request({ path: suffix ? `${basePath}/get?${suffix}` : `${basePath}/get` });
|
|
641
651
|
return { ok: true, data };
|
|
@@ -805,7 +815,7 @@ function searchBriefMessage(data) {
|
|
|
805
815
|
return target.explanation;
|
|
806
816
|
return typeof brief.status === 'string' ? `Search targeting: ${brief.status}.` : undefined;
|
|
807
817
|
}
|
|
808
|
-
// SEO mode
|
|
818
|
+
// SEO mode: the keyword this post targets and the research behind it.
|
|
809
819
|
async function runSearchBriefCommand(action, input, client) {
|
|
810
820
|
const projectId = requireProjectId(input);
|
|
811
821
|
const path = `projects/${encodeURIComponent(projectId)}/search-brief`;
|
|
@@ -1964,7 +1974,7 @@ function widgetStateLabel(widget) {
|
|
|
1964
1974
|
function widgetSpec(widget) {
|
|
1965
1975
|
return widget.spec && typeof widget.spec === 'object' && !Array.isArray(widget.spec) ? widget.spec : {};
|
|
1966
1976
|
}
|
|
1967
|
-
function describeWidget(widget) {
|
|
1977
|
+
function describeWidget(widget, options = {}) {
|
|
1968
1978
|
const spec = widgetSpec(widget);
|
|
1969
1979
|
const lines = [
|
|
1970
1980
|
`${String(widget.id)} ${String(spec.title ?? '(untitled)')} [${widgetStateLabel(widget)}]`,
|
|
@@ -1975,6 +1985,9 @@ function describeWidget(widget) {
|
|
|
1975
1985
|
];
|
|
1976
1986
|
if (typeof widget.embed_url === 'string')
|
|
1977
1987
|
lines.push(` embed: ${widget.embed_url}`);
|
|
1988
|
+
if (options.embedCode && typeof widget.embed_code === 'string' && widget.embed_code) {
|
|
1989
|
+
lines.push(' embed code:', ...widget.embed_code.split('\n').map((line) => ` ${line}`));
|
|
1990
|
+
}
|
|
1978
1991
|
if (widget.fact_check_warning)
|
|
1979
1992
|
lines.push(` fact check: ${String(widget.fact_check_warning)}`);
|
|
1980
1993
|
const error = widgetError(widget);
|
|
@@ -1989,7 +2002,7 @@ function widgetsListMessage(data) {
|
|
|
1989
2002
|
}
|
|
1990
2003
|
const model = getResponseValue(data, 'model');
|
|
1991
2004
|
const placeholders = widgets.filter((widget) => widget.current_version == null && widget.build_state === 'idle').length;
|
|
1992
|
-
const lines = widgets.map(describeWidget);
|
|
2005
|
+
const lines = widgets.map((widget) => describeWidget(widget, { embedCode: true }));
|
|
1993
2006
|
if (model) {
|
|
1994
2007
|
lines.push('', `Build model: ${String(model.label ?? model.id)}. One build spends up to ${String(model.cap)} credits (an edit up to ${String(model.edit_cap)}).`);
|
|
1995
2008
|
}
|
|
@@ -2046,7 +2059,7 @@ function widgetsWaitResult(projectId, result, resumeCommand, doneWord) {
|
|
|
2046
2059
|
}
|
|
2047
2060
|
return {
|
|
2048
2061
|
ok: true,
|
|
2049
|
-
message: `${widgets.length} interactive${widgets.length === 1 ? '' : 's'} ${doneWord}.\n${widgets.map(describeWidget).join('\n')}`,
|
|
2062
|
+
message: `${widgets.length} interactive${widgets.length === 1 ? '' : 's'} ${doneWord}.\n${widgets.map((widget) => describeWidget(widget)).join('\n')}`,
|
|
2050
2063
|
messageIncludesData: true,
|
|
2051
2064
|
data,
|
|
2052
2065
|
};
|
|
@@ -2088,7 +2101,7 @@ async function runWidgetsCommand(action, input, client) {
|
|
|
2088
2101
|
const waited = await waitForWidgets(client, projectId, [id], [widget]);
|
|
2089
2102
|
return widgetsWaitResult(projectId, waited, `coauthor widgets status ${projectId} ${id} --wait`, 'ready');
|
|
2090
2103
|
}
|
|
2091
|
-
return { ok: true, message: widget ? describeWidget(widget) : undefined, messageIncludesData: Boolean(widget), data };
|
|
2104
|
+
return { ok: true, message: widget ? describeWidget(widget, { embedCode: true }) : undefined, messageIncludesData: Boolean(widget), data };
|
|
2092
2105
|
}
|
|
2093
2106
|
if (action === 'build') {
|
|
2094
2107
|
const id = needWidget('build');
|
|
@@ -2197,7 +2210,7 @@ function siteMessage(data, request) {
|
|
|
2197
2210
|
return `The last index of ${origin} failed. Try \`coauthor site reindex\`.`;
|
|
2198
2211
|
return `${origin} has not been indexed yet.`;
|
|
2199
2212
|
}
|
|
2200
|
-
// SEO mode
|
|
2213
|
+
// SEO mode: the site index behind a profile's website, which
|
|
2201
2214
|
// internal links and own-site evidence read. Defaults to the default profile.
|
|
2202
2215
|
async function runSiteCommand(action, input, client) {
|
|
2203
2216
|
if (action && !['status', 'reindex'].includes(action))
|
|
@@ -2218,7 +2231,7 @@ async function runSiteCommand(action, input, client) {
|
|
|
2218
2231
|
const data = await client.request({ path });
|
|
2219
2232
|
return { ok: true, message: siteMessage(data), data };
|
|
2220
2233
|
}
|
|
2221
|
-
// ─── SEO content plan
|
|
2234
|
+
// ─── SEO content plan ────────────────────────────────────────────────────────
|
|
2222
2235
|
const SEO_PLAN_KINDS = ['post', 'improve', 'page', 'left_out', 'covered', 'not_checked'];
|
|
2223
2236
|
const SEO_PLAN_KIND_LABELS = {
|
|
2224
2237
|
post: 'posts to write',
|
|
@@ -3442,18 +3455,18 @@ export function helpResult(command = []) {
|
|
|
3442
3455
|
' brief review|answer',
|
|
3443
3456
|
' profile list|show|update (update: --interactive-widgets on|off)',
|
|
3444
3457
|
' widgets list|status|build|build-all|use-image|edit|delete (interactives, beta)',
|
|
3445
|
-
' site status|reindex [--profile <profile-id>]
|
|
3446
|
-
' seo-plan show|generate|write|dismiss|done|monthly-check|results
|
|
3458
|
+
' site status|reindex [--profile <profile-id>]',
|
|
3459
|
+
' seo-plan show|generate|write|dismiss|done|monthly-check|results',
|
|
3447
3460
|
' source list|add|remove',
|
|
3448
3461
|
' integrations list',
|
|
3449
3462
|
' log add|show',
|
|
3450
3463
|
' research run|status|structured',
|
|
3451
3464
|
' draft generate|status|get|save|revise',
|
|
3452
3465
|
' draft revision show|apply|discard',
|
|
3453
|
-
' draft get supports --format json|markdown|html|text (--frontmatter adds post details to markdown)',
|
|
3466
|
+
' draft get supports --format json|markdown|html|text (--frontmatter adds post details to markdown; --widgets embed exports interactives as live iframes)',
|
|
3454
3467
|
' post-details show|set',
|
|
3455
3468
|
' seo markets [--country <country>] [--language <language>]',
|
|
3456
|
-
' search-brief show|set-keyword|set-mode
|
|
3469
|
+
' search-brief show|set-keyword|set-mode',
|
|
3457
3470
|
' workflow show|status|advance|run|rewind|approve|resume',
|
|
3458
3471
|
' workflow run/advance supports --briefing-mode auto|strict|off and --require-brief-review',
|
|
3459
3472
|
' image list|status|show|generate|edit|metadata|replace',
|
|
@@ -3495,8 +3508,8 @@ function commandHelp(command) {
|
|
|
3495
3508
|
'',
|
|
3496
3509
|
'Creates a project. When --topic or --audience is provided, CoAuthor seeds the saved contract so workflow briefing review can use that context.',
|
|
3497
3510
|
'--contract accepts a JSON editorial contract object. Top-level --topic and --audience fill missing contract topic/audience fields.',
|
|
3498
|
-
'--keyword (SEO mode
|
|
3499
|
-
'--seo (SEO mode
|
|
3511
|
+
'--keyword (SEO mode) sets the Google search keyword the post targets. It is researched when the outline is generated and never replaced automatically.',
|
|
3512
|
+
'--seo (SEO mode) sets how the post uses search: optimize (the outline covers what ranks and keeps your angle), my-way (written as planned; the keyword goes only in the SEO title, meta description and slug) or off. Without it, the profile\'s Search optimization setting applies, and "Ask each time" optimizes.',
|
|
3500
3513
|
].join('\n'),
|
|
3501
3514
|
'workflow run': [
|
|
3502
3515
|
'Usage: coauthor workflow run <project-id> --target <outline|research|draft> [--planning-model <id>] [--writing-model <id>] [--wait] [--briefing-mode auto|strict|off] [--json]',
|
|
@@ -3541,10 +3554,11 @@ function commandHelp(command) {
|
|
|
3541
3554
|
'--widget-model (interactives beta) picks the model that builds interactives: claude-opus-5-5 (default) or claude-sonnet-5-5.',
|
|
3542
3555
|
].join('\n'),
|
|
3543
3556
|
'draft get': [
|
|
3544
|
-
'Usage: coauthor draft get <project-id> [--format json|markdown|html|text] [--frontmatter] [--json]',
|
|
3557
|
+
'Usage: coauthor draft get <project-id> [--format json|markdown|html|text] [--frontmatter] [--widgets image|embed] [--json]',
|
|
3545
3558
|
'',
|
|
3546
3559
|
'Retrieves a saved generated draft. Chat responses are available through coauthor chat show.',
|
|
3547
3560
|
'--frontmatter (markdown only) prepends YAML frontmatter from the post details: title, seo_title, description, slug, excerpt, and the featured image. Posts without post details get no frontmatter.',
|
|
3561
|
+
'--widgets (markdown or html only) chooses how built interactives export. image (default) is the linked poster image, safe for email and newsletters. embed is the live sandboxed iframe plus one embed.js script, for a website you control (Astro, Hugo, Next, custom HTML). In markdown the iframe is a raw HTML block that is also valid MDX.',
|
|
3548
3562
|
].join('\n'),
|
|
3549
3563
|
'draft save': [
|
|
3550
3564
|
'Usage: coauthor draft save <project-id> --data @payload.json [--force] [--json]',
|
|
@@ -3571,7 +3585,7 @@ function commandHelp(command) {
|
|
|
3571
3585
|
'Usage: coauthor site status [--profile <profile-id>] [--json]',
|
|
3572
3586
|
' coauthor site reindex [--profile <profile-id>] [--json]',
|
|
3573
3587
|
'',
|
|
3574
|
-
'SEO mode
|
|
3588
|
+
'SEO mode. CoAuthor reads the website on a writer profile from its sitemap (up to 500 recent pages) to link new posts to it and cite its own pages as evidence.',
|
|
3575
3589
|
'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.',
|
|
3576
3590
|
'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.',
|
|
3577
3591
|
].join('\n'),
|
|
@@ -3584,7 +3598,7 @@ function commandHelp(command) {
|
|
|
3584
3598
|
' coauthor seo-plan monthly-check on|off [--profile <profile-id>] [--json]',
|
|
3585
3599
|
' coauthor seo-plan results [--profile <profile-id>] [--json]',
|
|
3586
3600
|
'',
|
|
3587
|
-
'SEO content plan
|
|
3601
|
+
'SEO content plan: 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.',
|
|
3588
3602
|
'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.',
|
|
3589
3603
|
'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.',
|
|
3590
3604
|
'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.',
|
|
@@ -3716,7 +3730,7 @@ function commandHelp(command) {
|
|
|
3716
3730
|
' coauthor search-brief set-keyword <project-id> "<keyword>" [--confirm-reset] [--json]',
|
|
3717
3731
|
' coauthor search-brief set-mode <project-id> <optimize|my-way|off> [--confirm-reset] [--json]',
|
|
3718
3732
|
'',
|
|
3719
|
-
'SEO mode
|
|
3733
|
+
'SEO mode. show prints the keyword this post targets, its volume, difficulty and market, and what the ranking pages cover and miss.',
|
|
3720
3734
|
'set-keyword targets a keyword you choose; CoAuthor researches it (SEO research credits) and never replaces it automatically.',
|
|
3721
3735
|
'If an outline exists, set-keyword answers confirmation_required: changing the keyword regenerates the outline, research and draft. Repeat with --confirm-reset to proceed.',
|
|
3722
3736
|
'set-mode chooses how the post uses its keyword: optimize (reads what ranks; SEO research credits), my-way (no ranking-page read; the keyword goes only in the SEO title, meta description and slug) or off. optimize and my-way need a search target (no_search_target otherwise). After an outline exists, a change answers confirmation_required like set-keyword.',
|
package/dist/parser.js
CHANGED
|
@@ -60,6 +60,7 @@ const OPTIONS = {
|
|
|
60
60
|
seo: { type: 'string' },
|
|
61
61
|
'confirm-reset': { type: 'boolean', default: false },
|
|
62
62
|
frontmatter: { type: 'boolean', default: false },
|
|
63
|
+
widgets: { type: 'string' },
|
|
63
64
|
country: { type: 'string' },
|
|
64
65
|
language: { type: 'string' },
|
|
65
66
|
status: { type: 'string' },
|
package/package.json
CHANGED
package/skills/coauthor/SKILL.md
CHANGED
|
@@ -61,7 +61,7 @@ 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
|
|
64
|
+
## SEO content plan
|
|
65
65
|
|
|
66
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
67
|
|
|
@@ -73,7 +73,7 @@ When the user wants to know what to write about for a business site, or asks for
|
|
|
73
73
|
- `coauthor seo-plan monthly-check on|off --json` switches the plan's monthly check, which re-checks where each published post ranks on Google and refreshes the plan's chances. It uses credits (about 30 a month; the first check is free). `show` returns `data.monthly_check` (`enabled`, `next_check_at`, `estimate_credits`), or `null` while it is not switched on for the account.
|
|
74
74
|
- `coauthor seo-plan results --json` reads the last monthly check: where each tracked post ranks on Google (`data.results`: `position`, `previous_position`, `movement`, `ranking_url`), the posts that have a target search but no live address yet, except ones marked as still being edited (`data.missing_urls`), and how the check went (`data.last_check`). Posts without a live address are not tracked; set one with `coauthor post-details set <id> --live-url <url>`.
|
|
75
75
|
|
|
76
|
-
Details, item fields, and what each kind means: `references/seo-content-plan.md`. If a command answers `not_enabled`,
|
|
76
|
+
Details, item fields, and what each kind means: `references/seo-content-plan.md`. If a command answers `not_enabled`, SEO content plans are not switched on for this account; carry on without a plan.
|
|
77
77
|
|
|
78
78
|
## Housekeeping
|
|
79
79
|
|
|
@@ -13,7 +13,7 @@ All fields are optional and omitted ones get defaults, but always include at lea
|
|
|
13
13
|
## Profiles and source documents
|
|
14
14
|
|
|
15
15
|
- `coauthor profile list --json` shows the user's writer profiles: `is_default` marks the one new projects get without `--profile`, plus a `summary` and the `visual_style`. `coauthor profile show <profile id> --json` shows the voice, writer context, and business context in full, plus the profile's `website` and `search_country` (null until set in the web app; the search language follows the language each post is written in). Pass `--profile <id>` to `project create`; the profile can't be changed later, so pick deliberately. Profiles are created and edited in the web app (`manage_url`).
|
|
16
|
-
- `coauthor site status [--profile <id>] --json` (SEO mode
|
|
16
|
+
- `coauthor site status [--profile <id>] --json` (SEO mode) shows how much of the profile's website CoAuthor has read (`site.status`: pending, indexing, ready, blocked, failed; `site.indexed_pages`). SEO posts link to those pages and cite them as evidence. `coauthor site reindex` refreshes it after the user publishes new pages; it is free and needs no confirmation.
|
|
17
17
|
- `coauthor source add <id> <file>` uploads a reference document CoAuthor's research reads (PDF up to about 3.3 MB through the CLI, .txt or .md up to 512 KB, 5 per project). `coauthor source list <id> --json` shows them; `coauthor source remove <id> <source id> --yes` deletes one.
|
|
18
18
|
- Add sources before research runs. Adding or removing one after research marks the research and draft stale (the output says `research_invalidated`), so research has to run again.
|
|
19
19
|
|
|
@@ -21,7 +21,7 @@ All fields are optional and omitted ones get defaults, but always include at lea
|
|
|
21
21
|
|
|
22
22
|
`coauthor seo markets --country <country> --language <language> --json` checks whether CoAuthor has Google search data for a country and language (names or codes both work). `data.support.tier` is `full` (search volume, keyword difficulty, and ranking checks), `limited` (CoAuthor can analyze what ranks, but not difficulty or existing rankings), `unsupported`, or `unknown_country`. `data.explanation.message` is a sentence you can give the user, and `data.explanation.alternatives` lists covered languages for that country and covered countries for that language. Use `--country` or `--language` alone to list one side; markets are country-level.
|
|
23
23
|
|
|
24
|
-
## Search target
|
|
24
|
+
## Search target
|
|
25
25
|
|
|
26
26
|
SEO mode is rolling out gradually; accounts outside it get `feature_unavailable` from these commands. When it is on, a post on a searchable topic targets one Google keyword chosen from real search data, and the outline and draft are built around it.
|
|
27
27
|
- You don't have to do anything: when the outline is generated, CoAuthor checks search demand, picks a keyword the user's site can win, and reads what currently ranks (table stakes, gaps, intent, format, a length hint). This costs SEO research credits and is skipped for topics nobody searches for.
|
|
@@ -27,7 +27,9 @@ coauthor models preferences set --widget-model claude-opus-5-5|claude-sonnet-5-5
|
|
|
27
27
|
- `build-all` with no ids builds every placeholder; with ids, only those.
|
|
28
28
|
- `use-image` is for a placeholder that took over a planned image (`replaces_image: true`). It turns the node in the draft back into an image placeholder (it updates the draft for you); then generate it with `coauthor image generate <project-id> --placeholder-id <placeholder-id>`. If `document_updated` is false, `document_status` says why: `already_removed` means a repeat (the swap was already done, nothing to fix); `not_updated` is a real failure and `document_note` has the manual fix. The call is safe to repeat.
|
|
29
29
|
- `edit` takes a plain instruction of up to 500 characters and rebuilds the widget. `edit` and `delete` change every published copy, so both need `--yes`: confirm with the user first. `delete` removes the interactive everywhere, including posts already published, and cannot be undone. It also removes the node from the draft.
|
|
30
|
-
-
|
|
30
|
+
- `status` and `list` print an `embed code:` block for each built widget (an iframe plus the one `embed.js` script, ready to paste into any page) and return it as `embed_code` in the JSON.
|
|
31
|
+
- By default a built widget exports as its poster image linked to the live version in markdown and HTML (`draft get --format markdown`). Add `--widgets embed` to get the live sandboxed iframe instead: `coauthor draft get <id> --format markdown --widgets embed --json` (or `--format html`). Use `embed` when publishing to a website the user controls (Astro, Hugo, Next.js, plain HTML). Keep the default image form for email, newsletters, and anywhere that strips iframes. `--widgets` only applies to `--format markdown` and `html`; `--format text` stays the caption plus the link. WordPress export chooses automatically and ignores the flag.
|
|
32
|
+
- The markdown embed form is a raw HTML block (`<figure class="coauthor-widget"><iframe ...></iframe></figure>`) and one `<script src="https://figurehost.com/embed.js" async></script>` at the end of the document. The attributes are valid in plain Markdown and in MDX (no inline `style`, braces in captions escaped). If the site renders its own layout and already loads `embed.js` once, delete the trailing script line to avoid loading it twice. The iframe keeps its `sandbox="allow-scripts"` and resizes itself once `embed.js` runs.
|
|
31
33
|
|
|
32
34
|
## Limitations to tell the user
|
|
33
35
|
|
|
@@ -5,6 +5,7 @@
|
|
|
5
5
|
```sh
|
|
6
6
|
coauthor draft get <id> --format markdown --json # data.markdown, images as markdown image links
|
|
7
7
|
coauthor draft get <id> --format html --json # data.html, images as <img> tags
|
|
8
|
+
coauthor draft get <id> --format markdown --widgets embed --json # website you control: interactives as live iframes (see interactive-widgets.md)
|
|
8
9
|
coauthor draft get <id> --format text --json # data.text, plain text with image URLs
|
|
9
10
|
coauthor draft get <id> --format json --json # data.content, the editor document (for edits)
|
|
10
11
|
```
|
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
# SEO content plan
|
|
1
|
+
# SEO content plan
|
|
2
2
|
|
|
3
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
4
|
|
|
5
|
-
|
|
5
|
+
SEO content plans are open to every CoAuthor account. An account where they are not switched on gets `not_enabled` from every `seo-plan` command; carry on without a plan and pick topics yourself.
|
|
6
6
|
|
|
7
7
|
## When to use it
|
|
8
8
|
|
|
@@ -54,7 +54,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
54
54
|
| `structured_brief` | `image generate --prompt` on a comparison or technical-diagram image, which is built from structured fields. | Generate without `--prompt`, then `image edit --edit-prompt "..."`. |
|
|
55
55
|
| `uploaded_image` | `image generate` on an image the user replaced with their own file. | Use `image edit --edit-prompt "..."`, or `image replace` again. |
|
|
56
56
|
| `not_a_panel` | `image replace` on an article image. | Only slideshow and video panels can be replaced from the CLI. |
|
|
57
|
-
| `not_enabled` | `seo-plan` commands on an account
|
|
57
|
+
| `not_enabled` | `seo-plan` commands on an account where SEO content plans are not switched on. | Carry on without a plan and choose topics yourself. |
|
|
58
58
|
| `profile_not_found` | `--profile` isn't one of the user's profiles. | `coauthor profile list --json` and use an `id` from it. |
|
|
59
59
|
| `profile_archived` | `seo-plan generate` on an archived profile. | Use another profile, or the user restores it in the web app. |
|
|
60
60
|
| `site_required` | `seo-plan generate` on a profile with no website. | Ask the user to add the website to the profile in the web app. |
|
|
@@ -63,7 +63,7 @@ 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
|
|
66
|
+
## SEO content plan
|
|
67
67
|
|
|
68
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
69
|
|
|
@@ -75,7 +75,7 @@ When the user wants to know what to write about for a business site, or asks for
|
|
|
75
75
|
- `coauthor seo-plan monthly-check on|off --json` switches the plan's monthly check, which re-checks where each published post ranks on Google and refreshes the plan's chances. It uses credits (about 30 a month; the first check is free). `show` returns `data.monthly_check` (`enabled`, `next_check_at`, `estimate_credits`), or `null` while it is not switched on for the account.
|
|
76
76
|
- `coauthor seo-plan results --json` reads the last monthly check: where each tracked post ranks on Google (`data.results`: `position`, `previous_position`, `movement`, `ranking_url`), the posts that have a target search but no live address yet, except ones marked as still being edited (`data.missing_urls`), and how the check went (`data.last_check`). Posts without a live address are not tracked; set one with `coauthor post-details set <id> --live-url <url>`.
|
|
77
77
|
|
|
78
|
-
Details, item fields, and what each kind means: `references/seo-content-plan.md`. If a command answers `not_enabled`,
|
|
78
|
+
Details, item fields, and what each kind means: `references/seo-content-plan.md`. If a command answers `not_enabled`, SEO content plans are not switched on for this account; carry on without a plan.
|
|
79
79
|
|
|
80
80
|
## Housekeeping
|
|
81
81
|
|
|
@@ -106,7 +106,7 @@ All fields are optional and omitted ones get defaults, but always include at lea
|
|
|
106
106
|
### Profiles and source documents
|
|
107
107
|
|
|
108
108
|
- `coauthor profile list --json` shows the user's writer profiles: `is_default` marks the one new projects get without `--profile`, plus a `summary` and the `visual_style`. `coauthor profile show <profile id> --json` shows the voice, writer context, and business context in full, plus the profile's `website` and `search_country` (null until set in the web app; the search language follows the language each post is written in). Pass `--profile <id>` to `project create`; the profile can't be changed later, so pick deliberately. Profiles are created and edited in the web app (`manage_url`).
|
|
109
|
-
- `coauthor site status [--profile <id>] --json` (SEO mode
|
|
109
|
+
- `coauthor site status [--profile <id>] --json` (SEO mode) shows how much of the profile's website CoAuthor has read (`site.status`: pending, indexing, ready, blocked, failed; `site.indexed_pages`). SEO posts link to those pages and cite them as evidence. `coauthor site reindex` refreshes it after the user publishes new pages; it is free and needs no confirmation.
|
|
110
110
|
- `coauthor source add <id> <file>` uploads a reference document CoAuthor's research reads (PDF up to about 3.3 MB through the CLI, .txt or .md up to 512 KB, 5 per project). `coauthor source list <id> --json` shows them; `coauthor source remove <id> <source id> --yes` deletes one.
|
|
111
111
|
- Add sources before research runs. Adding or removing one after research marks the research and draft stale (the output says `research_invalidated`), so research has to run again.
|
|
112
112
|
|
|
@@ -114,7 +114,7 @@ All fields are optional and omitted ones get defaults, but always include at lea
|
|
|
114
114
|
|
|
115
115
|
`coauthor seo markets --country <country> --language <language> --json` checks whether CoAuthor has Google search data for a country and language (names or codes both work). `data.support.tier` is `full` (search volume, keyword difficulty, and ranking checks), `limited` (CoAuthor can analyze what ranks, but not difficulty or existing rankings), `unsupported`, or `unknown_country`. `data.explanation.message` is a sentence you can give the user, and `data.explanation.alternatives` lists covered languages for that country and covered countries for that language. Use `--country` or `--language` alone to list one side; markets are country-level.
|
|
116
116
|
|
|
117
|
-
### Search target
|
|
117
|
+
### Search target
|
|
118
118
|
|
|
119
119
|
SEO mode is rolling out gradually; accounts outside it get `feature_unavailable` from these commands. When it is on, a post on a searchable topic targets one Google keyword chosen from real search data, and the outline and draft are built around it.
|
|
120
120
|
- You don't have to do anything: when the outline is generated, CoAuthor checks search demand, picks a keyword the user's site can win, and reads what currently ranks (table stakes, gaps, intent, format, a length hint). This costs SEO research credits and is skipped for topics nobody searches for.
|
|
@@ -425,7 +425,9 @@ coauthor models preferences set --widget-model claude-opus-5-5|claude-sonnet-5-5
|
|
|
425
425
|
- `build-all` with no ids builds every placeholder; with ids, only those.
|
|
426
426
|
- `use-image` is for a placeholder that took over a planned image (`replaces_image: true`). It turns the node in the draft back into an image placeholder (it updates the draft for you); then generate it with `coauthor image generate <project-id> --placeholder-id <placeholder-id>`. If `document_updated` is false, `document_status` says why: `already_removed` means a repeat (the swap was already done, nothing to fix); `not_updated` is a real failure and `document_note` has the manual fix. The call is safe to repeat.
|
|
427
427
|
- `edit` takes a plain instruction of up to 500 characters and rebuilds the widget. `edit` and `delete` change every published copy, so both need `--yes`: confirm with the user first. `delete` removes the interactive everywhere, including posts already published, and cannot be undone. It also removes the node from the draft.
|
|
428
|
-
-
|
|
428
|
+
- `status` and `list` print an `embed code:` block for each built widget (an iframe plus the one `embed.js` script, ready to paste into any page) and return it as `embed_code` in the JSON.
|
|
429
|
+
- By default a built widget exports as its poster image linked to the live version in markdown and HTML (`draft get --format markdown`). Add `--widgets embed` to get the live sandboxed iframe instead: `coauthor draft get <id> --format markdown --widgets embed --json` (or `--format html`). Use `embed` when publishing to a website the user controls (Astro, Hugo, Next.js, plain HTML). Keep the default image form for email, newsletters, and anywhere that strips iframes. `--widgets` only applies to `--format markdown` and `html`; `--format text` stays the caption plus the link. WordPress export chooses automatically and ignores the flag.
|
|
430
|
+
- The markdown embed form is a raw HTML block (`<figure class="coauthor-widget"><iframe ...></iframe></figure>`) and one `<script src="https://figurehost.com/embed.js" async></script>` at the end of the document. The attributes are valid in plain Markdown and in MDX (no inline `style`, braces in captions escaped). If the site renders its own layout and already loads `embed.js` once, delete the trailing script line to avoid loading it twice. The iframe keeps its `sandbox="allow-scripts"` and resizes itself once `embed.js` runs.
|
|
429
431
|
|
|
430
432
|
### Limitations to tell the user
|
|
431
433
|
|
|
@@ -446,6 +448,7 @@ Error codes: `references/troubleshooting.md`.
|
|
|
446
448
|
```sh
|
|
447
449
|
coauthor draft get <id> --format markdown --json # data.markdown, images as markdown image links
|
|
448
450
|
coauthor draft get <id> --format html --json # data.html, images as <img> tags
|
|
451
|
+
coauthor draft get <id> --format markdown --widgets embed --json # website you control: interactives as live iframes (see interactive-widgets.md)
|
|
449
452
|
coauthor draft get <id> --format text --json # data.text, plain text with image URLs
|
|
450
453
|
coauthor draft get <id> --format json --json # data.content, the editor document (for edits)
|
|
451
454
|
```
|
|
@@ -585,11 +588,11 @@ Only X can be posted directly. A thread posts with `coauthor publish thread <id>
|
|
|
585
588
|
|
|
586
589
|
## references/seo-content-plan.md
|
|
587
590
|
|
|
588
|
-
## SEO content plan
|
|
591
|
+
## SEO content plan
|
|
589
592
|
|
|
590
593
|
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.
|
|
591
594
|
|
|
592
|
-
|
|
595
|
+
SEO content plans are open to every CoAuthor account. An account where they are not switched on gets `not_enabled` from every `seo-plan` command; carry on without a plan and pick topics yourself.
|
|
593
596
|
|
|
594
597
|
### When to use it
|
|
595
598
|
|
|
@@ -746,7 +749,7 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
|
|
|
746
749
|
| `structured_brief` | `image generate --prompt` on a comparison or technical-diagram image, which is built from structured fields. | Generate without `--prompt`, then `image edit --edit-prompt "..."`. |
|
|
747
750
|
| `uploaded_image` | `image generate` on an image the user replaced with their own file. | Use `image edit --edit-prompt "..."`, or `image replace` again. |
|
|
748
751
|
| `not_a_panel` | `image replace` on an article image. | Only slideshow and video panels can be replaced from the CLI. |
|
|
749
|
-
| `not_enabled` | `seo-plan` commands on an account
|
|
752
|
+
| `not_enabled` | `seo-plan` commands on an account where SEO content plans are not switched on. | Carry on without a plan and choose topics yourself. |
|
|
750
753
|
| `profile_not_found` | `--profile` isn't one of the user's profiles. | `coauthor profile list --json` and use an `id` from it. |
|
|
751
754
|
| `profile_archived` | `seo-plan generate` on an archived profile. | Use another profile, or the user restores it in the web app. |
|
|
752
755
|
| `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. |
|