@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 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 (limited rollout)
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 (limited rollout)
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 (limited rollout)
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 (limited rollout): the keyword this post targets and the research behind it.
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 (limited rollout): the site index behind a profile's website, which
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 (limited rollout) ──────────────────────────────────────
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>] (limited rollout)',
3446
- ' seo-plan show|generate|write|dismiss|done|monthly-check|results (limited rollout)',
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 (limited rollout)',
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, limited rollout) sets the Google search keyword the post targets. It is researched when the outline is generated and never replaced automatically.',
3499
- '--seo (SEO mode, limited rollout) 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.',
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 (limited rollout). 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.',
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 (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.',
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 (limited rollout). show prints the keyword this post targets, its volume, difficulty and market, and what the ranking pages cover and miss.',
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.66",
3
+ "version": "0.0.68",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -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 (limited rollout)
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`, the account is outside the rollout; carry on without a plan.
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, limited rollout) 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.
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 (limited rollout)
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
- - A built widget exports as its poster image linked to the live version in markdown and HTML (`draft get --format markdown`), and live in WordPress when the connection allows it.
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 (limited rollout)
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
- Accounts outside the rollout get `not_enabled` from every `seo-plan` command. Carry on without a plan and pick topics yourself.
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 outside the SEO content plan rollout. | Carry on without a plan and choose topics yourself. |
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 (limited rollout)
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`, the account is outside the rollout; carry on without a plan.
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, limited rollout) 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.
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 (limited rollout)
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
- - A built widget exports as its poster image linked to the live version in markdown and HTML (`draft get --format markdown`), and live in WordPress when the connection allows it.
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 (limited rollout)
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
- Accounts outside the rollout get `not_enabled` from every `seo-plan` command. Carry on without a plan and pick topics yourself.
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 outside the SEO content plan rollout. | Carry on without a plan and choose topics yourself. |
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. |