@gscdump/cli 7.11.1 → 7.12.0

package/dist/agent-outcome.mjs

@@ -0,0 +1,38 @@
+import { agentOutcomeReceiptSchema } from "@gscdump/contracts";
+async function submitAgentOutcome(body, deps) {
+	const response = await deps.fetch(deps.url, {
+		method: "POST",
+		redirect: "error",
+		headers: {
+			"content-type": "application/json",
+			...deps.credential ? { authorization: `Bearer ${deps.credential}` } : {}
+		},
+		body: JSON.stringify(body),
+		signal: AbortSignal.timeout(1e4)
+	}).catch((cause) => ({
+		_tag: "FetchFailed",
+		cause
+	}));
+	if ("_tag" in response) return {
+		_tag: "Err",
+		reason: "unreachable",
+		message: "Could not reach the outcome endpoint. Do not retry an uncertain submission."
+	};
+	if (!response.ok) return {
+		_tag: "Err",
+		reason: "rejected",
+		message: `Outcome reporting returned HTTP ${response.status}.`
+	};
+	const data = await response.json().catch((cause) => ({ invalidResponse: cause instanceof Error ? cause.message : String(cause) }));
+	const parsed = agentOutcomeReceiptSchema.safeParse(data);
+	if (!parsed.success) return {
+		_tag: "Err",
+		reason: "rejected",
+		message: "The outcome endpoint returned an invalid receipt."
+	};
+	return {
+		_tag: "Ok",
+		receipt: parsed.data
+	};
+}
+export { submitAgentOutcome };

package/dist/bing-hosted.mjs

@@ -1,14 +1,17 @@
+import { useCliRuntime } from "./runtime.mjs";
 import { stopError } from "./stop.mjs";
 import { getHostedAccount, hostedCredential, siteManagerOf } from "./auth-state.mjs";
 import { logger } from "./utils.mjs";
 import { writeBingDump } from "./bing-data.mjs";
