@siteoshq/cli 2.3.1 → 2.5.0

package/README.md

@@ -1,7 +1,7 @@
 # SiteOS CLI
 
 `@siteoshq/cli` exposes one `siteos` binary for Auth, common Projects, Pulse, Cookie, Forms,
-Search, Trace, SEO/GEO and Integrations. This source is version 2.2.0; source changes require a separate release to reach npm.
+Search, Trace, SEO/GEO and Integrations. This source is version 2.4.0; source changes require a separate release to reach npm.
 
 CLI 2 requires `siteos project use <id-or-slug> --environment <slug>` once per repository.
 It stores only the common selection in private `projects.json`; older service bindings are not
@@ -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
@@ -230,6 +231,11 @@ 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
+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.
 New request example: `{"kind":"domain","target":"example.com","country":"US","language":"en"}`.

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]
@@ -9012,17 +9013,20 @@ var RESEARCH_HELP = `
   siteos seo research saved save --input <request.json> --name <name> [--id <saved-id>] [--environment <slug>] [--json]
   siteos seo research saved remove <saved-id> [--environment <slug>] [--json]
 
-Research kinds: keywords, domain, rankings, backlinks, brand, ai-visibility.
+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.
 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 requires brand, prompt and platforms.
+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.
 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 settings; 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 kind; show/export can address older retained run IDs. Saved checks are limited to 100 per resource.
+History returns the latest 30 checks per section; show/export can address older retained run IDs. Saved checks are limited to 100 per resource.
 Wait defaults to 120 seconds (maximum 900); exit 3 means still pending, exit 4 means failed or cancelled. Partial evidence stays accessible.
 Exports preserve scope, dates and partial state. CSV stores one dataset row as JSON per row, including failed parts; it never converts missing metrics to zero.
 `;
@@ -9034,6 +9038,8 @@ var kinds = [
   "brand",
   "ai-visibility"
 ];
+var sections = [...kinds, "ai-rankings"];
+var sectionOf = (request) => request.kind === "ai-visibility" && request.category ? "ai-rankings" : request.kind;
 var requestSchema = z17.object({
   kind: z17.enum(["domain", ...kinds]).transform((kind) => kind === "domain" ? "competitors" : kind),
   target: z17.string().min(1).max(253)
@@ -9085,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"] },
@@ -9104,7 +9111,7 @@ async function runSeoResearchCommand(options) {
         "Provide --keyword with 1 to 200 characters from the selected keyword report."
       );
     if (values.kind === "domain") values.kind = "competitors";
-    if (operation.flags.includes("kind") && !kinds.includes(values.kind))
+    if (operation.flags.includes("kind") && !sections.includes(values.kind))
       throw new Error("Choose a documented --kind.");
     if (operation.flags.includes("input") && !values.input)
       throw new Error("Provide --input with a research request JSON file.");
@@ -9127,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(
@@ -9270,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);
@@ -9312,7 +9336,7 @@ async function runSeoResearchCommand(options) {
     } else if (action === "summary") {
       record = await get("/summary");
       resourceSchema.parse(record.resource);
-      z17.array(z17.object({ kind: z17.enum(kinds), summary: z17.unknown() })).parse(
+      z17.array(z17.object({ kind: z17.enum(sections), summary: z17.unknown() })).parse(
         record.checks
       );
     } else if (["status", "history", "saved list"].includes(action)) {
@@ -9326,13 +9350,13 @@ async function runSeoResearchCommand(options) {
           request: requestSchema
         }).passthrough()
       ).parse(view.saved);
-      if (runs.some((r) => r.request.kind !== values.kind) || saved.some((r) => r.request.kind !== values.kind))
+      if (runs.some((r) => sectionOf(r.request) !== values.kind) || saved.some((r) => sectionOf(r.request) !== values.kind))
         throw new Error(
           "The response does not match the requested research kind."
         );
       if (view.run != null) {
         const selected = runSchema.parse(view.run);
-        if (selected.request.kind !== values.kind)
+        if (sectionOf(selected.request) !== values.kind)
           throw new Error("The selected report has a different research kind.");
       }
       record = {
@@ -9395,6 +9419,25 @@ async function runSeoResearchCommand(options) {
             row
           ]);
         });
+        if (run.categoryReport) {
+          rows.push([
+            run.id,
+            run.websiteUrl,
+            run.request.kind,
+            run.request.target,
+            run.createdAt,
+            run.state,
+            run.error,
+            null,
+            null,
+            null,
+            null,
+            "category-report",
+            run.request,
+            { version: run.categoryReport.version },
+            run.categoryReport
+          ]);
+        }
         const content = values.format === "json" ? JSON.stringify(record, null, 2) : [
           [
             "run_id",
@@ -9888,7 +9931,7 @@ var SEO_HELP = `SEO/GEO: audit your website and research search-engine and AI vi
 
 Site Audit checks public HTML, canonical, robots.txt, sitemap and technical GEO signals.
 Performance measures selected pages with Lighthouse and compares response/rendered HTML.
-Research covers keywords, rankings, competitors, backlinks, Brand lookup and Prompt checks.
+Research covers keywords, rankings, competitors, backlinks, Brand lookup and AI visibility.
 GSC Insights reads your connected property's Google Search Console data; other research needs no GSC.
 Technical GEO checks crawler policies, content, snippets and structured-data syntax/shape.
 These checks do not measure autonomous agent journeys or guarantee AI inclusion or citations.