@clickminded/coauthor-cli 0.0.84 → 0.0.86

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.
@@ -17,6 +17,11 @@ export declare function openBrowser(url: string, spawnImpl?: typeof spawn, warn?
17
17
  * reported as completed *with items to review*, never as plainly done.
18
18
  */
19
19
  export declare function draftCompletionMessage(base: string, status: JsonValue): string;
20
+ /**
21
+ * "Where AI search mentions you" in `seo-plan show`: mentions per platform, the comparison leader and the top
22
+ * question. Nothing when the plan has no AI search data.
23
+ */
24
+ export declare function seoPlanAiSearchLines(value: unknown): string[];
20
25
  /**
21
26
  * `--cta save,follow,custom:Join the webinar` -> the web app's cta_variants
22
27
  * list (at most 4 endings, at most one custom).
package/dist/commands.js CHANGED
@@ -2494,6 +2494,38 @@ function seoPlanItemLine(item) {
2494
2494
  hint ? ` ${hint}` : null,
2495
2495
  ].filter(Boolean).join('\n');
2496
2496
  }
2497
+ /**
2498
+ * "Where AI search mentions you" in `seo-plan show`: mentions per platform, the comparison leader and the top
2499
+ * question. Nothing when the plan has no AI search data.
2500
+ */
2501
+ export function seoPlanAiSearchLines(value) {
2502
+ if (!value || typeof value !== 'object')
2503
+ return [];
2504
+ const visibility = planRecord(value);
2505
+ const platform = (key, label) => {
2506
+ if (visibility[key] === null || visibility[key] === undefined)
2507
+ return null;
2508
+ const row = planRecord(visibility[key]);
2509
+ const mentions = typeof row.mentions === 'number' ? row.mentions : 0;
2510
+ const cited = typeof row.cited === 'number' ? row.cited : 0;
2511
+ return `${label} ${mentions.toLocaleString('en-US')} ${mentions === 1 ? 'answer' : 'answers'}${mentions > 0 ? ` (${cited.toLocaleString('en-US')} cite you)` : ''}`;
2512
+ };
2513
+ const parts = [platform('google', 'Google AI answers'), platform('chat_gpt', 'ChatGPT')].filter((part) => part !== null);
2514
+ if (parts.length === 0)
2515
+ return [];
2516
+ const lines = [`AI search mentions: ${parts.join('; ')}.${visibility.chat_gpt_available === false ? ' ChatGPT data covers the United States in English only.' : ''}`];
2517
+ const competitors = Array.isArray(visibility.competitors) ? visibility.competitors.map(planRecord) : [];
2518
+ const leader = competitors.find((row) => typeof row.mentions === 'number' && row.mentions > 0);
2519
+ if (leader)
2520
+ lines.push(` Top competitor in Google AI answers: ${planString(leader, 'domain')} (${leader.mentions.toLocaleString('en-US')}).`);
2521
+ const questions = Array.isArray(planRecord(visibility.google).questions) ? planRecord(visibility.google).questions.map(planRecord) : [];
2522
+ const top = questions[0];
2523
+ if (top) {
2524
+ const url = Array.isArray(top.own_urls) && typeof top.own_urls[0] === 'string' ? top.own_urls[0] : null;
2525
+ lines.push(` Top question: "${planString(top, 'question')}"${url ? ` -> ${url}` : ''}.`);
2526
+ }
2527
+ return lines;
2528
+ }
2497
2529
  function seoPlanShowMessage(data, kind) {
2498
2530
  const view = planRecord(data);
2499
2531
  const plan = view.plan === null || view.plan === undefined ? null : planRecord(view.plan);
@@ -2534,6 +2566,9 @@ function seoPlanShowMessage(data, kind) {
2534
2566
  const competitors = planString(plan, 'competitors_line');
2535
2567
  if (competitors)
2536
2568
  lines.push(`Competitors: ${competitors}`);
2569
+ const aiSearch = seoPlanAiSearchLines(plan.ai_visibility);
2570
+ if (aiSearch.length > 0)
2571
+ lines.push(...aiSearch);
2537
2572
  const doNext = Array.isArray(view.do_next) ? view.do_next.map(planRecord) : [];
2538
2573
  if (doNext.length > 0) {
2539
2574
  lines.push('', 'Do next:');
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clickminded/coauthor-cli",
3
- "version": "0.0.84",
3
+ "version": "0.0.86",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "coauthor": "dist/index.js",
@@ -36,7 +36,7 @@ Typical timing: brief and outline under a minute; research and draft 3–10 minu
36
36
  3. **Outline checkpoint.** `coauthor outline generate <id> --json` (this does not approve it; sections are in `data.sections`). Review it as the user's editor: every section serves the core promise, must-includes are covered, the order builds, nothing is generic, repeated, or unsupported. Find problems; a bare approval is the exception. Send all your changes in one request: `coauthor outline revise <id> --feedback "Merge sections 3 and 4. Replace the conclusion with a one-week checklist." --json`. It saves the revision and returns `data.diff` (added, removed, renamed, changed, reordered); check the diff matches what you asked, and revise again (at most twice) if not. `data.not_applied` lists any requested change CoAuthor did not make, each with `request` and `reason`; resend those with clearer wording or tell the user why they were left out. When `data.research_plan.stale` is true (the outline changed after a research plan was made; `sections_without_tasks` lists sections it does not cover), run `coauthor research-plan generate <id> --json` after approving the outline instead of approving the old plan. For exact wording you already have, `coauthor outline save <id> --data @outline.json --json` with the complete `{"sections":[...]}` instead. Then `coauthor outline approve <id> --json` and log it (`coauthor log add <id> --message "Approved the outline after …" --json`). If the user asked to see the outline, show it to them here and wait.
37
37
  4. **Research-plan checkpoint.** `coauthor research-plan generate <id> --json` (tasks in `data.research_tasks`). Check every section has a task, every claim that needs proof points at the right sources (including URLs the user gave you), and deep research is used only where it matters. Fix it with `coauthor research-plan revise <id> --feedback "Add a task for the checklist section. Use https://… as a required source for the limits section." --json` and check `data.diff`, then `coauthor research-plan approve <id> --json` and log it.
38
38
  5. **Research and draft.** `COAUTHOR_CLI_WAIT_TIMEOUT_MS=540000 coauthor workflow run <id> --target draft --wait --json`. It is done when the message says the draft completed (`data.draft_status.project_state` is `draft_generated`); ignore the stale `data.workflow.status`. On `timed_out`: `coauthor workflow resume <id> --target draft --wait --json`.
39
- 6. **Quality pass.** CoAuthor already checks each new draft against the brief and for consistency, and fixes what it can: must-include items, non-negotiables, tables vs their sections, "see the table" references, unsourced "most readers" claims, FAQ answers that defer, and links (cut-short or malformed URLs, dead pages, citations that open a page about something else). Whatever is still open is in `quality_check.unresolved` of `coauthor draft status <id> --json` (and `post-details show`), and the completion message says how many. Fix those first. Then `coauthor draft get <id> --format markdown --json` and read `data.markdown` in full. Check it against the brief's must-include, must-avoid, and non-negotiables. Look for: notes about the research process ("the retrieved sources do not…"), invented "checked <date>" lines, numbered lists that restart at 1, garbled `*`, `_`, or code spans, literal `[ ]` in checklists, the same caveat repeated across sections, claims without a source or cited to a page that doesn't support them, contradictions, and a messy Sources list (generic titles like "Google", duplicate entries). Fix them in step 8.
39
+ 6. **Quality pass.** CoAuthor already checks each new draft against the brief and for consistency, and fixes what it can: must-include items (and every figure they give, plus sentences claiming the post has no data the brief supplies), non-negotiables, tables vs their sections, "see the table" references, unsourced "most readers" claims, FAQ answers that defer, links (cut-short or malformed URLs, dead pages, citations that open a page about something else), and sentences that cite a research source: figures that are not in that source, a report edition that differs from the one cited ("the 2027 report" linked to the 2026 page), and up to 15 rules or figures checked against the source text (contradicted ones are corrected from the source when it can; the rest are reported). Whatever is still open is in `quality_check.unresolved` of `coauthor draft status <id> --json` (and `post-details show`), and the completion message says how many. Fix those first. Then `coauthor draft get <id> --format markdown --json` and read `data.markdown` in full. Check it against the brief's must-include, must-avoid, and non-negotiables. Look for: notes about the research process ("the retrieved sources do not…"), invented "checked <date>" lines, numbered lists that restart at 1, garbled `*`, `_`, or code spans, literal `[ ]` in checklists, the same caveat repeated across sections, claims without a source or cited to a page that doesn't support them, contradictions, and a messy Sources list (generic titles like "Google", duplicate entries). Fix them in step 8.
40
40
  7. **Images.** `coauthor image generate <id> --all --wait --json` generates every planned image and waits for them (one image: `coauthor image generate <id> --placeholder-id <placeholder id> --json`, using the `id` UUID from `image list`). CoAuthor decides how many images a draft gets, sometimes only the featured image; the CLI can't add more, so tell the user if they expected several. Open each image and check it does not state numbers or claims the article does not make, and that its alt text matches what is visible (CoAuthor writes alt text from the finished image; fix it with `image metadata` only when it is wrong). See `references/images-and-social.md`. If the draft has interactive placeholders (beta), show them to the user and get a yes before building: `references/interactive-widgets.md`.
41
41
  8. **Edits.** For prose changes: `coauthor draft revise <id> --instruction "..." --wait --json` (be specific: name the section and give a number, such as "cut the intro to under 60 words"), review each group's `before_markdown` and `after_markdown`, then `coauthor draft revision apply <id> <revision-id> --json` (optionally `--accept` or `--reject` with ids copied from `data.groups[].id`) or `coauthor draft revision discard <id> <revision-id> --json`. For exact text you already have, edit the document JSON and `draft save`. See `references/editing-drafts.md`.
42
42
  9. **Deliver.** Give the user the final markdown (or `--format html`), the decision log (`coauthor log show <id> --json`: what you approved, what you asked CoAuthor to change, what you assumed), and the credits used (`coauthor credits <id> --json`). The user also sees the log in the project's workspace in the web app. With their yes: share link or WordPress export (`references/publishing-and-export.md`). For social posts and an email newsletter, `coauthor repurpose generate <id> --format all --json`, review `data.copy`, and `coauthor repurpose download <id> --out <dir>` (`references/repurposing.md`).
@@ -72,6 +72,16 @@ Other fields to use when you recommend an idea:
72
72
  - `do_next_rank` (1 to 5) marks the plan's own top moves.
73
73
  - Alternatives, comparison and best-of posts place the user's product on merit, as one fairly judged option with its limits, and carry a one-line disclosure ("We make <product>"). Competitor prices and features come from fetched pages and are dated. Do not ask CoAuthor to put the product first, and do not remove the disclosure in edits.
74
74
 
75
+ ### Where AI search mentions the site
76
+
77
+ `data.plan.ai_visibility` says how often stored AI answers mention the site, from DataForSEO's saved answers (no live prompting). It is `null` when the plan has none (plans made before it, or when the lookup did not run). When present:
78
+
79
+ - `google`: Google AI answers (AI Overviews and AI Mode) in the plan's market. `mentions` counts answers that used one of the site's pages, `cited` the ones that link to it as a source, and `questions` lists up to 8 questions answered with its pages (`own_urls`, `cited`).
80
+ - `chat_gpt`: the same for ChatGPT. It is `null` outside the United States in English (`chat_gpt_available: false`): ChatGPT answers are only stored for that market.
81
+ - `competitors`: the plan's competitors with their Google AI `mentions`, most first.
82
+
83
+ A mention is not a citation: most mentions mean the AI read the page while answering. Report both numbers as they are, and do not promise that writing a post will change them. The human output of `show` prints one summary line. The web app shows a "Where AI search mentions you" section.
84
+
75
85
  ## Write this
76
86
 
77
87
  `coauthor seo-plan write <item-id> --json` opens a project for a `post` item and returns `data.project_id`, `data.created` and `data.start_prompt`. The project is already set up from the plan: the keyword, the post format, where the product goes, the related searches, and the posts it should link to. You do not need a brief interview or a keyword step.
@@ -104,4 +104,4 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
104
104
 
105
105
  ## Before retrying anything
106
106
 
107
- Check state first: `coauthor workflow status <id> --json`, `coauthor research status <id> --json`, `coauthor draft status <id> --json`, and for exports `coauthor operation list --json`. A finished draft's `quality_check` (`status`: `passed`, `repaired`, `needs_review`, `skipped` or `failed`, plus `fixed` and `unresolved` items with `kind`, `section_heading` and `detail`; `kind: link_broken` covers links that were cut short, malformed, gone or about something else, which CoAuthor restores from the brief and research, replaces or removes) is the draft check run when it was written; it describes the draft as generated, so it does not update when you edit. Starting a step twice can spend credits twice.
107
+ Check state first: `coauthor workflow status <id> --json`, `coauthor research status <id> --json`, `coauthor draft status <id> --json`, and for exports `coauthor operation list --json`. A finished draft's `quality_check` (`status`: `passed`, `repaired`, `needs_review`, `skipped` or `failed`, plus `fixed` and `unresolved` items with `kind`, `section_heading` and `detail`; `kind: link_broken` covers links that were cut short, malformed, gone or about something else, which CoAuthor restores from the brief and research, replaces or removes; `kind: claim_not_supported_by_source` is a sentence with a number or a rule whose cited source says something else or does not say it (including figures missing from the cited page and a report year that differs from the cited edition), with the sentence and what the source supports in `detail`; `claim_check` gives that part's own `status` and how many sentences it `checked`, and its `failed` means only that part could not run) is the draft check run when it was written; it describes the draft as generated, so it does not update when you edit. Starting a step twice can spend credits twice.
@@ -38,7 +38,7 @@ Typical timing: brief and outline under a minute; research and draft 3–10 minu
38
38
  3. **Outline checkpoint.** `coauthor outline generate <id> --json` (this does not approve it; sections are in `data.sections`). Review it as the user's editor: every section serves the core promise, must-includes are covered, the order builds, nothing is generic, repeated, or unsupported. Find problems; a bare approval is the exception. Send all your changes in one request: `coauthor outline revise <id> --feedback "Merge sections 3 and 4. Replace the conclusion with a one-week checklist." --json`. It saves the revision and returns `data.diff` (added, removed, renamed, changed, reordered); check the diff matches what you asked, and revise again (at most twice) if not. `data.not_applied` lists any requested change CoAuthor did not make, each with `request` and `reason`; resend those with clearer wording or tell the user why they were left out. When `data.research_plan.stale` is true (the outline changed after a research plan was made; `sections_without_tasks` lists sections it does not cover), run `coauthor research-plan generate <id> --json` after approving the outline instead of approving the old plan. For exact wording you already have, `coauthor outline save <id> --data @outline.json --json` with the complete `{"sections":[...]}` instead. Then `coauthor outline approve <id> --json` and log it (`coauthor log add <id> --message "Approved the outline after …" --json`). If the user asked to see the outline, show it to them here and wait.
39
39
  4. **Research-plan checkpoint.** `coauthor research-plan generate <id> --json` (tasks in `data.research_tasks`). Check every section has a task, every claim that needs proof points at the right sources (including URLs the user gave you), and deep research is used only where it matters. Fix it with `coauthor research-plan revise <id> --feedback "Add a task for the checklist section. Use https://… as a required source for the limits section." --json` and check `data.diff`, then `coauthor research-plan approve <id> --json` and log it.
40
40
  5. **Research and draft.** `COAUTHOR_CLI_WAIT_TIMEOUT_MS=540000 coauthor workflow run <id> --target draft --wait --json`. It is done when the message says the draft completed (`data.draft_status.project_state` is `draft_generated`); ignore the stale `data.workflow.status`. On `timed_out`: `coauthor workflow resume <id> --target draft --wait --json`.
41
- 6. **Quality pass.** CoAuthor already checks each new draft against the brief and for consistency, and fixes what it can: must-include items, non-negotiables, tables vs their sections, "see the table" references, unsourced "most readers" claims, FAQ answers that defer, and links (cut-short or malformed URLs, dead pages, citations that open a page about something else). Whatever is still open is in `quality_check.unresolved` of `coauthor draft status <id> --json` (and `post-details show`), and the completion message says how many. Fix those first. Then `coauthor draft get <id> --format markdown --json` and read `data.markdown` in full. Check it against the brief's must-include, must-avoid, and non-negotiables. Look for: notes about the research process ("the retrieved sources do not…"), invented "checked <date>" lines, numbered lists that restart at 1, garbled `*`, `_`, or code spans, literal `[ ]` in checklists, the same caveat repeated across sections, claims without a source or cited to a page that doesn't support them, contradictions, and a messy Sources list (generic titles like "Google", duplicate entries). Fix them in step 8.
41
+ 6. **Quality pass.** CoAuthor already checks each new draft against the brief and for consistency, and fixes what it can: must-include items (and every figure they give, plus sentences claiming the post has no data the brief supplies), non-negotiables, tables vs their sections, "see the table" references, unsourced "most readers" claims, FAQ answers that defer, links (cut-short or malformed URLs, dead pages, citations that open a page about something else), and sentences that cite a research source: figures that are not in that source, a report edition that differs from the one cited ("the 2027 report" linked to the 2026 page), and up to 15 rules or figures checked against the source text (contradicted ones are corrected from the source when it can; the rest are reported). Whatever is still open is in `quality_check.unresolved` of `coauthor draft status <id> --json` (and `post-details show`), and the completion message says how many. Fix those first. Then `coauthor draft get <id> --format markdown --json` and read `data.markdown` in full. Check it against the brief's must-include, must-avoid, and non-negotiables. Look for: notes about the research process ("the retrieved sources do not…"), invented "checked <date>" lines, numbered lists that restart at 1, garbled `*`, `_`, or code spans, literal `[ ]` in checklists, the same caveat repeated across sections, claims without a source or cited to a page that doesn't support them, contradictions, and a messy Sources list (generic titles like "Google", duplicate entries). Fix them in step 8.
42
42
  7. **Images.** `coauthor image generate <id> --all --wait --json` generates every planned image and waits for them (one image: `coauthor image generate <id> --placeholder-id <placeholder id> --json`, using the `id` UUID from `image list`). CoAuthor decides how many images a draft gets, sometimes only the featured image; the CLI can't add more, so tell the user if they expected several. Open each image and check it does not state numbers or claims the article does not make, and that its alt text matches what is visible (CoAuthor writes alt text from the finished image; fix it with `image metadata` only when it is wrong). See `references/images-and-social.md`. If the draft has interactive placeholders (beta), show them to the user and get a yes before building: `references/interactive-widgets.md`.
43
43
  8. **Edits.** For prose changes: `coauthor draft revise <id> --instruction "..." --wait --json` (be specific: name the section and give a number, such as "cut the intro to under 60 words"), review each group's `before_markdown` and `after_markdown`, then `coauthor draft revision apply <id> <revision-id> --json` (optionally `--accept` or `--reject` with ids copied from `data.groups[].id`) or `coauthor draft revision discard <id> <revision-id> --json`. For exact text you already have, edit the document JSON and `draft save`. See `references/editing-drafts.md`.
44
44
  9. **Deliver.** Give the user the final markdown (or `--format html`), the decision log (`coauthor log show <id> --json`: what you approved, what you asked CoAuthor to change, what you assumed), and the credits used (`coauthor credits <id> --json`). The user also sees the log in the project's workspace in the web app. With their yes: share link or WordPress export (`references/publishing-and-export.md`). For social posts and an email newsletter, `coauthor repurpose generate <id> --format all --json`, review `data.copy`, and `coauthor repurpose download <id> --out <dir>` (`references/repurposing.md`).
@@ -677,6 +677,16 @@ Other fields to use when you recommend an idea:
677
677
  - `do_next_rank` (1 to 5) marks the plan's own top moves.
678
678
  - Alternatives, comparison and best-of posts place the user's product on merit, as one fairly judged option with its limits, and carry a one-line disclosure ("We make <product>"). Competitor prices and features come from fetched pages and are dated. Do not ask CoAuthor to put the product first, and do not remove the disclosure in edits.
679
679
 
680
+ #### Where AI search mentions the site
681
+
682
+ `data.plan.ai_visibility` says how often stored AI answers mention the site, from DataForSEO's saved answers (no live prompting). It is `null` when the plan has none (plans made before it, or when the lookup did not run). When present:
683
+
684
+ - `google`: Google AI answers (AI Overviews and AI Mode) in the plan's market. `mentions` counts answers that used one of the site's pages, `cited` the ones that link to it as a source, and `questions` lists up to 8 questions answered with its pages (`own_urls`, `cited`).
685
+ - `chat_gpt`: the same for ChatGPT. It is `null` outside the United States in English (`chat_gpt_available: false`): ChatGPT answers are only stored for that market.
686
+ - `competitors`: the plan's competitors with their Google AI `mentions`, most first.
687
+
688
+ A mention is not a citation: most mentions mean the AI read the page while answering. Report both numbers as they are, and do not promise that writing a post will change them. The human output of `show` prints one summary line. The web app shows a "Where AI search mentions you" section.
689
+
680
690
  ### Write this
681
691
 
682
692
  `coauthor seo-plan write <item-id> --json` opens a project for a `post` item and returns `data.project_id`, `data.created` and `data.start_prompt`. The project is already set up from the plan: the keyword, the post format, where the product goes, the related searches, and the posts it should link to. You do not need a brief interview or a keyword step.
@@ -828,4 +838,4 @@ Every failure prints JSON on stderr with `ok: false`, `error` (a readable messag
828
838
 
829
839
  ### Before retrying anything
830
840
 
831
- Check state first: `coauthor workflow status <id> --json`, `coauthor research status <id> --json`, `coauthor draft status <id> --json`, and for exports `coauthor operation list --json`. A finished draft's `quality_check` (`status`: `passed`, `repaired`, `needs_review`, `skipped` or `failed`, plus `fixed` and `unresolved` items with `kind`, `section_heading` and `detail`; `kind: link_broken` covers links that were cut short, malformed, gone or about something else, which CoAuthor restores from the brief and research, replaces or removes) is the draft check run when it was written; it describes the draft as generated, so it does not update when you edit. Starting a step twice can spend credits twice.
841
+ Check state first: `coauthor workflow status <id> --json`, `coauthor research status <id> --json`, `coauthor draft status <id> --json`, and for exports `coauthor operation list --json`. A finished draft's `quality_check` (`status`: `passed`, `repaired`, `needs_review`, `skipped` or `failed`, plus `fixed` and `unresolved` items with `kind`, `section_heading` and `detail`; `kind: link_broken` covers links that were cut short, malformed, gone or about something else, which CoAuthor restores from the brief and research, replaces or removes; `kind: claim_not_supported_by_source` is a sentence with a number or a rule whose cited source says something else or does not say it (including figures missing from the cited page and a report year that differs from the cited edition), with the sentence and what the source supports in `detail`; `claim_check` gives that part's own `status` and how many sentences it `checked`, and its `failed` means only that part could not run) is the draft check run when it was written; it describes the draft as generated, so it does not update when you edit. Starting a step twice can spend credits twice.