+import { hostedRequestContext } from "./hosted-context.mjs";
 import { noSitesStop } from "./hosted-site.mjs";
 import { createGscdumpV1Client } from "@gscdump/sdk/v1";
 const BING_SITES_COMMAND = "gscdump bing sites --json";
 function hostedBingClient(state) {
 	return createGscdumpV1Client({
 		apiRoot: state.apiRoot,
-		credential: hostedCredential(state)
+		credential: hostedCredential(state),
+		requestContext: hostedRequestContext(useCliRuntime().environment)
 	});
 }
 async function listHostedBingSites(state) {

package/dist/cli.mjs

@@ -7,7 +7,9 @@ import { resolveCliEnvironment } from "./environment.mjs";
 import { applyProfileFromCli } from "./commands/profile-selection.mjs";
 import { reportCliError } from "./error-handler.mjs";
 import { resolveOutputOptions, terminalOutputOptions } from "./render/terminal.mjs";
+import { SKILL_AGENTS, inspectSkillInstallation } from "./skill.mjs";
 import { VERSION, setNoColor, showSplash, withConfiguredOutput } from "./utils.mjs";
+import os from "node:os";
 import process from "node:process";
 import { defineCommand, renderUsage, runCommand } from "citty";
 function shouldShowSplash(rawArgs) {
@@ -139,6 +141,16 @@ async function runCli(opts = {}) {
 			runtime.jsonOutput = asksForJson(rawArgs);
 			const argumentError = await checkCliArgs(main, rawArgs);
 			if (argumentError) throw commandLineError(argumentError);
+			if (rawArgs[0] !== "skill" && !rawArgs.some((arg) => HELP_FLAGS.has(arg) || arg === "--version") && runtime.environment.GSCDUMP_NO_SKILL_CHECK !== "1") {
+				const states = await Promise.all(SKILL_AGENTS.map((agent) => inspectSkillInstallation({
+					agent,
+					homeDirectory: os.homedir()
+				})));
+				for (const state of states) {
+					if (state.state === "stale") runtime.logger.warn(`The ${state.agent} skill differs from this CLI. Run gscdump skill install --agent ${state.agent}, then re-read SKILL.md.`);
+					if (state.state === "unavailable") runtime.logger.warn(`Could not check the ${state.agent} skill: ${state.message}`);
+				}
+			}
 			await withConfiguredOutput(() => runMainCommand(rawArgs));
 			return 0;
 		} catch (error) {

package/dist/command-meta.mjs

@@ -88,8 +88,12 @@ const papercutCommandMeta = {
 	name: "papercut",
 	description: "Report a CLI problem to gscdump.com (anonymous, sanitized)"
 };
+const telemetryCommandMeta = {
+	name: "telemetry",
+	description: "Record an explicit agent task outcome"
+};
 const bingCommandMeta = {
 	name: "bing",
 	description: "Authenticate Bing, list sites, dump data, and read Indexing Evidence"
 };
-export { analyzeCommandMeta, authCommandMeta, bingCommandMeta, configCommandMeta, doctorCommandMeta, dumpCommandMeta, entitiesCommandMeta, indexingCommandMeta, initCommandMeta, inspectCommandMeta, mcpCommandMeta, papercutCommandMeta, profileCommandMeta, queryCommandMeta, reportCommandMeta, sitemapsCommandMeta, sitesCommandMeta, skillCommandMeta, storeCommandMeta, syncCommandMeta };
+export { analyzeCommandMeta, authCommandMeta, bingCommandMeta, configCommandMeta, doctorCommandMeta, dumpCommandMeta, entitiesCommandMeta, indexingCommandMeta, initCommandMeta, inspectCommandMeta, mcpCommandMeta, papercutCommandMeta, profileCommandMeta, queryCommandMeta, reportCommandMeta, sitemapsCommandMeta, sitesCommandMeta, skillCommandMeta, storeCommandMeta, syncCommandMeta, telemetryCommandMeta };

package/dist/command-registry.mjs

@@ -1,4 +1,4 @@
-import { analyzeCommandMeta, authCommandMeta, bingCommandMeta, configCommandMeta, doctorCommandMeta, dumpCommandMeta, entitiesCommandMeta, indexingCommandMeta, initCommandMeta, inspectCommandMeta, mcpCommandMeta, papercutCommandMeta, profileCommandMeta, queryCommandMeta, reportCommandMeta, sitemapsCommandMeta, sitesCommandMeta, skillCommandMeta, storeCommandMeta, syncCommandMeta } from "./command-meta.mjs";
+import { analyzeCommandMeta, authCommandMeta, bingCommandMeta, configCommandMeta, doctorCommandMeta, dumpCommandMeta, entitiesCommandMeta, indexingCommandMeta, initCommandMeta, inspectCommandMeta, mcpCommandMeta, papercutCommandMeta, profileCommandMeta, queryCommandMeta, reportCommandMeta, sitemapsCommandMeta, sitesCommandMeta, skillCommandMeta, storeCommandMeta, syncCommandMeta, telemetryCommandMeta } from "./command-meta.mjs";
 function resolveValue(value) {
 	return typeof value === "function" ? value() : value;
 }
@@ -130,6 +130,7 @@ const CLI_SUBCOMMANDS = {
 	doctor: shallowCommand(doctorCommandMeta, () => import("./commands/doctor.mjs").then((module) => module.doctorCommand)),
 	mcp: shallowCommand(mcpCommandMeta, () => import("./commands/mcp.mjs").then((module) => module.mcpCommand)),
 	skill: shallowCommand(skillCommandMeta, () => import("./commands/skill.mjs").then((module) => module.skillCommand)),
-	papercut: shallowCommand(papercutCommandMeta, () => import("./commands/papercut.mjs").then((module) => module.papercutCommand))
+	papercut: shallowCommand(papercutCommandMeta, () => import("./commands/papercut.mjs").then((module) => module.papercutCommand)),
+	telemetry: shallowCommand(telemetryCommandMeta, () => import("./commands/telemetry.mjs").then((module) => module.telemetryCommand))
 };
 export { CLI_SUBCOMMANDS, findSubCommandIndex, isUsageError, resolveUsageTarget, usageError };

package/dist/commands/auth.mjs

@@ -34,6 +34,7 @@ function loginNextStep(state, siteCount, issuer) {
 const HOSTED_COMMANDS = [
 	"sites",
 	"query",
+	"report",
 	"sitemaps current",
 	"sitemaps history",
 	"sitemaps membership",

package/dist/commands/papercut.mjs

@@ -8,24 +8,60 @@ import { confirm, isCancel } from "@clack/prompts";
 const papercutCommand = defineCommand({
 	meta: papercutCommandMeta,
 	args: {
-		command: {
+		"command": {
 			type: "string",
 			description: "The gscdump command that misbehaved, for example \"report triage\""
 		},
-		comment: {
+		"comment": {
 			type: "string",
 			description: "What you ran, what you expected, what happened, any workaround (sanitized)"
 		},
-		agent: {
+		"agent": {
 			type: "string",
 			description: "Reporter name, for example \"Claude Code\" or a person's handle"
 		},
-		intent: {
+		"intent": {
 			type: "string",
 			description: "bug (default) or improvement",
 			default: "bug"
 		},
-		yes: {
+		"request-id": {
+			type: "string",
+			description: "Request ID returned by the failed operation"
+		},
+		"parent-request-id": {
+			type: "string",
+			description: "Request ID returned by the calling application"
+		},
+		"workflow-id": {
+			type: "string",
+			description: "Opaque task identifier without customer content"
+		},
+		"origin": {
+			type: "string",
+			description: "Application host, for example requestindexing.com"
+		},
+		"product": {
+			type: "string",
+			description: "Application identifier"
+		},
+		"surface": {
+			type: "string",
+			description: "cli, mcp, api, skill, or browser"
+		},
+		"operation": {
+			type: "string",
+			description: "Operation identifier"
+		},
+		"skill-digest": {
+			type: "string",
+			description: "SHA-256 digest of the skill artifact"
+		},
+		"skill-version": {
+			type: "string",
+			description: "Declared skill version"
+		},
+		"yes": {
 			type: "boolean",
 			alias: "y",
 			default: false,
@@ -39,7 +75,16 @@ const papercutCommand = defineCommand({
 			command: args.command,
 			comment: args.comment,
 			agent: args.agent,
-			intent: args.intent
+			intent: args.intent,
+			requestId: args["request-id"],
+			parentRequestId: args["parent-request-id"],
+			workflowId: args["workflow-id"],
+			origin: args.origin,
+			product: args.product,
+			surface: args.surface,
+			operation: args.operation,
+			skillDigest: args["skill-digest"],
+			skillVersion: args["skill-version"]
 		});
 		if (built._tag === "Err") {
 			logger.error(`Invalid papercut: ${built.message}`);

package/dist/commands/profile-selection.mjs

@@ -1,8 +1,8 @@
 import { useCliRuntime } from "../runtime.mjs";
 import { setConfigDir } from "../config.mjs";
 import { resolveCliEnvironment } from "../environment.mjs";
-import path from "node:path";
 import os from "node:os";
+import path from "node:path";
 import fs from "node:fs";
 const ROOT_DIR = path.join(os.homedir(), ".config", "gscdump");
 const PROFILES_DIR = path.join(ROOT_DIR, "profiles");

package/dist/commands/report.mjs

@@ -1,8 +1,10 @@
+import { resolveAuthentication } from "../auth-state.mjs";
 import { reportCommandMeta } from "../command-meta.mjs";
 import { terminalOutputOptions } from "../render/terminal.mjs";
 import { logger, parseFetchBudget, setJsonOutput } from "../utils.mjs";
 import { COMPARISON_FLAGS, PERIOD_FLAGS, parseWindowFlags, windowFlagErrorToException } from "../window.mjs";
 import { analysisNeeds, analyzerSources, analyzerTables, resolveAnalysisSource } from "../analysis-local.mjs";
+import { runHostedReport } from "../hosted-report.mjs";
 import { renderCliReport } from "../render/report.mjs";
 import { defineCommand } from "citty";
 import { getLatestGscDate } from "gscdump/dates";
@@ -109,10 +111,15 @@ function makeReportCommand(report) {
 				default: false,
 				description: "Force live GSC API; bypass local store"
 			},
+			"force": {
+				type: "boolean",
+				default: false,
+				description: "Regenerate a Hosted report instead of reading its cache"
+			},
 			"json": {
 				type: "boolean",
 				default: false,
-				description: "Emit full ReportResult JSON"
+				description: "Emit report JSON with evidence coverage"
 			},
 			"explain": {
 				type: "boolean",
@@ -147,6 +154,22 @@ function makeReportCommand(report) {
 				}, null, 2));
 				return;
 			}
+			if (!args.live && (await resolveAuthentication())._tag === "Hosted") {
+				const result = await runHostedReport(report.id, args);
+				if (args.json) {
+					console.log(JSON.stringify(result, null, 2));
+					return;
+				}
+				console.log(`${report.id}: ${result.site}\n${result.window.start} to ${result.window.end}`);
+				for (const section of result.sections) {
+					console.log(`\n${section.title}${section.dataUnavailable ? " (unavailable)" : ""}`);
+					for (const finding of section.findings) console.log(`${finding.entity.value}: ${Object.entries(finding.metrics).map(([key, value]) => `${key}=${value}`).join(", ")}`);
+					if (section.truncated) logger.warn(`${section.id}: ${section.truncated.kept} of ${section.truncated.total} findings returned.`);
+				}
+				if (result.meta.degraded) logger.warn("Report evidence is incomplete. Read section coverage before drawing conclusions.");
+				return;
+			}
+			if (args.force) throw new Error("--force regenerates a Hosted report. Select Hosted mode to use it.");
 			const steps = (window) => report.plan(params, window).map((step) => ({
 				type: step.type,
 				params: {

package/dist/commands/skill.mjs

@@ -1,9 +1,9 @@
 import { skillCommandMeta } from "../command-meta.mjs";
+import { SKILL_AGENTS, SKILL_NAME, inspectSkillInstallation, installSkill } from "../skill.mjs";
 import { OUTPUT_ARGS, applyOutputMode, displayPath, logger } from "../utils.mjs";
-import { SKILL_AGENTS, SKILL_NAME, installSkill } from "../skill.mjs";
+import os from "node:os";
 import process from "node:process";
 import { defineCommand } from "citty";
-import os from "node:os";
 const installCommand = defineCommand({
 	meta: {
 		name: "install",
@@ -44,6 +44,37 @@ const installCommand = defineCommand({
 });
 const skillCommand = defineCommand({
 	meta: skillCommandMeta,
-	subCommands: { install: installCommand }
+	subCommands: {
+		install: installCommand,
+		status: defineCommand({
+			meta: {
+				name: "status",
+				description: "Compare installed skill content with the packaged artifact"
+			},
+			args: {
+				agent: {
+					type: "string",
+					default: "claude",
+					description: `Agent skill directory: ${SKILL_AGENTS.join(" or ")}`
+				},
+				target: {
+					type: "string",
+					description: "Inspect this directory instead of the agent home directory"
+				},
+				...OUTPUT_ARGS
+			},
+			async run({ args }) {
+				applyOutputMode(args);
+				const agent = SKILL_AGENTS.find((name) => name === args.agent);
+				if (!agent) throw new Error(`Unknown agent "${args.agent}". Use ${SKILL_AGENTS.join(" or ")}.`);
+				const result = await inspectSkillInstallation({
+					agent,
+					homeDirectory: os.homedir(),
+					target: args.target
+				});
+				console.log(JSON.stringify(result));
+			}
+		})
+	}
 });
 export { skillCommand };

package/dist/commands/telemetry.mjs

@@ -0,0 +1,142 @@
+import { useCliRuntime } from "../runtime.mjs";
+import { hostedCredential, resolveAuthentication } from "../auth-state.mjs";
+import { OUTPUT_ARGS, VERSION, applyOutputMode } from "../utils.mjs";
+import { resolvePapercutUrl } from "../papercut.mjs";
+import { submitAgentOutcome } from "../agent-outcome.mjs";
+import process from "node:process";
+import { defineCommand } from "citty";
+import { randomUUID } from "node:crypto";
+import { agentOutcomeBodySchema } from "@gscdump/contracts";
+import { confirm, isCancel } from "@clack/prompts";
+const telemetryCommand = defineCommand({
+	meta: {
+		name: "telemetry",
+		description: "Record an explicit agent task outcome"
+	},
+	subCommands: { record: defineCommand({
+		meta: {
+			name: "record",
+			description: "Submit bounded task metadata without prompts or output bodies"
+		},
+		args: {
+			"event-id": {
+				type: "string",
+				description: "Stable event ID; defaults to a new UUID"
+			},
+			"workflow-id": {
+				type: "string",
+				required: true,
+				description: "Opaque task identifier"
+			},
+			"request-id": {
+				type: "string",
+				description: "Related server request ID"
+			},
+			"parent-request-id": {
+				type: "string",
+				description: "Related consumer request ID"
+			},
+			"product": {
+				type: "string",
+				default: "gscdump",
+				description: "Declared originating application"
+			},
+			"surface": {
+				type: "string",
+				default: "cli",
+				description: "cli, mcp, api, skill, or browser"
+			},
+			"operation": {
+				type: "string",
+				required: true,
+				description: "Operation identifier without arguments"
+			},
+			"step": {
+				type: "string",
+				default: "complete",
+				description: "setup, read, diagnose, fix, verify, or complete"
+			},
+			"outcome": {
+				type: "string",
+				required: true,
+				description: "success, failure, blocked, or cancelled"
+			},
+			"semantic-flags": {
+				type: "string",
+				description: "Comma-separated empty, unavailable, refused, provisional, partial, stale, truncated"
+			},
+			"row-count": {
+				type: "string",
+				description: "Measured domain row count"
+			},
+			"duration-ms": {
+				type: "string",
+				description: "Measured task duration"
+			},
+			"quality": {
+				type: "string",
+				default: "unknown",
+				description: "Declared useful, unusable, incorrect, or unknown"
+			},
+			"error-code": {
+				type: "string",
+				description: "Stable error code"
+			},
+			"skill-digest": {
+				type: "string",
+				description: "SHA-256 digest of the skill artifact"
+			},
+			"skill-version": {
+				type: "string",
+				description: "Declared skill version"
+			},
+			"yes": {
+				type: "boolean",
+				alias: "y",
+				default: false,
+				description: "Submit without confirmation"
+			},
+			...OUTPUT_ARGS
+		},
+		async run({ args }) {
+			const { json } = applyOutputMode(args);
+			const body = agentOutcomeBodySchema.parse({
+				eventId: args["event-id"] || randomUUID(),
+				workflowId: args["workflow-id"],
+				requestId: args["request-id"],
+				parentRequestId: args["parent-request-id"],
+				product: args.product,
+				surface: args.surface,
+				operation: args.operation,
+				step: args.step,
+				outcome: args.outcome,
+				semanticFlags: args["semantic-flags"] ? args["semantic-flags"].split(",").map((flag) => flag.trim()) : [],
+				rowCount: args["row-count"] !== void 0 ? Number(args["row-count"]) : void 0,
+				durationMs: args["duration-ms"] !== void 0 ? Number(args["duration-ms"]) : void 0,
+				quality: args.quality,
+				errorCode: args["error-code"],
+				skillDigest: args["skill-digest"],
+				skillVersion: args["skill-version"],
+				cliVersion: VERSION
+			});
+			if (!args.yes) {
+				if (!process.stdin.isTTY || json) throw new Error("Pass --yes to submit this declared task outcome.");
+				const accepted = await confirm({ message: "Submit this declared agent task outcome?" });
+				if (isCancel(accepted) || !accepted) return;
+			}
+			const runtime = useCliRuntime();
+			const url = resolvePapercutUrl(runtime.environment).replace(/\/papercuts$/, "/agent-outcomes");
+			const authentication = await resolveAuthentication();
+			if (authentication._tag === "Hosted" && new URL(url).origin !== new URL(authentication.apiRoot).origin) throw new Error("The outcome endpoint does not match the Hosted credential origin.");
+			const credential = authentication._tag === "Hosted" ? hostedCredential(authentication) : void 0;
+			const result = await submitAgentOutcome(body, {
+				fetch: globalThis.fetch,
+				url,
+				credential
+			});
+			if (result._tag === "Err") throw new Error(result.message);
+			console.log(JSON.stringify(result.receipt));
+		}
+	}) }
+});
+export { telemetryCommand };

package/dist/config.mjs

@@ -1,8 +1,8 @@
 import { useCliRuntime } from "./runtime.mjs";
+import os from "node:os";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
-import os from "node:os";
 import { SearchTypes } from "gscdump/query";
 function setConfigDir(dir) {
 	useCliRuntime().configDir = dir;

package/dist/dump-writers.mjs

@@ -1,8 +1,8 @@
 import { exportColumns, readParquetSql, sourceSelectSql, sqlString } from "./table-sources.mjs";
+import os from "node:os";
 import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
-import os from "node:os";
 import { DuckDBInstance } from "@duckdb/node-api";
 import { encodeRowsToParquetFlex } from "@gscdump/engine/hyparquet";
 const DUMP_FORMATS = [

package/dist/hosted-context.mjs

@@ -0,0 +1,13 @@
+import { VERSION } from "./utils.mjs";
+import { agentRequestContextSchema } from "@gscdump/contracts";
+function hostedRequestContext(environment) {
+	return agentRequestContextSchema.parse({
+		cliVersion: VERSION,
+		client: "gscdump-cli",
+		product: environment.GSCDUMP_PRODUCT ?? "gscdump",
+		workflowId: environment.GSCDUMP_WORKFLOW_ID,
+		parentRequestId: environment.GSCDUMP_PARENT_REQUEST_ID,
+		skillDigest: environment.GSCDUMP_SKILL_DIGEST
+	});
+}
+export { hostedRequestContext };

package/dist/hosted-report.mjs

@@ -0,0 +1,40 @@
+import { resolveHostedSite } from "./hosted-site.mjs";
+import { runReportV1RequestSchema } from "@gscdump/contracts/v1";
+function hostedReportRequest(reportId, args) {
+	if (args["prev-start"] || args["prev-end"] || args["fetch-budget"]) throw new Error("Hosted reports do not accept --prev-start, --prev-end, or --fetch-budget. Use --vs for comparison.");
+	const period = args.period ? String(args.period).replace(/^(\d+d)$/, "last-$1") : void 0;
+	return runReportV1RequestSchema.parse({
+		reportId,
+		period,
+		comparison: args.vs,
+		start: args.start,
+		end: args.end,
+		target: args.target,
+		targetKind: args["target-kind"],
+		brandTerms: args["brand-terms"],
+		topic: args.topic,
+		maxFindings: args["max-findings"] !== void 0 ? Number(args["max-findings"]) : void 0,
+		minClicksChange: args["min-clicks-change"] !== void 0 ? Number(args["min-clicks-change"]) : void 0,
+		force: Boolean(args.force)
+	});
+}
+async function runHostedReport(reportId, args) {
+	const body = hostedReportRequest(reportId, args);
+	const { client, site } = await resolveHostedSite(args, {
+		name: `report ${reportId}`,
+		localAlternative: "run the report against your Store"
+	});
+	const response = await client.runReport({
+		params: { siteId: site.siteId },
+		body
+	});
+	return {
+		...response.data,
+		meta: {
+			...response.data.meta,
+			requestId: response.meta.requestId,
+			source: "hosted"
+		}
+	};
+}
+export { hostedReportRequest, runHostedReport };

package/dist/hosted-site.mjs

@@ -2,6 +2,7 @@ import { stopError } from "./stop.mjs";
 import { connectSiteStep, getHostedAccount, hostedCredential, parseAuthentication, resolveAuthentication, siteManagerOf } from "./auth-state.mjs";
 import { loadConfig } from "./config.mjs";
 import { resolveCliEnvironment } from "./environment.mjs";
+import { hostedRequestContext } from "./hosted-context.mjs";
 import { createGscdumpV1Client } from "@gscdump/sdk/v1";
 const HOSTED_ARGS = {
 	"site": {
@@ -104,7 +105,8 @@ async function resolveHostedSite(args, command) {
 	return {
 		client: createGscdumpV1Client({
 			apiRoot: authentication.apiRoot,
-			credential: hostedCredential(authentication)
+			credential: hostedCredential(authentication),
+			requestContext: hostedRequestContext(environment)
 		}),
 		site: match.site,
 		authentication,

package/dist/package.mjs

@@ -1,2 +1,2 @@
-var version = "7.11.1";
+var version = "7.12.0";
 export { version };

package/dist/papercut.mjs

@@ -1,28 +1,18 @@
 import { VERSION } from "./utils.mjs";
 import process from "node:process";
 import { z } from "zod";
+import { cliPapercutBodySchema } from "@gscdump/contracts";
 const DEFAULT_PAPERCUT_BASE_URL = "https://gscdump.com";
 const PAPERCUT_PATH = "/api/cli/papercuts";
 const REQUEST_TIMEOUT_MS = 1e4;
-const singleLine = (max) => z.string().trim().min(1).max(max).regex(/^\P{Cc}*$/u, "must be a single line without control characters");
-const papercutBodySchema = z.strictObject({
-	command: singleLine(200),
-	comment: z.string().trim().min(1).max(2e3),
-	agent: singleLine(100),
-	intent: z.enum(["bug", "improvement"]).default("bug"),
-	cliVersion: singleLine(64),
-	node: singleLine(64),
-	platform: singleLine(32)
-});
+const papercutBodySchema = cliPapercutBodySchema;
 const receiptSchema = z.object({
 	id: z.string().min(1),
 	status: z.literal("new")
 });
 function buildPapercutBody(input) {
 	const parsed = papercutBodySchema.safeParse({
-		command: input.command,
-		comment: input.comment,
-		agent: input.agent,
+		...input,
 		intent: input.intent ?? "bug",
 		cliVersion: VERSION,
 		node: process.versions.node,
@@ -77,14 +67,14 @@ async function submitPapercut(body, deps) {
 	if (response.status === 400 || response.status === 422) return {
 		_tag: "Err",
 		reason: "invalid_input",
-		message: `gscdump.com rejected the papercut: ${(await response.text().catch(() => "")).slice(0, 300) || response.status}`
+		message: `gscdump.com rejected the papercut: ${(await response.text()).slice(0, 300) || response.status}`
 	};
 	if (!response.ok) return {
 		_tag: "Err",
 		reason: "rejected",
 		message: `gscdump.com answered ${response.status}.`
 	};
-	const json = await response.json().catch(() => null);
+	const json = await response.json().catch((cause) => ({ invalidResponse: cause instanceof Error ? cause.message : String(cause) }));
 	const receipt = receiptSchema.safeParse(json);
 	if (!receipt.success) return {
 		_tag: "Err",

package/dist/runtime.mjs

@@ -1,7 +1,7 @@
+import os from "node:os";
 import process from "node:process";
 import path from "node:path";
 import { AsyncLocalStorage } from "node:async_hooks";
-import os from "node:os";
 import { createConsola } from "consola";
 let runtimeStorage;
 let fallbackRuntime;

package/dist/skill.mjs

@@ -1,4 +1,5 @@
-import { cp, mkdir, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { cp, mkdir, mkdtemp, readFile, readdir, rename, rm, stat } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 const SKILL_NAME = "gscdump";
@@ -13,6 +14,78 @@ function skillSourceDirectory(moduleUrl = import.meta.url) {
 function skillDestination(homeDirectory, agent) {
 	return path.join(homeDirectory, AGENT_DIRECTORIES[agent], "skills", SKILL_NAME);
 }
+async function skillDigest(directory) {
+	const hash = createHash("sha256");
+	async function read(relative) {
+		const entries = await readdir(path.join(directory, relative), { withFileTypes: true });
+		entries.sort((a, b) => a.name.localeCompare(b.name));
+		for (const entry of entries) {
+			if (entry.name.startsWith(".")) continue;
+			const name = relative ? `${relative}/${entry.name}` : entry.name;
+			if (entry.isDirectory()) await read(name);
+			else if (entry.isFile()) hash.update(name).update("\0").update(await readFile(path.join(directory, name))).update("\0");
+			else throw new Error(`The skill contains an unsupported file at ${name}.`);
+		}
+	}
+	await read("");
+	return hash.digest("hex");
+}
+async function inspectSkillInstallation(options) {
+	const destination = options.target ? path.join(options.target, SKILL_NAME) : skillDestination(options.homeDirectory, options.agent);
+	if (!await stat(destination).then(() => true).catch((cause) => {
+		if (cause !== null && typeof cause === "object" && "code" in cause && cause.code === "ENOENT") return false;
+		throw cause;
+	})) return {
+		state: "not-installed",
+		agent: options.agent,
+		destination
+	};
+	return Promise.all([skillDigest(destination), skillDigest(options.sourceDirectory ?? skillSourceDirectory())]).then(([installedDigest, packagedDigest]) => ({
+		state: installedDigest === packagedDigest ? "current" : "stale",
+		agent: options.agent,
+		destination,
+		installedDigest,
+		packagedDigest
+	})).catch((cause) => ({
+		state: "unavailable",
+		agent: options.agent,
+		destination,
+		message: cause instanceof Error ? cause.message : String(cause)
+	}));
+}
+async function replaceSkill(source, destination) {
+	await mkdir(path.dirname(destination), { recursive: true });
+	const staging = await mkdtemp(path.join(path.dirname(destination), ".gscdump-skill-"));
+	const candidate = path.join(staging, "candidate");
+	const backup = path.join(staging, "previous");
+	const digest = await cp(source, candidate, {
+		recursive: true,
+		force: true
+	}).then(() => skillDigest(candidate)).catch(async (cause) => {
+		await rm(staging, {
+			recursive: true,
+			force: true
+		});
+		throw cause;
+	});
+	const previous = await rename(destination, backup).then(() => "moved").catch((cause) => {
+		if (cause !== null && typeof cause === "object" && "code" in cause && cause.code === "ENOENT") return "absent";
+		throw cause;
+	});
+	await rename(candidate, destination).catch(async (cause) => {
+		if (previous === "moved") await rename(backup, destination);
+		await rm(staging, {
+			recursive: true,
+			force: true
+		});
+		throw cause;
+	});
+	await rm(staging, {
+		recursive: true,
+		force: true
+	});
+	return digest;
+}
 async function installSkill(options) {
 	const source = options.sourceDirectory ?? skillSourceDirectory();
 	if (!(await stat(source).catch(() => {
@@ -23,15 +96,13 @@ async function installSkill(options) {
 		message: `The packaged skill is missing at ${source}. Reinstall @gscdump/cli, then run the command again.`
 	};
 	const destination = options.target ? path.join(options.target, SKILL_NAME) : skillDestination(options.homeDirectory, options.agent);
-	return mkdir(path.dirname(destination), { recursive: true }).then(() => cp(source, destination, {
-		recursive: true,
-		force: true
-	})).then(() => ({
+	return replaceSkill(source, destination).then((digest) => ({
 		_tag: "Ok",
 		installation: {
 			agent: options.agent,
 			source,
-			destination
+			destination,
+			digest
 		}
 	})).catch((cause) => {
 		const detail = cause instanceof Error ? cause.message : String(cause);
@@ -42,4 +113,4 @@ async function installSkill(options) {
 		};
 	});
 }
-export { SKILL_AGENTS, SKILL_NAME, installSkill, skillDestination, skillSourceDirectory };
+export { SKILL_AGENTS, SKILL_NAME, inspectSkillInstallation, installSkill, skillDestination, skillSourceDirectory };

package/dist/utils.mjs

@@ -1,9 +1,9 @@
 import { useCliRuntime } from "./runtime.mjs";
 import { commandLineError } from "./stop.mjs";
 import { version } from "./package.mjs";
+import os from "node:os";
 import process from "node:process";
 import fs from "node:fs/promises";
-import os from "node:os";
 import { SearchTypes } from "gscdump/query";
 import { Buffer } from "node:buffer";
 import { MAX_FETCH_BUDGET } from "@gscdump/engine/analysis-types";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/cli",
   "type": "module",
-  "version": "7.11.1",
+  "version": "7.12.0",
   "description": "CLI for Google Search Console and Bing with hosted or local authentication, data exports, and an MCP server",
   "author": {
     "name": "Harlan Wilton",
@@ -44,16 +44,16 @@
   "dependencies": {
     "@clack/prompts": "^1.8.1",
     "@duckdb/node-api": "1.5.5-r.5",
-    "@gscdump/analysis": "^7.11.1",
-    "@gscdump/contracts": "^7.11.1",
-    "@gscdump/engine": "^7.11.1",
-    "@gscdump/engine-gsc-api": "^7.11.1",
-    "@gscdump/sdk": "^7.11.1",
+    "@gscdump/analysis": "^7.12.0",
+    "@gscdump/contracts": "^7.12.0",
+    "@gscdump/engine": "^7.12.0",
+    "@gscdump/engine-gsc-api": "^7.12.0",
+    "@gscdump/sdk": "^7.12.0",
     "@modelcontextprotocol/sdk": "^1.30.1",
     "citty": "^0.2.2",
     "consola": "^3.4.2",
     "google-auth-library": "^11.1.0",
-    "gscdump": "^7.11.1",
+    "gscdump": "^7.12.0",
     "ofetch": "^1.5.1",
     "open": "^11.0.4",
     "proper-lockfile": "^4.1.2",

package/skills/gscdump/SKILL.md

@@ -18,6 +18,10 @@ Example: `gscdump query --site=SITE --start=DATE --end=DATE -d page -f json`.
 
 ## Start each task
 
+Run `gscdump skill status --agent codex --json` for Codex, or use `--agent claude` for Claude.
+If the result is `stale`, reinstall that agent's skill and re-read it before continuing.
+The check compares the complete artifact, including references. A matching version alone does not prove matching instructions.
+
 1. Before reading traffic, run `gscdump auth status --json`. Do this even when the user says authentication works.
 2. Keep the requested Site, dates, dimensions, and task scope. A request for pages does not need query dimensions.
 3. In Hosted mode, skip steps 3 to 5. `gscdump query` reads the hosted record, and `sync` needs Local mode.
@@ -73,7 +77,7 @@ gscdump sites --json
 gscdump query --site example.com -d page -f json
 ```
 
-Hosted mode can run only these commands: `sites`, `query`, `sitemaps current`, `sitemaps history`, `sitemaps membership`,
+Hosted mode can run these commands: `sites`, `query`, `report`, `sitemaps current`, `sitemaps history`, `sitemaps membership`,
 `sitemaps lastmod`, `sitemaps export`, `sitemaps inspect`, `indexing urls`, `indexing inspect --yes`, `indexing summary`, `indexing watch list|add|remove`,
 and the `bing` commands `login --site`, `sites`, `status`, `dump`, `inspect`, and `verify`.
 Direct Google commands need Local mode: `sync`, `inspect`, `query --live`, `analyze --live`, `report --live`,
@@ -119,7 +123,13 @@ Hosted sitemap reads and the hosted `indexing` commands need Hosted mode. Their
 ## Routing
 
 This section covers Local mode. In Hosted mode, `query` always reads the hosted record, and JSON has `meta.source: "hosted"`.
-`analyze` and `report` read the Store only in Hosted mode. When the Store cannot answer, they stop with the Local mode command.
+`report` runs deterministic reports through the hosted record in Hosted mode. It needs no local Store.
+Its JSON preserves `cached`, `generatedAt`, the resolved `window`, section `coverage`, `truncated`, and `dataUnavailable`.
+Its `meta.requestId` correlates successful reads with feedback. `meta.source` is `hosted`.
+A section with `dataUnavailable: true` is unavailable evidence, not an empty finding.
+`--force` regenerates the Hosted report. `--prev-start`, `--prev-end`, and `--fetch-budget` need Local mode.
+Hosted reports preserve `--max-findings` from 1 to 1000. Movers also preserves `--min-clicks-change`.
+`analyze` reads the Store only in Hosted mode. When the Store cannot answer, it stops with the Local mode command.
 
 `query`, `analyze`, and `report` choose one source for each run. One run never
 mixes Store rows and live rows.
@@ -292,6 +302,7 @@ A routing stop also has `siteUrl`. `STORE_RANGE_NOT_COVERED` adds `missingDates`
 | `gscdump mcp` | Start Google MCP tools in Local mode. Hosted mode uses `https://gscdump.com/mcp` |
 | `gscdump skill install` | Copy this skill into an agent skill directory |
 | `gscdump papercut` | Report a CLI problem to gscdump.com |
+| `gscdump telemetry record` | Explicitly record bounded, declared task quality without prompts or output bodies |
 
 `gscdump login`, `gscdump logout`, and `gscdump status` are top-level aliases of
 the matching `auth` subcommands.
@@ -404,6 +415,11 @@ gscdump papercut --command "report triage" --agent "Claude Code" \
 - Include what you ran, what you expected, what happened, and any workaround.
 - `--intent improvement` marks a suggestion. The default is `bug`.
 - The CLI adds its version, Node version, and platform.
+- Add `--request-id` when the failed operation returned one.
+- Add `--parent-request-id` when a consumer returned a separate request ID.
+- Use `--origin requestindexing.com --product requestindexing` for work started there.
+- `--surface cli|mcp|api|skill|browser`, `--operation`, `--workflow-id`, `--skill-digest`, and `--skill-version` add safe context.
+- These fields are declared context. They do not prove authorization or credential origin.
 - Send sanitized details only. Remove tokens, cookies, personal data, private
   URLs, and customer rows. Use placeholder arguments.
 
@@ -415,6 +431,29 @@ The endpoint is anonymous and allows ten reports per network address each
 hour. Success returns `id` and `status: "new"`. If reporting fails, mention
 the failure and continue. Never retry an uncertain submission.
 
+Hosted requests send the CLI version and client identity. Optional environment variables add declared context:
+`GSCDUMP_PRODUCT`, `GSCDUMP_WORKFLOW_ID`, `GSCDUMP_PARENT_REQUEST_ID`, and `GSCDUMP_SKILL_DIGEST`.
+Use opaque IDs, never prompts, private URLs, or customer rows. No local command history uploads automatically.
+
+## Record task quality
+
+After an agent workflow, record one explicit terminal outcome when reporting is allowed.
+Reuse one opaque workflow ID throughout the task. Never put customer content in an ID.
+
+```sh
+gscdump telemetry record --workflow-id task_01 --operation indexing.summary \
+  --outcome success --quality useful --yes --json
+```
+
+Use `failure`, `blocked`, or `cancelled` when the task did not complete.
+Add measured `--row-count` and `--duration-ms` only when known.
+Use `--semantic-flags` for simultaneous conditions, such as `partial,stale,truncated`.
+Add request IDs, product, and skill digest when available. Use `--quality unknown` when usefulness is unmeasured.
+This records an agent claim. It never proves that a repair passed engine verification.
+Record incorrect or unusable answers, and submit a separate sanitized papercut for reproduction.
+This skill authorizes bounded task-outcome reports, subject to the user's reporting restrictions.
+If submission fails, mention it and continue. Never retry an uncertain submission.
+
 ## Guardrails
 
 - **Get consent before a mutation.** `sites add`, `sites delete`,