@siteoshq/cli 2.4.0 → 2.5.1

package/README.md

@@ -222,6 +222,7 @@ siteos seo research serp export <run-id> --keyword "website analytics" --format
 siteos seo research plan --input ./research-request.json --json
 siteos seo research run --input ./research-request.json --idempotency-key <retry-key> --json
 siteos seo research wait <run-id> --json
+siteos seo research retry <run-id> --idempotency-key <continuation-key> --json
 siteos seo research export <run-id> --format json --output ./research-report.json --json
 siteos seo gsc status --json
 siteos seo gsc report --dataset queries --filter all --json
@@ -231,9 +232,9 @@ siteos seo gsc export --dataset queries --format csv --output ./gsc-queries.csv
 Run `siteos seo --help` for request JSON, limits, saved inputs, cancellation and GSC settings.
 Research supports keywords, Domain Overview (`domain`), rankings, backlinks, brand and AI visibility without GSC.
 AI Visibility category history uses `--kind ai-rankings`; Prompt checks stays separate under
-`--kind ai-visibility`. Category requests use `kind: ai-visibility` with a `category-aeo-v2`
-category. Reports and exports preserve AEO scores, recommendation roles, first choices, objections,
-model settings and the exact supporting answers. See the SEO skill's AI visibility reference for
+`--kind ai-visibility`. Category requests use `kind: ai-visibility` with a `category-mentions-v3`
+category: ordinary answers, text Mentions and Citations. Historical reports retain AEO scores and
+annotations. Reports and exports include model settings and the exact supporting answers. See the SEO skill's AI visibility reference for
 the versioned request and scoring method; historical v1 reports remain readable without inferred scores.
 Domain Overview collects domain totals, up to 100 ranking keywords, pages and competitors for a market.
 `--kind domain` includes legacy `competitors` history; existing `competitors` inputs keep their original two-part plan.

package/dist/cli.js

@@ -9001,6 +9001,7 @@ var RESEARCH_HELP = `
   siteos seo research show <run-id> [--environment <slug>] [--json]
   siteos seo research plan --input <request.json> [--environment <slug>] [--json]
   siteos seo research run --input <request.json> [--idempotency-key <key>] [--environment <slug>] [--json]
+  siteos seo research retry <run-id> [--idempotency-key <key>] [--environment <slug>] [--json]
   siteos seo research wait <run-id> [--timeout <seconds>] [--environment <slug>] [--json]
   siteos seo research cancel <run-id> [--environment <slug>] [--json]
   siteos seo research export <run-id> --format <json|csv> --output <new-file> [--environment <slug>] [--json]
@@ -9014,14 +9015,15 @@ var RESEARCH_HELP = `
 
 Research request kinds: keywords, domain, rankings, backlinks, brand, ai-visibility.
 Read sections also accept --kind ai-rankings for category comparisons; --kind ai-visibility selects Prompt checks.
-Category run/plan inputs use kind ai-visibility with category-aeo-v2; both sections share AI request execution.
+Category run/plan inputs use kind ai-visibility with category-mentions-v3; both sections share AI request execution.
 Domain Overview: {"kind":"domain","target":"example.com","country":"US","language":"en"}.
 Domain collects summary, ranking keywords, top pages and competitors. The legacy competitors kind retains its two-part plan; domain history includes those reports.
 Request JSON: {"kind":"keywords","target":"example.com","keywords":["website analytics"],"country":"US","language":"en"}.
-Rankings accepts up to 10 keywords and 5 competitors. AI visibility accepts brand, platforms and either prompt or a category-aeo-v2 category with products and questions.
+Rankings accepts up to 10 keywords and 5 competitors. AI visibility accepts brand, platforms and either prompt or a category-mentions-v3 category with products and questions.
 Markets: US, GB, ES, DE, FR, CA, AU. Languages: en, es, de, fr, pt, it, nl, ru.
 Platforms: chat_gpt, claude, gemini, perplexity. Brand lookup uses brandPlatform chat_gpt|google and brandMatch domain|brand.
 Plan validates the request and shows planned parts and available research credits without enqueueing work.
+Retry creates a continuation using the original questions and platforms; category continuations collect ordinary text with category-mentions-v3; it preserves usable saved answers and only requests missing parts. It consumes credits and requires explicit scope authorization, like Run. Original reports and observation dates remain available.
 Run consumes Organization research credits through the same worker as the interface. Preserve the retry key after an uncertain response.
 SERP ensure collects one saved organic snapshot for a keyword returned by the selected completed Keyword Research report. It uses research credits once; repeating the same report/word returns the saved job, including failures. Show/wait/export only read and never spend. New reports can collect fresh snapshots.
 History returns the latest 30 checks per section; show/export can address older retained run IDs. Saved checks are limited to 100 per resource.
@@ -9089,6 +9091,7 @@ async function runSeoResearchCommand(options) {
       show: { args: 2, flags: [] },
       plan: { args: 1, flags: ["input"] },
       run: { args: 1, flags: ["input", "idempotency-key"] },
+      retry: { args: 2, flags: ["idempotency-key"] },
       wait: { args: 2, flags: ["timeout"] },
       cancel: { args: 2, flags: [] },
       export: { args: 2, flags: ["format", "output"] },
@@ -9131,7 +9134,7 @@ async function runSeoResearchCommand(options) {
           "The request file needs a research kind and target domain. Run siteos seo --help."
         );
     }
-    if (action === "run") {
+    if (action === "run" || action === "retry") {
       idempotencyKey = values["idempotency-key"] ?? randomUUID6();
       if (!/^[a-zA-Z0-9_-]{8,100}$/u.test(idempotencyKey))
         throw new Error(
@@ -9274,7 +9277,24 @@ async function runSeoResearchCommand(options) {
         stdout: JSON.stringify(record, null, 2)
       };
     }
-    if (action === "plan" || action === "run" || action === "saved save") {
+    if (action === "retry") {
+      const source = await get(`/runs/${encodeURIComponent(id)}`);
+      resourceSchema.parse(source.resource);
+      const original = runSchema.parse(source.run);
+      if (original.id !== id || ["queued", "running"].includes(original.state))
+        throw new Error("Choose the exact stopped research report to retry.");
+      record = await get("/runs", "run", {
+        request: original.request,
+        retryOf: id,
+        idempotencyKey
+      });
+      const next = runSchema.parse(record.run);
+      if (next.retryOf !== id || !isDeepStrictEqual(next.request, original.request))
+        throw new Error(
+          "The continued check does not match the original report."
+        );
+      record = { ...record, idempotencyKey };
+    } else if (action === "plan" || action === "run" || action === "saved save") {
       const plan = await get("/plan", "read", input);
       resourceSchema.parse(plan.resource);
       const canonical = requestSchema.parse(plan.request);