pagesight 0.18.0 → 0.20.0

package/src/cli.ts

@@ -1,3 +1,8 @@
+import { loadFollowupManifest } from "./followup-manifest.js";
+import { renderFollowup } from "./followup-text.js";
+import { renderInvestigation } from "./investigation-text.js";
+import { renderAssessment } from "./assessment-text.js";
+import { renderOpportunities } from "./opportunities-text.js";
 import { parseArgs } from "node:util";
 import { defaultDates } from "./shared/dates.js";
 import { execute } from "./api/index.js";
@@ -8,6 +13,11 @@ export const help = `Pagesight — read-only site evidence
 pagesight                      Show CLI help
 pagesight mcp                  Start MCP explicitly
 pagesight discover --url https://example.com/ [--providers gsc,ga]
+pagesight cloudflare audit --zone ZONE_ID --hostname example.com --start UTC_TIME --end UTC_TIME [--limit 50]
+
+pagesight change followup --manifest experiments.json [--as-of UTC_TIME] [--lag-days 3] [--format text]
+pagesight change evaluate --record change.json --baseline before.json [--current after.json] [--max-rows 20]
+pagesight technical compare --current current.json [--baseline previous.json]
 pagesight doctor --config seo.config.json
 pagesight gsc sites
 pagesight gsc sitemaps --site sc-domain:example.com
@@ -22,21 +32,27 @@ pagesight bing sites
 pagesight bing queries --site https://example.com/
 pagesight bing pages --site https://example.com/
 pagesight bing traffic --site https://example.com/
+pagesight ga realtime --property 123456 --request realtime.json
 pagesight ga accounts
 pagesight ga property --property 123456
 pagesight ga key-events --property 123456
 pagesight ga report --property 123456 --request report.json [--max-pages 4]
+pagesight render --url URL [--from-url URL --link-selector CSS] [--settle-ms 1000] [--timeout-ms 20000]
 pagesight page --url https://example.com/
 pagesight speed psi --url https://example.com/ [--strategy mobile]
 pagesight speed crux --url https://example.com/ [--origin] [--form-factor PHONE]
 pagesight speed history --url https://example.com/ [--origin]
 pagesight snapshot --config seo.config.json [--start YYYY-MM-DD --end YYYY-MM-DD]
+pagesight crawl --config seo.config.json [--max-pages 20] [--max-depth 3] [--inspect-limit 3]
+pagesight investigate --config seo.config.json --url https://example.com/page [--start YYYY-MM-DD --end YYYY-MM-DD] [--format text]
+pagesight assess --snapshot saved.json [--format text] [--max-rows 10]
+pagesight opportunities --snapshot saved.json [--min-impressions 20] [--max-clicks 2] [--max-rows 10] [--format text]
 pagesight compare --baseline before.json --current after.json [--max-rows 100]
 pagesight evidence import --request findings.json
 pagesight api --request operation.json
 pagesight serve [--port 6095]    Local HTTP API; requires PAGESIGHT_API_TOKEN
 
-All data commands emit JSON. --json is accepted for clarity.
+Data commands emit JSON by default; assess, opportunities, investigate and change followup accept --format text for readable summaries. --json is accepted for clarity.
 --out FILE saves the same evidence locally. Exit: 0 success, 1 provider failure,
 2 invalid input, 3 partial evidence. Snapshot defaults to 28 days ending Pacific
 today minus 3 days; max-pages defaults to 4 (ad hoc reports: 1; maximum: 20).
@@ -44,6 +60,48 @@ Credentials: GSC_* env, PAGESIGHT_GA_CREDENTIALS or GOOGLE_APPLICATION_CREDENTIA
 Requests, property metadata, provider limits and errors are preserved in evidence.
 `;
 
