@clickminded/coauthor-cli 0.0.67 → 0.0.69

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
@@ -80,8 +80,9 @@ coauthor repurpose download <id> --out ./social # copy-ready files
80
80
  coauthor share <id> --json # public read-only link
81
81
  coauthor post-details show <id> --json # SEO title, meta description, slug, excerpt
82
82
  coauthor post-details set <id> --seo-title "..." --json # exports use these as defaults
83
- coauthor post-details set <id> --live-url https://example.com/post/ # where the post is live (--clear-live-url removes it)
83
+ coauthor post-details set <id> --live-url https://example.com/post/ # where the post is live (--clear-live-url removes it; --track-search "..." sets the search to track for a post without a target search)
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
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 };
@@ -737,6 +747,18 @@ function postSeoMessage(data) {
737
747
  parts.push(`${count('fail')} missing`);
738
748
  return `Targeting "${seo.keyword}": SEO checklist ${parts.join(', ')}. Details in data.seo.checks.`;
739
749
  }
750
+ // Posts written without a target search are tracked by the monthly check through the live address and search on `tracking`.
751
+ function postTrackingMessage(data) {
752
+ const tracking = getResponseValue(data, 'tracking');
753
+ if (!tracking)
754
+ return '';
755
+ const url = typeof tracking.published_url === 'string' && tracking.published_url ? tracking.published_url : null;
756
+ const keyword = typeof tracking.tracking_keyword === 'string' && tracking.tracking_keyword ? tracking.tracking_keyword : null;
757
+ if (!url && !keyword)
758
+ return '';
759
+ const picked = tracking.tracking_keyword_source === 'ranked' || tracking.tracking_keyword_source === 'suggested' ? ' (picked by CoAuthor)' : '';
760
+ return ` Tracked by the monthly check: ${url ? `live at ${url}` : 'no live address yet'}; ${keyword ? `search "${keyword}"${picked}` : 'no search yet, the next check picks one'}.`;
761
+ }
740
762
  async function runPostDetailsCommand(action, input, client) {
741
763
  const projectId = requireProjectId(input);
742
764
  const path = `projects/${encodeURIComponent(projectId)}/post-details`;
@@ -744,7 +766,7 @@ async function runPostDetailsCommand(action, input, client) {
744
766
  const data = await client.request({ path });
745
767
  const details = getResponseValue(data, 'post_details');
746
768
  return details === null
747
- ? { ok: true, message: 'This post has no post details. They are generated for drafts created after the feature launched.', data }
769
+ ? { ok: true, message: `This post has no post details. They are generated for drafts created after the feature launched.${postTrackingMessage(data)}`, data }
748
770
  : { ok: true, message: postSeoMessage(data), data };
749
771
  }
750
772
  if (action === 'set') {
@@ -768,8 +790,21 @@ async function runPostDetailsCommand(action, input, client) {
768
790
  else if (clearLiveUrl) {
769
791
  body.published_url = null;
770
792
  }
793
+ // The search a post written without a target search is tracked with. --clear-track-search has CoAuthor pick again at the next check.
794
+ const trackSearch = getString(input.values, 'track-search')?.trim();
795
+ const clearTrackSearch = getBoolean(input.values, 'clear-track-search');
796
+ if (clearTrackSearch && trackSearch !== undefined)
797
+ throw new Error('Pass either --track-search <search> or --clear-track-search, not both.');
798
+ if (trackSearch !== undefined) {
799
+ if (trackSearch.length < 1 || trackSearch.length > 120)
800
+ throw new Error('--track-search needs a search of 1 to 120 characters.');
801
+ body.tracking_keyword = trackSearch;
802
+ }
803
+ else if (clearTrackSearch) {
804
+ body.tracking_keyword = null;
805
+ }
771
806
  if (Object.keys(body).length === 0) {
772
- throw new Error('Usage: coauthor post-details set <projectId> [--seo-title "..."] [--description "..."] [--slug "..."] [--excerpt "..."] [--live-url <url> | --clear-live-url]');
807
+ throw new Error('Usage: coauthor post-details set <projectId> [--seo-title "..."] [--description "..."] [--slug "..."] [--excerpt "..."] [--live-url <url> | --clear-live-url] [--track-search <search> | --clear-track-search]');
773
808
  }
774
809
  return { ok: true, data: await client.request({ method: 'PATCH', path, body }) };
775
810
  }
@@ -1964,7 +1999,7 @@ function widgetStateLabel(widget) {
1964
1999
  function widgetSpec(widget) {
1965
2000
  return widget.spec && typeof widget.spec === 'object' && !Array.isArray(widget.spec) ? widget.spec : {};
1966
2001
  }
1967
- function describeWidget(widget) {
2002
+ function describeWidget(widget, options = {}) {
1968
2003
  const spec = widgetSpec(widget);
1969
2004
  const lines = [
1970
2005
  `${String(widget.id)} ${String(spec.title ?? '(untitled)')} [${widgetStateLabel(widget)}]`,
@@ -1975,6 +2010,9 @@ function describeWidget(widget) {
1975
2010
  ];
1976
2011
  if (typeof widget.embed_url === 'string')
1977
2012
  lines.push(` embed: ${widget.embed_url}`);
2013
+ if (options.embedCode && typeof widget.embed_code === 'string' && widget.embed_code) {
2014
+ lines.push(' embed code:', ...widget.embed_code.split('\n').map((line) => ` ${line}`));
2015
+ }
1978
2016
  if (widget.fact_check_warning)
1979
2017
  lines.push(` fact check: ${String(widget.fact_check_warning)}`);
1980
2018
  const error = widgetError(widget);
@@ -1989,7 +2027,7 @@ function widgetsListMessage(data) {
1989
2027
  }
1990
2028
  const model = getResponseValue(data, 'model');
1991
2029
  const placeholders = widgets.filter((widget) => widget.current_version == null && widget.build_state === 'idle').length;
1992
- const lines = widgets.map(describeWidget);
2030
+ const lines = widgets.map((widget) => describeWidget(widget, { embedCode: true }));
1993
2031
  if (model) {
1994
2032
  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
2033
  }
@@ -2046,7 +2084,7 @@ function widgetsWaitResult(projectId, result, resumeCommand, doneWord) {
2046
2084
  }
2047
2085
  return {
2048
2086
  ok: true,
2049
- message: `${widgets.length} interactive${widgets.length === 1 ? '' : 's'} ${doneWord}.\n${widgets.map(describeWidget).join('\n')}`,
2087
+ message: `${widgets.length} interactive${widgets.length === 1 ? '' : 's'} ${doneWord}.\n${widgets.map((widget) => describeWidget(widget)).join('\n')}`,
2050
2088
  messageIncludesData: true,
2051
2089
  data,
2052
2090
  };
@@ -2088,7 +2126,7 @@ async function runWidgetsCommand(action, input, client) {
2088
2126
  const waited = await waitForWidgets(client, projectId, [id], [widget]);
2089
2127
  return widgetsWaitResult(projectId, waited, `coauthor widgets status ${projectId} ${id} --wait`, 'ready');
2090
2128
  }
2091
- return { ok: true, message: widget ? describeWidget(widget) : undefined, messageIncludesData: Boolean(widget), data };
2129
+ return { ok: true, message: widget ? describeWidget(widget, { embedCode: true }) : undefined, messageIncludesData: Boolean(widget), data };
2092
2130
  }
2093
2131
  if (action === 'build') {
2094
2132
  const id = needWidget('build');
@@ -2371,6 +2409,19 @@ function resultChange(row, depth) {
2371
2409
  default: return 'steady';
2372
2410
  }
2373
2411
  }
2412
+ // A post written without a target search carries `tracking: {keyword, source}`: who picked its search, and what the next check will use.
2413
+ function resultTrackingNote(row) {
2414
+ if (row.tracking === null || row.tracking === undefined)
2415
+ return '';
2416
+ const tracking = planRecord(row.tracking);
2417
+ const tracked = planString(tracking, 'keyword') ?? '';
2418
+ const reading = planString(row, 'keyword') ?? '';
2419
+ if (tracked === '')
2420
+ return ' · next check picks a new search';
2421
+ const picked = tracked === reading && (tracking.source === 'ranked' || tracking.source === 'suggested') ? ' (picked by CoAuthor)' : '';
2422
+ const next = tracked === reading ? '' : ` · next check uses "${tracked}"`;
2423
+ return `${picked}${next}`;
2424
+ }
2374
2425
  function seoPlanCheckReason(check) {
2375
2426
  if (!check || check.status === 'queued' || check.status === 'running')
2376
2427
  return null;
@@ -2422,7 +2473,7 @@ function seoPlanResultsMessage(data) {
2422
2473
  ].filter(Boolean).join(' · '), '');
2423
2474
  for (const row of rows) {
2424
2475
  const position = typeof row.position === 'number' ? `#${row.position}` : '--';
2425
- lines.push(` ${position.padEnd(4)} ${resultChange(row, depth).padEnd(16)} ${planString(row, 'title') ?? 'Untitled'} [search: ${planString(row, 'keyword') ?? ''}]`);
2476
+ lines.push(` ${position.padEnd(4)} ${resultChange(row, depth).padEnd(16)} ${planString(row, 'title') ?? 'Untitled'} [search: ${planString(row, 'keyword') ?? ''}${resultTrackingNote(row)}]`);
2426
2477
  lines.push(` ${planString(row, 'tracked_url') ?? ''} (project ${planString(row, 'project_id') ?? ''})`);
2427
2478
  const otherPage = planString(row, 'ranking_url');
2428
2479
  if (row.movement === 'not_found' && otherPage)
@@ -2430,13 +2481,15 @@ function seoPlanResultsMessage(data) {
2430
2481
  }
2431
2482
  }
2432
2483
  else {
2433
- lines.push('No posts are tracked yet. A post is tracked once it has a target search and a live address.');
2484
+ lines.push('No posts are tracked yet. A post is tracked once it has a live address and a search to track.');
2434
2485
  }
2435
2486
  const missing = Array.isArray(view.missing_urls) ? view.missing_urls.map(planRecord) : [];
2436
2487
  if (missing.length > 0) {
2437
2488
  lines.push('', `${missing.length} ${missing.length === 1 ? 'post has' : 'posts have'} no live address yet, so ${missing.length === 1 ? 'it is' : 'they are'} not tracked. Set one with \`coauthor post-details set <project-id> --live-url <url>\`:`);
2438
- for (const row of missing.slice(0, RESULT_ROWS_SHOWN))
2439
- lines.push(` ${planString(row, 'project_id') ?? ''} ${planString(row, 'title') ?? 'Untitled'} [search: ${planString(row, 'keyword') ?? ''}]`);
2489
+ for (const row of missing.slice(0, RESULT_ROWS_SHOWN)) {
2490
+ const search = row.needs_search === true ? 'no target search yet' : `search: ${planString(row, 'keyword') ?? ''}`;
2491
+ lines.push(` ${planString(row, 'project_id') ?? ''} ${planString(row, 'title') ?? 'Untitled'} [${search}]`);
2492
+ }
2440
2493
  if (missing.length > RESULT_ROWS_SHOWN)
2441
2494
  lines.push(` and ${missing.length - RESULT_ROWS_SHOWN} more (see --json data.missing_urls).`);
2442
2495
  }
@@ -3450,7 +3503,7 @@ export function helpResult(command = []) {
3450
3503
  ' research run|status|structured',
3451
3504
  ' draft generate|status|get|save|revise',
3452
3505
  ' draft revision show|apply|discard',
3453
- ' draft get supports --format json|markdown|html|text (--frontmatter adds post details to markdown)',
3506
+ ' draft get supports --format json|markdown|html|text (--frontmatter adds post details to markdown; --widgets embed exports interactives as live iframes)',
3454
3507
  ' post-details show|set',
3455
3508
  ' seo markets [--country <country>] [--language <language>]',
3456
3509
  ' search-brief show|set-keyword|set-mode',
@@ -3541,10 +3594,11 @@ function commandHelp(command) {
3541
3594
  '--widget-model (interactives beta) picks the model that builds interactives: claude-opus-5-5 (default) or claude-sonnet-5-5.',
3542
3595
  ].join('\n'),
3543
3596
  'draft get': [
3544
- 'Usage: coauthor draft get <project-id> [--format json|markdown|html|text] [--frontmatter] [--json]',
3597
+ 'Usage: coauthor draft get <project-id> [--format json|markdown|html|text] [--frontmatter] [--widgets image|embed] [--json]',
3545
3598
  '',
3546
3599
  'Retrieves a saved generated draft. Chat responses are available through coauthor chat show.',
3547
3600
  '--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.',
3601
+ '--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
3602
  ].join('\n'),
3549
3603
  'draft save': [
3550
3604
  'Usage: coauthor draft save <project-id> --data @payload.json [--force] [--json]',
@@ -3591,7 +3645,7 @@ function commandHelp(command) {
3591
3645
  'dismiss hides an idea from the plan; --undo brings it back.',
3592
3646
  'done marks an idea as done (for example after you improved the page); --undo clears the mark. A done idea stays in the plan and stays done when the plan is updated.',
3593
3647
  'monthly-check on|off switches the plan\'s monthly check (free). Once a month it re-checks where each published post ranks on Google, refreshes the plan\'s ranking data and chances, and uses credits (the first check is free). show prints its state: enabled, next_check_at and about how many credits a month. It is absent while monthly checks are not switched on for the account. Turning it on picks the next date at least 25 days after the last check.',
3594
- 'results prints where each tracked post ranked at the last monthly check (position, change since the check before, live address; a post no check has read yet reads "checked next time"; when another page of the site ranks instead it prints that page), the posts that have a target search but no live address yet (except ones marked as still being edited), and why the last check did less than a full job. --json returns data.results, data.missing_urls, data.last_check and data.monthly_check. Without monthly checks switched on for the account there are no results. A post is tracked once it has a target search and a live address: set one with `coauthor post-details set <project-id> --live-url <url>`.',
3648
+ 'results prints where each tracked post ranked at the last monthly check (position, change since the check before, live address; a post no check has read yet reads "checked next time"; when another page of the site ranks instead it prints that page), the posts with no live address yet (except ones marked as still being edited; a post written without a target search reads "no target search yet" and gets one picked at the next check), and why the last check did less than a full job. --json returns data.results, data.missing_urls, data.last_check and data.monthly_check. Without monthly checks switched on for the account there are no results. A post is tracked once it has a live address and a search: set the address with `coauthor post-details set <project-id> --live-url <url>`. Posts written without a target search are tracked automatically (CoAuthor finds the live page and picks a search; results shows "(picked by CoAuthor)"); change the search with `post-details set <project-id> --track-search "<search>"`, and --json adds tracking to each row and needs_search to each missing post.',
3595
3649
  '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.',
3596
3650
  ].join('\n'),
3597
3651
  integrations: [
@@ -3724,12 +3778,13 @@ function commandHelp(command) {
3724
3778
  ].join('\n'),
3725
3779
  'post-details': [
3726
3780
  'Usage: coauthor post-details show <project-id> [--json]',
3727
- ' coauthor post-details set <project-id> [--seo-title "..."] [--description "..."] [--slug "..."] [--excerpt "..."] [--live-url <url> | --clear-live-url] [--json]',
3781
+ ' coauthor post-details set <project-id> [--seo-title "..."] [--description "..."] [--slug "..."] [--excerpt "..."] [--live-url <url> | --clear-live-url] [--track-search <search> | --clear-track-search] [--json]',
3728
3782
  '',
3729
3783
  'Post details are the SEO title, meta description, slug and excerpt CoAuthor writes after a draft. Exports use them as defaults.',
3730
3784
  'set changes only the fields you pass; an empty value clears a field. Edited fields are kept when the draft is regenerated.',
3731
3785
  'The live URL is where the post is published. show returns published_url and published_url_source (export, manual, auto_detect or cleared). --live-url sets it by hand (an http or https address) and wins over later exports; --clear-live-url removes it, and CoAuthor then does not look for it again.',
3732
- 'Posts drafted before post details launched have none (show returns post_details: null; set returns post_details_unavailable).',
3786
+ 'Posts written without a target search (mostly drafted before SEO mode) are tracked by the monthly check anyway: CoAuthor finds the live page and picks a search. show returns tracking (published_url, published_url_source, tracking_keyword, tracking_keyword_source: ranked or suggested = CoAuthor picked it, manual = you did). --track-search sets the search to track (1 to 120 characters; wins over later picks); --clear-track-search has CoAuthor pick again at the next check. To stop tracking such a post, use --clear-live-url. --track-search is for posts without a target search (a post with one answers post_has_target_search).',
3787
+ 'Posts drafted before post details launched have no SEO fields (show returns post_details: null; setting SEO fields returns post_details_unavailable), but --live-url, --clear-live-url and --track-search still work for them.',
3733
3788
  'SEO posts also return seo: the target keyword, market, SEO research credits and a checklist computed from the current draft (pass, warn, fail or skip per check).',
3734
3789
  ].join('\n'),
3735
3790
  share: [
package/dist/parser.js CHANGED
@@ -56,10 +56,13 @@ const OPTIONS = {
56
56
  'seo-title': { type: 'string' },
57
57
  'live-url': { type: 'string' },
58
58
  'clear-live-url': { type: 'boolean', default: false },
59
+ 'track-search': { type: 'string' },
60
+ 'clear-track-search': { type: 'boolean', default: false },
59
61
  keyword: { type: 'string' },
60
62
  seo: { type: 'string' },
61
63
  'confirm-reset': { type: 'boolean', default: false },
62
64
  frontmatter: { type: 'boolean', default: false },
65
+ widgets: { type: 'string' },
63
66
  country: { type: 'string' },
64
67
  language: { type: 'string' },
65
68
  status: { type: 'string' },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.67",
3
+ "version": "0.0.69",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -71,7 +71,7 @@ When the user wants to know what to write about for a business site, or asks for
71
71
  - `coauthor seo-plan dismiss <item-id> [--undo] --json` hides an idea the user rules out.
72
72
  - `coauthor seo-plan done <item-id> [--undo] --json` marks an idea done (usually an `improve` page the user has updated). Items carry `done_at`; a done idea stays done when the plan is updated.
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
- - `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>`.
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 with 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>`. Posts written without a target search are tracked automatically (CoAuthor finds the live page and picks a search, shown in `tracking`); set or change the search with `post-details set <id> --track-search "<search>"`.
75
75
 
76
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
 
@@ -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
  ```
@@ -22,12 +23,16 @@ coauthor post-details show <id> --json # data.post_details (null for drafts ma
22
23
  coauthor post-details set <id> --seo-title "..." --description "..." --slug "..." --excerpt "..." --json
23
24
  coauthor post-details set <id> --live-url https://example.com/my-post/ --json # where the post is live
24
25
  coauthor post-details set <id> --clear-live-url --json
26
+ coauthor post-details set <id> --track-search "welcome email examples" --json # posts written without a target search: the search to track
27
+ coauthor post-details set <id> --clear-track-search --json # CoAuthor picks the search again at the next check
25
28
  ```
26
29
 
27
- `set` changes only the fields you pass; an empty value clears one. Fields the user or you edited are kept when the draft is regenerated. Keep the SEO title near 60 characters and the description near 155. `post_details_unavailable` means the draft predates post details.
30
+ `set` changes only the fields you pass; an empty value clears one. Fields the user or you edited are kept when the draft is regenerated. Keep the SEO title near 60 characters and the description near 155. `post_details_unavailable` means the draft predates post details and you tried to change an SEO field.
28
31
 
29
32
  The live URL is where the post is published. `post_details.published_url` holds it (null until it is known) and `published_url_source` says where it came from: `export` (an export reported the post live, or a WordPress post the user published afterwards), `manual` (set with `--live-url` or in the app), `auto_detect` (CoAuthor found the page on the user's site) or `cleared` (removed on purpose). Set it when the user tells you where a post went live. A URL set by hand wins over later exports, and `--clear-live-url` removes it so CoAuthor does not look for it again. It must be an `http` or `https` address, and it is not one of the four SEO fields, so it never counts as an edited field.
30
33
 
34
+ Posts written without a target search (mostly drafted before SEO mode, many with no post details at all) are still tracked by the monthly check: CoAuthor finds the live page and picks a search to track. `post-details show` returns `data.tracking`: `{published_url, published_url_source, tracking_keyword, tracking_keyword_source}`, the live address and search used for tracking (post details first, then CoAuthor's own record), where `tracking_keyword_source` is `ranked` or `suggested` (CoAuthor picked it), `manual` (set with `--track-search`) or `null`. `--live-url` and `--clear-live-url` work for these posts even without post details. `--track-search` sets the search (1 to 120 characters, kept over later picks; changing the address makes CoAuthor pick again unless you set the search by hand) and `--clear-track-search` asks for a new pick at the next check. `--clear-live-url` stops tracking the post. A post that has a target search of its own answers `post_has_target_search`: its tracked search is that one.
35
+
31
36
  For SEO posts on a profile with a website, `post_details.incoming_link_suggestions` lists existing pages on the user's site that could link to the new post: `{status, suggestions: [{url, title, anchor, sentence}]}`. `status` is `ready`, `none`, or `index_not_ready` (the site was still being indexed when the draft was written; links appear on the next post). It is read-only. After the post is published, offer the user the sentences to add on those pages, linking the anchor text to the new post's URL. It is `null` for other posts.
32
37
 
33
38
  For SEO posts, `post-details show` also returns `seo`: the target `keyword`, its `market`, `seo_research_credits`, and a `checks` list computed from the current draft and title. Each check has an `id`, a `status` (`pass`, `warn`, `fail`, or `skip` when there is nothing to measure) and a plain `detail`. The ids are `keyword_in_title`, `keyword_in_intro` (first 100 words), `secondary_in_h2`, `table_stakes`, `angle_section`, `questions_answered`, `internal_link`, `outbound_sources` and `length`. A `fail` on the title is worth fixing before publishing: edit it with `project rename`. A `warn` on `keyword_in_intro` is fine when the keyword wouldn't read naturally in the opening, so don't force it in. `secondary_in_h2` and `questions_answered` are optional: they report `pass` or `skip`, never `warn`. `seo` is `null` for other posts.
@@ -80,18 +80,20 @@ Errors: `plan_stale` (the profile's website or market changed; run `generate` to
80
80
 
81
81
  ## Monthly check
82
82
 
83
- Once a month CoAuthor looks up where each published post (one with a target search and a live URL) ranks on Google, refreshes the plan's ranking data and the chance of its top ideas, and records the result. It uses credits, about 30 a month, and the account's first check is free. It is on by default for a plan.
83
+ Once a month CoAuthor looks up where each published post (one with a search to track and a live URL) ranks on Google, refreshes the plan's ranking data and the chance of its top ideas, and records the result. It uses credits, about 30 a month, and the account's first check is free. It is on by default for a plan.
84
84
 
85
85
  `coauthor seo-plan monthly-check on|off [--profile <id>] --json` switches it for that profile's plan and returns `data.enabled` and `data.next_check_at` (`null` when off). Turning it on picks the next date at least 25 days after the last check, so switching does not buy an early check. `show` returns `data.monthly_check` with `enabled`, `next_check_at`, `last_check_at`, `estimate_credits` and `first_check_free`; it is `null` while monthly checks are not switched on for the account, and then there is nothing to switch. Do not turn it off on your own judgment: it is what keeps the plan's rankings and chances current. Errors: `not_enabled`, `profile_not_found`, `plan_not_found` (make the plan first), `invalid_input`.
86
86
 
87
87
  Posts are only tracked once their live URL is known: set it with `coauthor post-details set <id> --live-url <url>` (see `references/publishing-and-export.md`).
88
88
 
89
+ Posts written without a target search (mostly drafted before SEO mode) are tracked automatically: CoAuthor finds the live page on the site and picks a search for it, and tracking starts at once. The pick is shown in the results so the user can change it, and it costs about one credit more per month for each extra tracked search. Set or change the search with `coauthor post-details set <id> --track-search "<search>"` (`--clear-track-search` has CoAuthor pick again at the next check), and stop tracking a post with `--clear-live-url`. A post whose live page is not found yet shows under `data.missing_urls` with `needs_search: true`; give it an address (and optionally a search) the same way.
90
+
89
91
  ### Results
90
92
 
91
93
  `coauthor seo-plan results [--profile <id>] --json` shows what the last monthly check found; the human output is a short list. The same fields come back from `show` (`data.results`, `data.missing_urls`, `data.last_check`, `data.monthly_check`).
92
94
 
93
- - `data.results` has one row per tracked post (a live address and a target search), best news first (moved up, then page one by position, then the rest, then posts no check has read yet): `project_id`, `title`, `keyword`, `tracked_url`, `position`, `previous_position`, `movement`, `ranking_url` and `checked_at`. `position` is Google's organic position; page one means 10 or better. It is `null` when the post's address is not within the top results the check looked at (`data.last_check.depth`, 30 by default), and `movement` is then `not_found`; if `ranking_url` is set, another page of the same site ranks for that search instead, which is worth telling the user. `movement` is `up` or `down` only for a move of 3 places or more, or a move onto or off page one; `same` is steady; `new` means the first reading of that search and address, so there is nothing to compare with yet; `pending` means the post went live after the last check and has no reading yet (`position` and `checked_at` are `null`; the next check reads it).
94
- - `data.missing_urls` lists posts that have a target search but no live address (`project_id`, `title`, `keyword`, `publication_status`: `published`, `submitted`, or `null` when nobody marked the post); only posts explicitly marked as still being edited are left out. Most posts are unmarked, so a `null` post may not be live yet: ask the user before setting an address. They are not tracked until you set one with `coauthor post-details set <project-id> --live-url <url>`; the next check picks it up.
95
+ - `data.results` has one row per tracked post (a live address and a search), best news first (moved up, then page one by position, then the rest, then posts no check has read yet): `project_id`, `title`, `keyword`, `tracked_url`, `position`, `previous_position`, `movement`, `ranking_url`, `checked_at` and `tracking`. `tracking` is `null` for a post written for a target search; for a post written without one it is `{keyword, source}`: the search tracked now (`keyword` is `""` while the next check will pick one; it can differ from the row's `keyword`, which is what the last reading used) and who chose it (`source`: `ranked` or `suggested` = CoAuthor picked it, `manual` = the user did, `null` = not picked yet). `position` is Google's organic position; page one means 10 or better. It is `null` when the post's address is not within the top results the check looked at (`data.last_check.depth`, 30 by default), and `movement` is then `not_found`; if `ranking_url` is set, another page of the same site ranks for that search instead, which is worth telling the user. `movement` is `up` or `down` only for a move of 3 places or more, or a move onto or off page one; `same` is steady; `new` means the first reading of that search and address, so there is nothing to compare with yet; `pending` means the post went live after the last check and has no reading yet (`position` and `checked_at` are `null`; the next check reads it).
96
+ - `data.missing_urls` lists posts that have no live address (`project_id`, `title`, `keyword`, `needs_search`, `publication_status`: `needs_search` is `true`, with `keyword` `""`, for a post written without a target search that has no search to track yet, so the next check picks one; `publication_status`: `published`, `submitted`, or `null` when nobody marked the post); only posts explicitly marked as still being edited are left out. Most posts are unmarked, so a `null` post may not be live yet: ask the user before setting an address. They are not tracked until you set one with `coauthor post-details set <project-id> --live-url <url>` (add `--track-search "<search>"` to choose the search for a post without a target search); the next check picks it up.
95
97
  - `data.last_check` is `{status, finished_at, partial, partial_reason, plan_refresh_skipped, error_code, credits_charged, free, depth}`. `partial` means the check stopped early (for example credits ran out); `plan_refresh_skipped` (`stale` or `failed`) means the plan's own chances were not refreshed because the plan needs updating, so run `coauthor seo-plan generate`. `status` `skipped` with `error_code` `insufficient_credits` means the account had too few credits and nothing was spent.
96
98
  - Everything is empty or `null` while monthly checks are not switched on for the account, and before the first check has run.
97
99
 
@@ -49,8 +49,9 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
49
49
  | `invalid_keyword` | The keyword is empty or longer than 200 characters. | Pass a plain search phrase. |
50
50
  | `invalid_seo_mode` | `--seo` or `set-mode` got something other than `optimize`, `my-way` or `off`, or `--seo off` was combined with `--keyword`. | Pass one of the three modes; drop `--keyword` with `off`. |
51
51
  | `no_search_target` | `search-brief set-mode optimize` or `my-way` on a project with no target keyword. | Set one with `search-brief set-keyword`, or let the outline pick one. |
52
- | `post_details_unavailable` | The draft was made before post details launched, so it has none to edit. | Pass the slug and description to the export directly. |
53
- | `invalid_post_details` | `post-details set` got something other than text for a field, or a live URL that is not an `http` or `https` address. | Pass plain text with `--seo-title`, `--description`, `--slug`, or `--excerpt`, and a full address with `--live-url`. |
52
+ | `post_details_unavailable` | The draft was made before post details launched, so it has no SEO fields to edit (`--live-url` and `--track-search` still work). | Pass the slug and description to the export directly. |
53
+ | `invalid_post_details` | `post-details set` got something other than text for a field, a live URL that is not an `http` or `https` address, or a `--track-search` that is empty or over 120 characters. | Pass plain text with `--seo-title`, `--description`, `--slug`, or `--excerpt`, a full address with `--live-url`, and a search of 1 to 120 characters with `--track-search`. |
54
+ | `post_has_target_search` | `post-details set --track-search` on a post that was written for a target search. | Nothing to do: that post is tracked with its target search. Change it with `search-brief set-keyword` if the user wants another. |
54
55
  | `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
56
  | `uploaded_image` | `image generate` on an image the user replaced with their own file. | Use `image edit --edit-prompt "..."`, or `image replace` again. |
56
57
  | `not_a_panel` | `image replace` on an article image. | Only slideshow and video panels can be replaced from the CLI. |
@@ -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 dismiss <item-id> [--undo] --json` hides an idea the user rules out.
74
74
  - `coauthor seo-plan done <item-id> [--undo] --json` marks an idea done (usually an `improve` page the user has updated). Items carry `done_at`; a done idea stays done when the plan is updated.
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
- - `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>`.
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 with 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>`. Posts written without a target search are tracked automatically (CoAuthor finds the live page and picks a search, shown in `tracking`); set or change the search with `post-details set <id> --track-search "<search>"`.
77
77
 
78
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
 
@@ -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
  ```
@@ -463,12 +466,16 @@ coauthor post-details show <id> --json # data.post_details (null for drafts ma
463
466
  coauthor post-details set <id> --seo-title "..." --description "..." --slug "..." --excerpt "..." --json
464
467
  coauthor post-details set <id> --live-url https://example.com/my-post/ --json # where the post is live
465
468
  coauthor post-details set <id> --clear-live-url --json
469
+ coauthor post-details set <id> --track-search "welcome email examples" --json # posts written without a target search: the search to track
470
+ coauthor post-details set <id> --clear-track-search --json # CoAuthor picks the search again at the next check
466
471
  ```
467
472
 
468
- `set` changes only the fields you pass; an empty value clears one. Fields the user or you edited are kept when the draft is regenerated. Keep the SEO title near 60 characters and the description near 155. `post_details_unavailable` means the draft predates post details.
473
+ `set` changes only the fields you pass; an empty value clears one. Fields the user or you edited are kept when the draft is regenerated. Keep the SEO title near 60 characters and the description near 155. `post_details_unavailable` means the draft predates post details and you tried to change an SEO field.
469
474
 
470
475
  The live URL is where the post is published. `post_details.published_url` holds it (null until it is known) and `published_url_source` says where it came from: `export` (an export reported the post live, or a WordPress post the user published afterwards), `manual` (set with `--live-url` or in the app), `auto_detect` (CoAuthor found the page on the user's site) or `cleared` (removed on purpose). Set it when the user tells you where a post went live. A URL set by hand wins over later exports, and `--clear-live-url` removes it so CoAuthor does not look for it again. It must be an `http` or `https` address, and it is not one of the four SEO fields, so it never counts as an edited field.
471
476
 
477
+ Posts written without a target search (mostly drafted before SEO mode, many with no post details at all) are still tracked by the monthly check: CoAuthor finds the live page and picks a search to track. `post-details show` returns `data.tracking`: `{published_url, published_url_source, tracking_keyword, tracking_keyword_source}`, the live address and search used for tracking (post details first, then CoAuthor's own record), where `tracking_keyword_source` is `ranked` or `suggested` (CoAuthor picked it), `manual` (set with `--track-search`) or `null`. `--live-url` and `--clear-live-url` work for these posts even without post details. `--track-search` sets the search (1 to 120 characters, kept over later picks; changing the address makes CoAuthor pick again unless you set the search by hand) and `--clear-track-search` asks for a new pick at the next check. `--clear-live-url` stops tracking the post. A post that has a target search of its own answers `post_has_target_search`: its tracked search is that one.
478
+
472
479
  For SEO posts on a profile with a website, `post_details.incoming_link_suggestions` lists existing pages on the user's site that could link to the new post: `{status, suggestions: [{url, title, anchor, sentence}]}`. `status` is `ready`, `none`, or `index_not_ready` (the site was still being indexed when the draft was written; links appear on the next post). It is read-only. After the post is published, offer the user the sentences to add on those pages, linking the anchor text to the new post's URL. It is `null` for other posts.
473
480
 
474
481
  For SEO posts, `post-details show` also returns `seo`: the target `keyword`, its `market`, `seo_research_credits`, and a `checks` list computed from the current draft and title. Each check has an `id`, a `status` (`pass`, `warn`, `fail`, or `skip` when there is nothing to measure) and a plain `detail`. The ids are `keyword_in_title`, `keyword_in_intro` (first 100 words), `secondary_in_h2`, `table_stakes`, `angle_section`, `questions_answered`, `internal_link`, `outbound_sources` and `length`. A `fail` on the title is worth fixing before publishing: edit it with `project rename`. A `warn` on `keyword_in_intro` is fine when the keyword wouldn't read naturally in the opening, so don't force it in. `secondary_in_h2` and `questions_answered` are optional: they report `pass` or `skip`, never `warn`. `seo` is `null` for other posts.
@@ -667,18 +674,20 @@ Errors: `plan_stale` (the profile's website or market changed; run `generate` to
667
674
 
668
675
  ### Monthly check
669
676
 
670
- Once a month CoAuthor looks up where each published post (one with a target search and a live URL) ranks on Google, refreshes the plan's ranking data and the chance of its top ideas, and records the result. It uses credits, about 30 a month, and the account's first check is free. It is on by default for a plan.
677
+ Once a month CoAuthor looks up where each published post (one with a search to track and a live URL) ranks on Google, refreshes the plan's ranking data and the chance of its top ideas, and records the result. It uses credits, about 30 a month, and the account's first check is free. It is on by default for a plan.
671
678
 
672
679
  `coauthor seo-plan monthly-check on|off [--profile <id>] --json` switches it for that profile's plan and returns `data.enabled` and `data.next_check_at` (`null` when off). Turning it on picks the next date at least 25 days after the last check, so switching does not buy an early check. `show` returns `data.monthly_check` with `enabled`, `next_check_at`, `last_check_at`, `estimate_credits` and `first_check_free`; it is `null` while monthly checks are not switched on for the account, and then there is nothing to switch. Do not turn it off on your own judgment: it is what keeps the plan's rankings and chances current. Errors: `not_enabled`, `profile_not_found`, `plan_not_found` (make the plan first), `invalid_input`.
673
680
 
674
681
  Posts are only tracked once their live URL is known: set it with `coauthor post-details set <id> --live-url <url>` (see `references/publishing-and-export.md`).
675
682
 
683
+ Posts written without a target search (mostly drafted before SEO mode) are tracked automatically: CoAuthor finds the live page on the site and picks a search for it, and tracking starts at once. The pick is shown in the results so the user can change it, and it costs about one credit more per month for each extra tracked search. Set or change the search with `coauthor post-details set <id> --track-search "<search>"` (`--clear-track-search` has CoAuthor pick again at the next check), and stop tracking a post with `--clear-live-url`. A post whose live page is not found yet shows under `data.missing_urls` with `needs_search: true`; give it an address (and optionally a search) the same way.
684
+
676
685
  #### Results
677
686
 
678
687
  `coauthor seo-plan results [--profile <id>] --json` shows what the last monthly check found; the human output is a short list. The same fields come back from `show` (`data.results`, `data.missing_urls`, `data.last_check`, `data.monthly_check`).
679
688
 
680
- - `data.results` has one row per tracked post (a live address and a target search), best news first (moved up, then page one by position, then the rest, then posts no check has read yet): `project_id`, `title`, `keyword`, `tracked_url`, `position`, `previous_position`, `movement`, `ranking_url` and `checked_at`. `position` is Google's organic position; page one means 10 or better. It is `null` when the post's address is not within the top results the check looked at (`data.last_check.depth`, 30 by default), and `movement` is then `not_found`; if `ranking_url` is set, another page of the same site ranks for that search instead, which is worth telling the user. `movement` is `up` or `down` only for a move of 3 places or more, or a move onto or off page one; `same` is steady; `new` means the first reading of that search and address, so there is nothing to compare with yet; `pending` means the post went live after the last check and has no reading yet (`position` and `checked_at` are `null`; the next check reads it).
681
- - `data.missing_urls` lists posts that have a target search but no live address (`project_id`, `title`, `keyword`, `publication_status`: `published`, `submitted`, or `null` when nobody marked the post); only posts explicitly marked as still being edited are left out. Most posts are unmarked, so a `null` post may not be live yet: ask the user before setting an address. They are not tracked until you set one with `coauthor post-details set <project-id> --live-url <url>`; the next check picks it up.
689
+ - `data.results` has one row per tracked post (a live address and a search), best news first (moved up, then page one by position, then the rest, then posts no check has read yet): `project_id`, `title`, `keyword`, `tracked_url`, `position`, `previous_position`, `movement`, `ranking_url`, `checked_at` and `tracking`. `tracking` is `null` for a post written for a target search; for a post written without one it is `{keyword, source}`: the search tracked now (`keyword` is `""` while the next check will pick one; it can differ from the row's `keyword`, which is what the last reading used) and who chose it (`source`: `ranked` or `suggested` = CoAuthor picked it, `manual` = the user did, `null` = not picked yet). `position` is Google's organic position; page one means 10 or better. It is `null` when the post's address is not within the top results the check looked at (`data.last_check.depth`, 30 by default), and `movement` is then `not_found`; if `ranking_url` is set, another page of the same site ranks for that search instead, which is worth telling the user. `movement` is `up` or `down` only for a move of 3 places or more, or a move onto or off page one; `same` is steady; `new` means the first reading of that search and address, so there is nothing to compare with yet; `pending` means the post went live after the last check and has no reading yet (`position` and `checked_at` are `null`; the next check reads it).
690
+ - `data.missing_urls` lists posts that have no live address (`project_id`, `title`, `keyword`, `needs_search`, `publication_status`: `needs_search` is `true`, with `keyword` `""`, for a post written without a target search that has no search to track yet, so the next check picks one; `publication_status`: `published`, `submitted`, or `null` when nobody marked the post); only posts explicitly marked as still being edited are left out. Most posts are unmarked, so a `null` post may not be live yet: ask the user before setting an address. They are not tracked until you set one with `coauthor post-details set <project-id> --live-url <url>` (add `--track-search "<search>"` to choose the search for a post without a target search); the next check picks it up.
682
691
  - `data.last_check` is `{status, finished_at, partial, partial_reason, plan_refresh_skipped, error_code, credits_charged, free, depth}`. `partial` means the check stopped early (for example credits ran out); `plan_refresh_skipped` (`stale` or `failed`) means the plan's own chances were not refreshed because the plan needs updating, so run `coauthor seo-plan generate`. `status` `skipped` with `error_code` `insufficient_credits` means the account had too few credits and nothing was spent.
683
692
  - Everything is empty or `null` while monthly checks are not switched on for the account, and before the first check has run.
684
693
 
@@ -741,8 +750,9 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
741
750
  | `invalid_keyword` | The keyword is empty or longer than 200 characters. | Pass a plain search phrase. |
742
751
  | `invalid_seo_mode` | `--seo` or `set-mode` got something other than `optimize`, `my-way` or `off`, or `--seo off` was combined with `--keyword`. | Pass one of the three modes; drop `--keyword` with `off`. |
743
752
  | `no_search_target` | `search-brief set-mode optimize` or `my-way` on a project with no target keyword. | Set one with `search-brief set-keyword`, or let the outline pick one. |
744
- | `post_details_unavailable` | The draft was made before post details launched, so it has none to edit. | Pass the slug and description to the export directly. |
745
- | `invalid_post_details` | `post-details set` got something other than text for a field, or a live URL that is not an `http` or `https` address. | Pass plain text with `--seo-title`, `--description`, `--slug`, or `--excerpt`, and a full address with `--live-url`. |
753
+ | `post_details_unavailable` | The draft was made before post details launched, so it has no SEO fields to edit (`--live-url` and `--track-search` still work). | Pass the slug and description to the export directly. |
754
+ | `invalid_post_details` | `post-details set` got something other than text for a field, a live URL that is not an `http` or `https` address, or a `--track-search` that is empty or over 120 characters. | Pass plain text with `--seo-title`, `--description`, `--slug`, or `--excerpt`, a full address with `--live-url`, and a search of 1 to 120 characters with `--track-search`. |
755
+ | `post_has_target_search` | `post-details set --track-search` on a post that was written for a target search. | Nothing to do: that post is tracked with its target search. Change it with `search-brief set-keyword` if the user wants another. |
746
756
  | `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
757
  | `uploaded_image` | `image generate` on an image the user replaced with their own file. | Use `image edit --edit-prompt "..."`, or `image replace` again. |
748
758
  | `not_a_panel` | `image replace` on an article image. | Only slideshow and video panels can be replaced from the CLI. |