+// Every CLI command and the flags it accepts; surface tests fail when one has no case.
+export const commands: Record<string, string[]> = {
+  render: ["url", "from-url", "link-selector", "settle-ms", "timeout-ms"],
+  "cloudflare.audit": ["zone", "hostname", "start", "end", "limit"],
+  "change.followup": ["manifest", "as-of", "lag-days", "format"],
+  "change.evaluate": ["record", "baseline", "current", "max-rows"],
+  "technical.compare": ["baseline", "current"],
+  "evidence.import": ["request"],
+  crawl: ["config", "max-pages", "max-depth", "max-links", "inspect-limit", "include-query"],
+  investigate: ["config", "url", "start", "end", "max-pages", "max-rows", "format"],
+  assess: ["snapshot", "max-rows", "format"],
+  opportunities: ["snapshot", "max-rows", "format", "min-impressions", "max-clicks"],
+  discover: ["url", "providers"],
+  compare: ["baseline", "current", "max-rows"],
+  "bing.crawl-stats": ["site"],
+  "bing.crawl-issues": ["site"],
+  "bing.url-info": ["site", "url"],
+  "bing.link-counts": ["site", "max-pages"],
+  "bing.url-links": ["site", "url", "max-pages"],
+  "bing.sites": [],
+  "bing.queries": ["site"],
+  "bing.pages": ["site"],
+  "bing.traffic": ["site"],
+  "gsc.sites": [],
+  "gsc.sitemaps": ["site"],
+  "gsc.inspect": ["site", "url"],
+  "gsc.report": ["site", "request", "max-pages"],
+  "ga.realtime": ["property", "request"],
+  "ga.accounts": [],
+  "ga.property": ["property"],
+  "ga.key-events": ["property"],
+  "ga.report": ["property", "request", "max-pages"],
+  page: ["url"],
+  "speed.psi": ["url", "strategy"],
+  "speed.crux": ["url", "origin", "form-factor"],
+  "speed.history": ["url", "origin", "form-factor"],
+  doctor: ["config"],
+  snapshot: ["config", "start", "end", "max-pages"],
+  api: ["request"],
+  serve: ["port"],
+};
+
 async function jsonFile(path: string | undefined, label: string): Promise<unknown> {
   if (!path) throw new RequestError(`Missing --${label}`, null, "invalid_input");
   try {
@@ -60,6 +118,17 @@ export async function runCli(args: string[]): Promise<number> {
       allowPositionals: true,
       strict: true,
       options: {
+        zone: { type: "string" },
+        hostname: { type: "string" },
+        "from-url": { type: "string" },
+        "link-selector": { type: "string" },
+        "settle-ms": { type: "string" },
+        "timeout-ms": { type: "string" },
+        limit: { type: "string" },
+        record: { type: "string" },
+        manifest: { type: "string" },
+        "as-of": { type: "string" },
+        "lag-days": { type: "string" },
         port: { type: "string" },
         help: { type: "boolean", short: "h" },
         json: { type: "boolean" },
@@ -76,9 +145,17 @@ export async function runCli(args: string[]): Promise<number> {
         "form-factor": { type: "string" },
         origin: { type: "boolean" },
         providers: { type: "string" },
+        snapshot: { type: "string" },
+        format: { type: "string" },
         baseline: { type: "string" },
         current: { type: "string" },
         "max-rows": { type: "string" },
+        "min-impressions": { type: "string" },
+        "max-clicks": { type: "string" },
+        "max-depth": { type: "string" },
+        "max-links": { type: "string" },
+        "inspect-limit": { type: "string" },
+        "include-query": { type: "boolean" },
       },
     });
     if (args.length === 0 || values.help || positionals[0] === "help") {
@@ -86,42 +163,15 @@ export async function runCli(args: string[]): Promise<number> {
       return 0;
     }
     const [family, action] = positionals;
-    if (positionals.length > (["gsc", "ga", "bing", "speed", "evidence"].includes(family) ? 2 : 1))
+    if (
+      positionals.length >
+      (["gsc", "ga", "bing", "speed", "evidence", "cloudflare", "change", "technical"].includes(family) ? 2 : 1)
+    )
       throw new RequestError("Too many command arguments", null, "invalid_input");
-    const operation = ["gsc", "ga", "bing", "speed", "evidence"].includes(family)
+    const operation = ["gsc", "ga", "bing", "speed", "evidence", "cloudflare", "change", "technical"].includes(family)
       ? `${family}.${action ?? ""}`
       : family;
-    const flags: Record<string, string[]> = {
-      "evidence.import": ["request"],
-      discover: ["url", "providers"],
-      compare: ["baseline", "current", "max-rows"],
-      "bing.crawl-stats": ["site"],
-      "bing.crawl-issues": ["site"],
-      "bing.url-info": ["site", "url"],
-      "bing.link-counts": ["site", "max-pages"],
-      "bing.url-links": ["site", "url", "max-pages"],
-      "bing.sites": [],
-      "bing.queries": ["site"],
-      "bing.pages": ["site"],
-      "bing.traffic": ["site"],
-      "gsc.sites": [],
-      "gsc.sitemaps": ["site"],
-      "gsc.inspect": ["site", "url"],
-      "gsc.report": ["site", "request", "max-pages"],
-      "ga.accounts": [],
-      "ga.property": ["property"],
-      "ga.key-events": ["property"],
-      "ga.report": ["property", "request", "max-pages"],
-      page: ["url"],
-      "speed.psi": ["url", "strategy"],
-      "speed.crux": ["url", "origin", "form-factor"],
-      "speed.history": ["url", "origin", "form-factor"],
-      doctor: ["config"],
-      snapshot: ["config", "start", "end", "max-pages"],
-      api: ["request"],
-      serve: ["port"],
-    };
-    const allowed = [...(flags[operation] ?? []), ...(operation === "serve" ? [] : ["out", "json"])];
+    const allowed = [...(commands[operation] ?? []), ...(operation === "serve" ? [] : ["out", "json"])];
     for (const flag of Object.keys(values))
       if (!allowed.includes(flag))
         throw new RequestError(`--${flag} is not supported for ${operation}`, null, "invalid_input");
@@ -134,10 +184,80 @@ export async function runCli(args: string[]): Promise<number> {
       process.stderr.write(`Pagesight API listening on ${server.url}v1/query\n`);
       return 0;
     }
+    if (values.format && !["json", "text"].includes(values.format))
+      throw new RequestError("Use --format json or text", null, "invalid_input");
+    if (values.json && values.format === "text")
+      throw new RequestError("--json and --format text conflict", null, "invalid_input");
     let input: unknown;
     if (operation === "api") input = await jsonFile(values.request, "request");
-    else if (operation === "evidence.import")
+    else if (operation === "render") {
+      if (Boolean(values["from-url"]) !== Boolean(values["link-selector"]))
+        throw new RequestError("Supply both --from-url and --link-selector", null, "invalid_input");
+      input = {
+        operation: "page.verify",
+        url: values.url,
+        ...(values["from-url"]
+          ? { navigation: { fromUrl: values["from-url"], linkSelector: values["link-selector"] } }
+          : {}),
+        settleMs: Number(values["settle-ms"] ?? 1000),
+        timeoutMs: Number(values["timeout-ms"] ?? 20000),
+      };
+    } else if (operation === "evidence.import")
       input = { operation, document: await jsonFile(values.request, "request") };
+    else if (operation === "cloudflare.audit")
+      input = {
+        operation,
+        zone: values.zone,
+        hostname: values.hostname,
+        startTime: values.start,
+        endTime: values.end,
+        limit: Number(values.limit ?? 50),
+      };
+    else if (operation === "change.followup")
+      input = {
+        operation,
+        experiments: await loadFollowupManifest(values.manifest),
+        asOf: values["as-of"],
+        lagDays: Number(values["lag-days"] ?? 3),
+      };
+    else if (operation === "change.evaluate")
+      input = {
+        operation,
+        record: await jsonFile(values.record, "record"),
+        baseline: await jsonFile(values.baseline, "baseline"),
+        ...(values.current ? { current: await jsonFile(values.current, "current") } : {}),
+        maxRows: Number(values["max-rows"] ?? 20),
+      };
+    else if (operation === "crawl")
+      input = {
+        operation,
+        config: await jsonFile(values.config, "config"),
+        maxPages: Number(values["max-pages"] ?? 20),
+        maxDepth: Number(values["max-depth"] ?? 3),
+        maxLinks: Number(values["max-links"] ?? 500),
+        inspectLimit: Number(values["inspect-limit"] ?? 3),
+        includeQuery: values["include-query"] ?? false,
+      };
+    else if (operation === "technical.compare")
+      input = {
+        operation,
+        current: await jsonFile(values.current, "current"),
+        ...(values.baseline ? { baseline: await jsonFile(values.baseline, "baseline") } : {}),
+      };
+    else if (operation === "opportunities")
+      input = {
+        operation,
+        snapshot: await jsonFile(values.snapshot, "snapshot"),
+        minImpressions: Number(values["min-impressions"] ?? 20),
+        maxClicks: Number(values["max-clicks"] ?? 2),
+        maxRows: Number(values["max-rows"] ?? 10),
+      };
+    else if (operation === "assess")
+      input = {
+        operation,
+        snapshot: await jsonFile(values.snapshot, "snapshot"),
+        maxRows: Number(values["max-rows"] ?? 10),
+      };
     else if (operation === "compare")
       input = {
         operation,
@@ -145,14 +265,20 @@ export async function runCli(args: string[]): Promise<number> {
         current: await jsonFile(values.current, "current"),
         maxRows: Number(values["max-rows"] ?? 100),
       };
-    else if (operation === "snapshot" || operation === "doctor") {
+    else if (operation === "snapshot" || operation === "doctor" || operation === "investigate") {
       const config = await jsonFile(values.config, "config");
       if (operation === "doctor") input = { operation, config };
       else {
         if (Boolean(values.start) !== Boolean(values.end))
           throw new RequestError("Supply both --start and --end, or neither", null, "invalid_input");
         const dates = values.start ? { startDate: values.start, endDate: values.end } : defaultDates();
-        input = { operation, config, ...dates, maxPages: Number(values["max-pages"] ?? 4) };
+        input = {
+          operation,
+          config,
+          ...dates,
+          maxPages: Number(values["max-pages"] ?? (operation === "investigate" ? 1 : 4)),
+          ...(operation === "investigate" ? { url: values.url, maxRows: Number(values["max-rows"] ?? 28) } : {}),
+        };
       }
     } else {
       input = {
@@ -169,7 +295,16 @@ export async function runCli(args: string[]): Promise<number> {
       };
     }
     const result = await execute(input);
-    const output = `${JSON.stringify(result, null, 2)}\n`;
+    const output =
+      values.format === "text"
+        ? operation === "change.followup"
+          ? renderFollowup(result)
+          : operation === "investigate"
+            ? renderInvestigation(result)
+            : operation === "opportunities"
+              ? renderOpportunities(result)
+              : renderAssessment(result)
+        : `${JSON.stringify(result, null, 2)}\n`;
     if (values.out) await Bun.write(values.out, output);
     process.stdout.write(output);
     return result.status === "ok" ? 0 : result.status === "partial" ? 3 : 1;

package/src/followup-manifest.ts

@@ -0,0 +1,42 @@
+import { dirname, resolve } from "node:path";
+import { RequestError } from "./shared/http.js";
+
+export async function loadFollowupManifest(path: string | undefined): Promise<unknown[]> {
+  if (!path) throw new RequestError("Missing --manifest", null, "invalid_input");
+  let manifest: unknown;
+  try {
+    manifest = await Bun.file(path).json();
+  } catch {
+    throw new RequestError("Cannot read --manifest JSON file", null, "invalid_input");
+  }
+  if (!Array.isArray(manifest) || !manifest.length || manifest.length > 50)
+    throw new RequestError("Manifest must contain 1–50 experiment entries", null, "invalid_input");
+  const base = dirname(resolve(path));
+  const read = async (value: unknown) => {
+    if (typeof value !== "string" || !value) return null;
+    try {
+      return await Bun.file(resolve(base, value)).json();
+    } catch {
+      return null;
+    }
+  };
+  const entries = [];
+  for (const item of manifest) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      entries.push(null);
+      continue;
+    }
+    const entry = item as Record<string, unknown>;
+    if (Object.keys(entry).some((key) => !["label", "record", "baseline", "current"].includes(key))) {
+      entries.push(null);
+      continue;
+    }
+    entries.push({
+      label: entry.label,
+      record: await read(entry.record),
+      baseline: await read(entry.baseline),
+      ...(Object.hasOwn(entry, "current") ? { current: await read(entry.current) } : {}),
+    });
+  }
+  return entries;
+}

package/src/followup-text.ts

@@ -0,0 +1,45 @@
+import type { Evidence } from "./api/evidence.js";
+
+export function renderFollowup(evidence: Evidence): string {
+  const data = evidence.pages[0]?.response as
+    | {
+        asOf: string;
+        entries: Array<{
+          index: number;
+          label?: string;
+          id?: string;
+          status: string;
+          reason?: string;
+          confounded?: boolean;
+          reports?: Array<{
+            name: string;
+            status: string;
+            reason?: string;
+            nextCollection?: { date: string; timezone: string };
+          }>;
+        }>;
+      }
+    | undefined;
+  if (!data) return `Experiment follow-up unavailable: ${evidence.error?.message ?? evidence.status}\n`;
+  const lines = [
+    `Experiment follow-up as of ${data.asOf}`,
+    "Collection dates are planning estimates; no data is collected automatically.",
+    "",
+  ];
+  for (const entry of data.entries) {
+    lines.push(`${entry.label ?? `Entry ${entry.index + 1}`}${entry.id ? ` (${entry.id})` : ""}: ${entry.status}`);
+    if (entry.reason) lines.push(`  ${entry.reason}`);
+    if (entry.confounded) lines.push("  Declared overlapping changes confound attribution.");
+    for (const report of entry.reports ?? []) {
+      lines.push(
+        `  ${report.name}: ${report.status}${report.nextCollection ? ` — collect ${report.nextCollection.date} (${report.nextCollection.timezone})` : ""}`,
+      );
+      if (report.reason) lines.push(`    ${report.reason}`);
+    }
+    lines.push("");
+  }
+  lines.push(
+    "Readiness is per report. Review raw JSON warnings and source hashes; no causal SEO conclusion is implied.",
+  );
+  return lines.join("\n") + "\n";
+}

package/src/investigation-text.ts

@@ -0,0 +1,32 @@
+import type { Evidence } from "./api/evidence.js";
+import type { investigationBrief } from "./api/investigation.js";
+
+export function renderInvestigation(evidence: Evidence): string {
+  const response = evidence.pages[0]?.response as {
+    requestedDates: unknown;
+    context: unknown;
+    brief: ReturnType<typeof investigationBrief>;
+  };
+  const { brief } = response;
+  const quote = (value: unknown) =>
+    JSON.stringify(value).replace(
+      /[\u007f-\u009f\u2028\u2029]/gu,
+      (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`,
+    );
+  return [
+    `Pagesight investigation: ${quote(evidence.target)} (${evidence.status})`,
+    `Reporting window: ${quote(response.requestedDates)}`,
+    `Caller context (unverified): ${quote(response.context)}`,
+    ...brief.findings.map((f) => `Finding [${f.source}]: ${quote(f.statement)}`),
+    ...brief.tables.flatMap((t) => [
+      `Evidence [${t.source}]: ${quote({ displayPolicy: t.displayPolicy, dimensions: t.dimensions, metrics: t.metrics, rows: t.rows, observedRows: t.observedRows, omittedRows: t.omittedRows, unusableRows: t.unusableRows, paginationExhausted: t.paginationExhausted, collectedAt: t.collectedAt, metadata: t.metadata })}`,
+      ...t.warnings.map((w) => `Warning [${t.source}]: ${quote(w)}`),
+    ]),
+    ...brief.technical.map((t) => `Technical [${t.source}]: ${quote(t)}`),
+    "Full raw requests/responses and errors are available in JSON output.",
+    ...brief.unknowns.map((v) => `Unknown: ${quote(v)}`),
+    ...brief.nextChecks.map((v) => `Next check: ${quote(v)}`),
+    ...brief.limitations.map((v) => `Limitation: ${quote(v)}`),
+    "",
+  ].join("\n");
+}

package/src/opportunities-text.ts

@@ -0,0 +1,61 @@
+import type { Evidence } from "./api/evidence.js";
+
+const text = (value: unknown) =>
+  JSON.stringify(value).replace(
+    /[\u007f-\u009f\u2028\u2029]/gu,
+    (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`,
+  );
+export function renderOpportunities(result: Evidence): string {
+  const out = result.pages[0]?.response as
+    | {
+        site: string;
+        policy: unknown;
+        observedSearchRows: number | null;
+        unusableSearchRows: number;
+        qualifyingObservedRows: number | null;
+        omittedCandidates: number;
+        requestedDates: unknown;
+        snapshotSha256: string;
+        limitations: string[];
+        unassociatedOrganic: unknown[];
+        candidates: Array<{
+          url: string;
+          reason: string;
+          search: unknown;
+          organic: unknown;
+          technical: unknown;
+          unknowns: string[];
+          nextChecks: string[];
+          suggestedRequests: unknown[];
+        }>;
+      }
+    | undefined;
+  if (!out) return `${JSON.stringify(result, null, 2)}\n`;
+  const lines = [
+    `Pagesight opportunities: ${text(out.site)} (${result.status})`,
+    `Period: ${text(out.requestedDates)}; supplied snapshot, not reverified.`,
+    `Snapshot hash: ${out.snapshotSha256}`,
+    `Selection policy: ${text(out.policy)}`,
+    `Observed search rows: ${text(out.observedSearchRows)}; unusable: ${out.unusableSearchRows}; qualifying: ${text(out.qualifyingObservedRows)}; omitted candidates: ${out.omittedCandidates}`,
+  ];
+  for (const candidate of out.candidates)
+    lines.push(
+      "",
+      text(candidate.url),
+      `Why: ${text(candidate.reason)}`,
+      `Search: ${text(candidate.search)}`,
+      `Organic associations: ${text(candidate.organic)}`,
+      `Technical evidence: ${text(candidate.technical)}`,
+      ...candidate.unknowns.map((u) => `Unknown: ${text(u)}`),
+      ...candidate.nextChecks.map((n) => `Next check: ${text(n)}`),
+      ...candidate.suggestedRequests.map((request) => `Suggested API request: ${text(request)}`),
+    );
+  lines.push(
+    "",
+    ...out.unassociatedOrganic.map(
+      (table) => `Organic evidence not associated with displayed candidates: ${text(table)}`,
+    ),
+  );
+  lines.push("", ...out.limitations.map((l) => `Limit: ${text(l)}`));
+  return `${lines.join("\n")}\n`;
+}

package/src/providers/cloudflare.ts

@@ -0,0 +1,46 @@
+import { RequestError, readBounded } from "../shared/http.js";
+
+export type CloudflareQuery = { query: string; variables: Record<string, unknown> };
+export async function cloudflareGraphql(request: CloudflareQuery): Promise<unknown> {
+  const token = process.env.CLOUDFLARE_API_TOKEN;
+  if (!token)
+    throw new RequestError(
+      "Set CLOUDFLARE_API_TOKEN with read access to the selected zone's analytics",
+      null,
+      "not_configured",
+    );
+  const signal = AbortSignal.timeout(30_000);
+  let response: Response;
+  try {
+    response = await fetch("https://api.cloudflare.com/client/v4/graphql", {
+      method: "POST",
+      signal,
+      headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+      body: JSON.stringify(request),
+    });
+  } catch {
+    throw new RequestError("Cloudflare request failed or timed out", null, "network_error");
+  }
+  if (!response.ok) {
+    await response.body?.cancel();
+    throw new RequestError(
+      `Cloudflare returned HTTP ${response.status}`,
+      response.status,
+      response.status === 401
+        ? "unauthenticated"
+        : response.status === 403
+          ? "forbidden"
+          : response.status === 429
+            ? "quota_exceeded"
+            : "provider_error",
+    );
+  }
+  try {
+    return JSON.parse(await readBounded(response, 8_000_000));
+  } catch (error) {
+    if (error instanceof RequestError) throw error;
+    if (error instanceof SyntaxError)
+      throw new RequestError("Cloudflare response could not be read as JSON", response.status, "invalid_response");
+    throw new RequestError("Cloudflare response body failed or timed out", null, "network_error");
+  }
+}

package/src/tools/observe.ts

@@ -5,7 +5,7 @@ import { RequestError } from "../shared/http.js";
 export function registerObserveTool(server: McpServer): void {
   server.tool(
     "observe",
-    "Run the shared Pagesight API. Read-only operations: discover; bing.sites/queries/pages/traffic/crawl-stats/crawl-issues/url-info/link-counts/url-links; evidence.import (unverified UI findings); gsc.sites/sitemaps/inspect/report; ga.accounts/property/key-events/report; page (metadata and image ALT evidence); speed.psi/crux/history; doctor; snapshot; compare. Pass the API operation object as request. Returns structured evidence, exact effective requests, provider responses and partial errors. See the CLI --help and README for report/config shapes.",
+    "Run the shared Pagesight API. Evidence operations: page.verify (anonymous browser SEO evidence and one validated internal anchor navigation; may generate site requests); cloudflare.audit (bounded zone analytics/settings/security evidence); technical.compare (saved exact-page technical changes); change.followup (saved experiment collection dates and per-report blockers); change.evaluate (deployment context and comparable snapshot evidence); discover; bing.sites/queries/pages/traffic/crawl-stats/crawl-issues/url-info/link-counts/url-links; evidence.import (unverified UI findings); gsc.sites/sitemaps/inspect/report; ga.accounts/property/key-events/report/realtime; page (metadata and image ALT evidence); speed.psi/crux/history; doctor; snapshot; crawl (bounded robots-aware site graph and indexing sample); investigate (fresh exact-page search, organic and technical investigation); opportunities (saved search candidates); assess (saved evidence summary); compare. Pass the API operation object as request. Returns structured evidence, exact effective requests, provider responses and partial errors. See the CLI --help and README for report/config shapes.",
     { request: operationSchema },
     async ({ request }) => {
       try {

package/src/web/fetch.ts

@@ -1,6 +1,6 @@
 import { readBounded, RequestError } from "../shared/http.js";
 
-export async function fetchText(url: string, maxBytes: number, origin?: string) {
+export async function fetchText(url: string, maxBytes: number, origin?: string, proxy?: string) {
   const redirects: Array<{ url: string; status: number; location: string }> = [];
   let current = url;
   const signal = AbortSignal.timeout(20_000);
@@ -15,6 +15,7 @@ export async function fetchText(url: string, maxBytes: number, origin?: string)
       throw new RequestError("Redirect left the permitted origin or protocol", null, "invalid_redirect");
     const response = await fetch(current, {
       signal,
+      ...(proxy ? { proxy } : {}),
       redirect: "manual",
       headers: { "User-Agent": "Pagesight/0.17", Accept: "text/html,application/xml,text/plain" },
     });