@gscdump/cli 3.6.1 → 3.6.3

package/dist/cli-args.mjs

@@ -0,0 +1,63 @@
+import { parseArgs } from "node:util";
+async function resolve(value) {
+	return typeof value === "function" ? value() : value;
+}
+async function checkCliArgs(command, rawArgs, path = "gscdump") {
+	const definitions = await resolve(command.args ?? {});
+	const options = {
+		"help": { type: "boolean" },
+		"h": { type: "boolean" },
+		"version": { type: "boolean" },
+		"no-color": { type: "boolean" }
+	};
+	for (const [name, definition] of Object.entries(definitions)) {
+		if (definition.type === "positional") continue;
+		const type = definition.type === "boolean" ? "boolean" : "string";
+		const alias = "alias" in definition ? definition.alias : void 0;
+		const names = [
+			name,
+			...typeof alias === "string" ? [alias] : alias ?? [],
+			name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase()),
+			name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)
+		];
+		for (const key of names) {
+			options[key] = { type };
+			if (type === "boolean" && !key.startsWith("no-")) options[`no-${key}`] = { type };
+		}
+	}
+	const { tokens } = parseArgs({
+		args: rawArgs,
+		options,
+		strict: false,
+		allowPositionals: true,
+		tokens: true
+	});
+	const subCommands = await resolve(command.subCommands ?? {});
+	const positional = tokens.find((token) => token.kind === "positional");
+	const hasSubCommands = Object.keys(subCommands).length > 0;
+	const boundary = hasSubCommands && positional ? positional.index : rawArgs.length;
+	for (const token of tokens) {
+		if (token.index >= boundary || token.kind !== "option") continue;
+		const option = options[token.name];
+		if (!option) {
+			const matches = Object.keys(definitions).filter((name) => definitions[name]?.type !== "positional" && name.startsWith(token.name) && name.length - token.name.length <= 2);
+			const suggestion = matches.length === 1 ? ` Use --${matches[0]}.` : "";
+			return `Unknown option ${token.rawName}.${suggestion} Run ${path} --help.`;
+		}
+		if (option.type === "string" && (token.value === void 0 || !token.inlineValue && token.value.startsWith("-"))) return `${token.rawName} requires a value. Use ${token.rawName}=VALUE.`;
+	}
+	if (hasSubCommands && positional?.kind === "positional") {
+		let selected = subCommands[positional.value];
+		if (!selected) for (const candidate of Object.values(subCommands)) {
+			const meta = await resolve((await resolve(candidate))?.meta ?? {});
+			if ((typeof meta.alias === "string" ? [meta.alias] : meta.alias ?? []).includes(positional.value)) {
+				selected = candidate;
+				break;
+			}
+		}
+		if (!selected) return `Unknown command ${positional.value}. Run ${path} --help.`;
+		const child = await resolve(selected);
+		if (child) return checkCliArgs(child, rawArgs.slice(boundary + 1), `${path} ${positional.value}`);
+	}
+}
+export { checkCliArgs };

package/dist/cli.mjs

@@ -1,5 +1,6 @@
 import { createCliRuntime, runWithCliRuntime, useCliRuntime } from "./runtime.mjs";
 import { parseAuthMode } from "./auth-state.mjs";
+import { checkCliArgs } from "./cli-args.mjs";
 import { CLI_SUBCOMMANDS } from "./command-registry.mjs";
 import { resolveCliEnvironment } from "./environment.mjs";
 import { applyProfileFromCli } from "./commands/profile-selection.mjs";
@@ -78,6 +79,8 @@ async function runCli(opts = {}) {
 		if (opts.loadEnv !== false) loadEnvFromCwd();
 		const rawArgs = prepareCliArgs(input);
 		runtime.rawArgs = [...rawArgs];
+		const argumentError = await checkCliArgs(main, rawArgs);
+		if (argumentError) throw new Error(argumentError);
 		await withConfiguredOutput(() => runMain(main, { rawArgs }));
 	});
 }

package/dist/commands/query.mjs

@@ -2,7 +2,7 @@ import { queryCommandMeta } from "../command-meta.mjs";
 import { loadConfig } from "../config.mjs";
 import { terminalOutputOptions } from "../render/terminal.mjs";
 import { ALL_SEARCH_TYPES, logger, parseSearchType, toCSV } from "../utils.mjs";
-import { allTables, inferTable } from "../local-store.mjs";
+import { allTables, inferTable, tableDimensions } from "../local-store.mjs";
 import { createCommandContext } from "../context.mjs";
 import { gscErrorHandler } from "../error-handler.mjs";
 import { renderTable } from "../render/layout.mjs";
@@ -12,6 +12,7 @@ import process from "node:process";
 import { defineCommand } from "citty";
 import fs from "node:fs/promises";
 import { and, between, contains, country, date, device, eq, gsc, hour, notRegex, page, query, regex, searchAppearance } from "gscdump/query";
+import { decodeSiteId } from "gscdump/tenant";
 import { cancel, isCancel, multiselect, text } from "@clack/prompts";
 import { daysAgoUtc } from "gscdump/dates";
 import { collectSpans } from "@gscdump/engine/profile";
@@ -279,7 +280,9 @@ const queryCommand = defineCommand({
 			needsStore: !args.live,
 			interactive: Boolean(args.interactive)
 		});
-		const siteUrl = await ctx.resolveSite(args.site ? String(args.site) : void 0);
+		const hint = args.site ? String(args.site) : ctx.config.defaultSite;
+		const exactHint = !args.live && hint && /^(?:sc-domain:\S+|https?:\/\/\S+)$/.test(hint) ? hint : void 0;
+		const siteUrl = exactHint ? await resolveLocalSite(ctx.store, exactHint) ?? await ctx.resolveSite(hint) : await ctx.resolveSite(hint);
 		if (args.live) {
 			if (args.explain) {
 				const body = {
@@ -339,7 +342,7 @@ const queryCommand = defineCommand({
 			}, null, 2));
 			return;
 		}
-		await assertRangeCovered(store, siteUrl, table, startDate, endDate, searchType);
+		await assertRangeCovered(store, siteUrl, table, startDate, endDate, format === "json", searchType);
 		const probe = Boolean(args.profile) ? collectSpans() : void 0;
 		const result = await store.engine.query({
 			userId: store.userId,
@@ -477,6 +480,14 @@ async function promptFilters(args) {
 		if (ds && String(ds).length > 0) args["data-state"] = String(ds);
 	}
 }
+async function resolveLocalSite(store, hint) {
+	const siteIds = new Set((await store.engine.getWatermarks({ userId: store.userId })).map((w) => w.siteId).filter((siteId) => siteId !== void 0));
+	const exact = store.siteIdFor(hint);
+	if (siteIds.has(exact)) return hint;
+	const lowered = exact.toLowerCase();
+	const matches = [...siteIds].filter((siteId) => siteId.toLowerCase() === lowered);
+	return matches.length === 1 ? decodeSiteId(matches[0]) : void 0;
+}
 function buildLocalState(dimNames, startDate, endDate, rowLimit, dimensionFilter) {
 	const dims = dimNames.map((d) => DIM_COLUMNS[d]).filter((c) => Boolean(c));
 	const dateFilter = between(date, startDate, endDate);
@@ -494,25 +505,70 @@ function buildDimensionFilter(args) {
 	if (leaves.length === 1) return leaves[0];
 	return and(...leaves);
 }
-async function assertRangeCovered(store, siteUrl, table, startDate, endDate, searchType) {
-	const wm = (await store.engine.getWatermarks({
+async function assertRangeCovered(store, siteUrl, table, startDate, endDate, json, searchType) {
+	const watermarks = await store.engine.getWatermarks({
 		userId: store.userId,
 		siteId: store.siteIdFor(siteUrl),
 		table,
 		...searchType !== void 0 ? { searchType } : {}
-	}))[0];
-	if (!wm) {
-		logger.error(`No data synced for ${siteUrl} / ${table}. Run \`gscdump sync\` first, or pass --live.`);
-		process.exit(1);
-	}
-	if (endDate > wm.newestDateSynced) {
-		logger.error(`Requested end=${endDate} is newer than last sync (${wm.newestDateSynced}). Run \`gscdump sync\` first, or pass --live.`);
-		process.exit(1);
+	});
+	const wm = watermarks[0];
+	const states = await store.engine.getSyncStates({
+		userId: store.userId,
+		siteId: store.siteIdFor(siteUrl),
+		table,
+		searchType: searchType ?? "web",
+		state: "done"
+	});
+	const completed = new Set(states.map((state) => state.date));
+	const missingDates = [];
+	for (let date = Date.parse(startDate); date <= Date.parse(endDate); date += 864e5) {
+		const day = new Date(date).toISOString().slice(0, 10);
+		if (!completed.has(day)) missingDates.push(day);
 	}
-	if (startDate < wm.oldestDateSynced) {
-		logger.error(`Requested start=${startDate} is older than first sync (${wm.oldestDateSynced}). Run \`gscdump sync --start=${startDate}\` first, or pass --live.`);
-		process.exit(1);
+	if (missingDates.length === 0) return;
+	const nextArgs = [
+		"sync",
+		"--site",
+		siteUrl,
+		"--start",
+		startDate,
+		"--end",
+		endDate,
+		"--tables",
+		table,
+		"--types",
+		searchType ?? "web",
+		"--json"
+	];
+	const nextCommand = `gscdump ${nextArgs.map((value) => /^[\w:./=-]+$/.test(value) ? value : `'${value.replaceAll("'", "'\\''")}'`).join(" ")}`;
+	const message = !wm ? `No data synced for ${siteUrl} / ${table}.` : `Store coverage is incomplete for ${missingDates.length} requested dates.`;
+	if (json) {
+		const available = await store.engine.getWatermarks({
+			userId: store.userId,
+			siteId: store.siteIdFor(siteUrl)
+		});
+		console.log(JSON.stringify({ error: {
+			code: "STORE_RANGE_NOT_COVERED",
+			message,
+			siteUrl,
+			table,
+			range: {
+				start: startDate,
+				end: endDate
+			},
+			missingDates,
+			watermarks: watermarks.filter((w) => w.table === table),
+			availableTables: available.map((w) => ({
+				...w,
+				dimensions: tableDimensions(w.table)
+			})),
+			nextArgs,
+			nextCommand
+		} }, null, 2));
 	}
+	logger.error(`${message} Run ${nextCommand}, or pass --live.`);
+	process.exit(1);
 }
 async function runRawSqlMode(opts) {
 	if (!isKnownTable(opts.table)) {

package/dist/commands/stats.mjs

@@ -1,6 +1,6 @@
 import { terminalOutputOptions } from "../render/terminal.mjs";
 import { OUTPUT_ARGS, applyOutputMode, displayPath, formatAge, logger } from "../utils.mjs";
-import { allTables } from "../local-store.mjs";
+import { allTables, tableDimensions } from "../local-store.mjs";
 import { createCommandContext } from "../context.mjs";
 import { renderTable, textLines } from "../render/layout.mjs";
 import { formatMetric } from "../render/metrics.mjs";
@@ -26,15 +26,11 @@ const statsCommand = defineCommand({
 		const { json } = applyOutputMode(args);
 		const store = (await createCommandContext({ needsStore: true })).store;
 		const allEntries = await store.engine.listAll({ userId: store.userId });
-		let siteId;
-		if (args.site) {
-			const known = new Set(allEntries.filter((entry) => entry.retiredAt === void 0 && entry.siteId !== void 0).map((entry) => entry.siteId));
-			const candidate = store.siteIdFor(args.site);
-			if (!known.has(candidate)) {
-				logger.error(`No local data for --site=${args.site}. Known site IDs: ${known.size === 0 ? "(none — run `gscdump sync` first)" : Array.from(known).join(", ")}`);
-				process.exit(1);
-			}
-			siteId = candidate;
+		const knownSites = [...new Set(allEntries.filter((entry) => entry.retiredAt === void 0 && entry.siteId !== void 0).map((entry) => entry.siteId))];
+		const siteId = args.site ? store.siteIdFor(args.site) : void 0;
+		if (args.site && !json && !knownSites.includes(siteId)) {
+			logger.error(`No local data for --site=${args.site}. Known site IDs: ${knownSites.length === 0 ? "(none — run `gscdump sync` first)" : knownSites.join(", ")}`);
+			process.exit(1);
 		}
 		const selectedEntries = siteId === void 0 ? allEntries : allEntries.filter((entry) => entry.siteId === siteId);
 		const perTable = allTables().map((table) => {
@@ -48,16 +44,17 @@ const statsCommand = defineCommand({
 		const [watermarks, disk] = await Promise.all([store.engine.getWatermarks({
 			userId: store.userId,
 			siteId
-		}), filesystemStats(store.dataDir).catch(() => ({
-			files: 0,
-			bytes: 0
-		}))]);
+		}), filesystemStats(store.dataDir)]);
 		if (json) {
 			const payload = {
 				dataDir: store.dataDir,
+				siteId: siteId ?? null,
+				knownSites,
+				nextCommand: `gscdump sync${args.site ? ` --site '${String(args.site).replaceAll("'", "'\\''")}'` : ""} --status --json`,
 				disk,
 				tables: perTable.map(({ table, live, retired }) => ({
 					table,
+					dimensions: tableDimensions(table),
 					liveFiles: live.length,
 					liveRows: sumRows(live),
 					liveBytes: sumBytes(live),
@@ -65,6 +62,7 @@ const statsCommand = defineCommand({
 					retiredBytes: sumBytes(retired),
 					watermarks: watermarks.filter((w) => w.table === table).map((w) => ({
 						siteId: w.siteId ?? null,
+						searchType: w.searchType ?? "web",
 						newestDateSynced: w.newestDateSynced,
 						oldestDateSynced: w.oldestDateSynced,
 						lastSyncAt: w.lastSyncAt

package/dist/commands/store.mjs

@@ -9,6 +9,7 @@ import { resetCommand, rmSiteCommand } from "./store-purge.mjs";
 import { defineCommand } from "citty";
 const storeCommand = defineCommand({
 	meta: storeCommandMeta,
+	args: statsCommand.args,
 	subCommands: {
 		"stats": statsCommand,
 		"compact": compactCommand,

package/dist/commands/sync.mjs

@@ -160,7 +160,7 @@ const syncCommand = defineCommand({
 		},
 		"start": {
 			type: "string",
-			description: "Start date (YYYY-MM-DD) for historical sync"
+			description: "Start date (YYYY-MM-DD) for backfill"
 		},
 		"end": {
 			type: "string",
@@ -191,7 +191,7 @@ const syncCommand = defineCommand({
 		},
 		"full": {
 			type: "boolean",
-			description: "Sync the last 450 days (full GSC history)"
+			description: "Backfill up to 450 days of available Search Console data"
 		},
 		...OUTPUT_ARGS,
 		"force": {
@@ -276,10 +276,6 @@ const syncCommand = defineCommand({
 			}
 			types.push(t);
 		}
-		if (types.length === 0) {
-			logger.warn(`All requested types (${requestedTypes.join(", ")}) are marked empty for this site. Pass --force-types to re-probe.`);
-			return;
-		}
 		if (skippedTypes.length > 0 && !quiet) logger.info(`Skipping ${skippedTypes.join(", ")} (marked empty for this site; pass --force-types to re-probe).`);
 		const endDate = args.end ? String(args.end) : daysAgoUtc(DEFAULT_PENDING_DAYS);
 		let startDate;
@@ -292,6 +288,32 @@ const syncCommand = defineCommand({
 			logger.error(`No dates to sync (start=${startDate}, end=${endDate})`);
 			process.exit(1);
 		}
+		const printCompletion = async (status, totals, reason, rollupError) => {
+			if (!json) return;
+			console.log(JSON.stringify({
+				status,
+				...reason ? { reason } : {},
+				siteUrl,
+				range: {
+					start: startDate,
+					end: endDate
+				},
+				tables,
+				types,
+				skippedTypes,
+				totals,
+				watermarks: await store.engine.getWatermarks({
+					userId: store.userId,
+					siteId
+				}),
+				...rollupError ? { rollupError } : {}
+			}, null, 2));
+		};
+		if (types.length === 0) {
+			if (!quiet) logger.warn(`All requested types are marked empty. Pass --force-types to check them again.`);
+			await printCompletion("skipped", {}, "empty-types");
+			return;
+		}
 		if (args["retry-failed"]) {
 			const failedSet = /* @__PURE__ */ new Set();
 			const selectedTables = new Set(tables);
@@ -303,7 +325,8 @@ const syncCommand = defineCommand({
 			for (const s of states) if (selectedTables.has(s.table) && selectedTypes.has(s.searchType ?? "web") && s.state === "failed" && s.date >= startDate && s.date <= endDate) failedSet.add(s.date);
 			dates = dates.filter((d) => failedSet.has(d));
 			if (dates.length === 0) {
-				logger.success("No failed dates in range — nothing to retry.");
+				if (!quiet) logger.success("No failed dates in range. Nothing to retry.");
+				await printCompletion("skipped", {}, "no-failed-dates");
 				return;
 			}
 			args.force = true;
@@ -416,6 +439,7 @@ const syncCommand = defineCommand({
 			}
 		}
 		const noRollups = Boolean(args["no-rollups"]);
+		let rollupError;
 		const anyRowsSynced = Object.values(totals).some((t) => t.rows > 0);
 		if (!noRollups && anyRowsSynced) {
 			if (!quiet) logger.info(`Rebuilding rollups for [${siteId}] (${DEFAULT_ROLLUPS.length} rollups)…`);
@@ -442,6 +466,7 @@ const syncCommand = defineCommand({
 				},
 				defs: DEFAULT_ROLLUPS
 			}).catch((err) => {
+				rollupError = err.message;
 				logger.warn(`Rollup rebuild failed: ${err.message}`);
 				return [];
 			});
@@ -451,7 +476,8 @@ const syncCommand = defineCommand({
 				logger.success(`Rebuilt ${results.length} rollup(s) in ${ms}ms — ${kb.toFixed(1)} KB`);
 			}
 		}
-		if (anyFailed) process.exit(1);
+		await printCompletion(anyFailed || rollupError ? "failed" : "completed", totals, void 0, rollupError);
+		if (anyFailed || rollupError) process.exit(1);
 	}
 });
 function isKnownTable(name) {

package/dist/local-store.mjs

@@ -1,7 +1,18 @@
 import { createNodeHarness } from "@gscdump/engine/node";
+import { SCHEMAS, allTables, inferTable } from "@gscdump/engine/schema";
 import { TABLE_DIMS, assembleDatesRow } from "@gscdump/engine/ingest";
-import { allTables, inferTable } from "@gscdump/engine/schema";
+function tableDimensions(table) {
+	return SCHEMAS[table].columns.map((column) => column.name === "url" ? "page" : column.name === "search_appearance" ? "searchAppearance" : column.name).filter((name) => [
+		"page",
+		"query",
+		"date",
+		"hour",
+		"country",
+		"device",
+		"searchAppearance"
+	].includes(name));
+}
 function createLocalStore(opts) {
 	return createNodeHarness(opts);
 }
-export { TABLE_DIMS, allTables, assembleDatesRow, createLocalStore, inferTable };
+export { TABLE_DIMS, allTables, assembleDatesRow, createLocalStore, inferTable, tableDimensions };

package/dist/mcp/server/index.mjs

@@ -173,11 +173,11 @@ function createGscMcpServer(options) {
 		expression: z.string()
 	});
 	const filterGroupSchema = z.object({
-		groupType: z.enum(["and"]).optional().describe("Always \"and\"; multiple groups are OR-ed together"),
+		groupType: z.enum(["and"]).optional().describe("Only \"and\" is supported; multiple groups do not implement OR"),
 		filters: z.array(dimensionFilterSchema)
 	});
 	server.registerTool("query", {
-		description: "Run a custom search analytics query. Supports dimension filters (regex/contains/equals) via dimensionFilterGroups; multiple groups are OR-ed.",
+		description: "Run a custom search analytics query with dimension filters (regex/contains/equals). Multiple filter groups do not implement OR.",
 		inputSchema: z.object({
 			siteUrl: z.string().describe("GSC property URL (e.g., sc-domain:example.com)"),
 			startDate: z.string().describe("Start date (YYYY-MM-DD)"),
@@ -194,7 +194,7 @@ function createGscMcpServer(options) {
 			type: z.enum(SearchTypes).optional().describe("Search type"),
 			dataState: z.enum(["final", "all"]).optional().describe("Data state: final (settled) or all (includes fresh)"),
 			aggregationType: z.enum(["byPage", "byProperty"]).optional().describe("Aggregation type"),
-			dimensionFilterGroups: z.array(filterGroupSchema).optional().describe("Filter groups (each \"and\"-ed internally; multiple groups are OR-ed)")
+			dimensionFilterGroups: z.array(filterGroupSchema).optional().describe("Filter groups use \"and\" internally. Multiple groups do not implement OR.")
 		}).shape
 	}, async ({ siteUrl, startDate, endDate, dimensions, rowLimit, type, dataState, aggregationType, dimensionFilterGroups }) => {
 		const result = await runMcpSearchAnalyticsQuery(await getClient(), {

package/dist/package.mjs

@@ -1,2 +1,2 @@
-var version = "3.6.1";
+var version = "3.6.3";
 export { version };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/cli",
   "type": "module",
-  "version": "3.6.1",
+  "version": "3.6.3",
   "description": "CLI for Google Search Console and Bing with hosted or local authentication, data exports, and an MCP server",
   "author": {
     "name": "Harlan Wilton",
@@ -44,15 +44,15 @@
   "dependencies": {
     "@clack/prompts": "^1.8.0",
     "@duckdb/node-api": "1.5.5-r.4",
-    "@gscdump/analysis": "^3.6.1",
-    "@gscdump/engine": "^3.6.1",
-    "@gscdump/engine-gsc-api": "^3.6.1",
-    "@gscdump/sdk": "^3.6.1",
+    "@gscdump/analysis": "^3.6.3",
+    "@gscdump/engine": "^3.6.3",
+    "@gscdump/engine-gsc-api": "^3.6.3",
+    "@gscdump/sdk": "^3.6.3",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "citty": "^0.2.2",
     "consola": "^3.4.2",
     "google-auth-library": "^11.0.2",
-    "gscdump": "^3.6.1",
+    "gscdump": "^3.6.3",
     "ofetch": "^1.5.1",
     "open": "^11.0.2",
     "sitemapd": "^0.2.2",

package/skills/gscdump/SKILL.md

@@ -7,6 +7,24 @@ description: Drive the `gscdump` CLI for Google Search Console and Bing with clo
 
 `gscdump` reads Google Search Console and Bing with hosted or local authentication.
 It keeps a local Parquet Store for Google rows. Every command has `--help`.
+For `query`, `-s` means `--site`, `-d` means `--dimensions`, and `-f` means `--format`.
+Use `--start` and `--end` for dates. `--site=SITE` also works.
+Use each option once, with either its short or long spelling.
+Example: `gscdump query --site=SITE --start=DATE --end=DATE -d page -f json`.
+
+## Start each task
+
+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. Before local queries, check coverage with `gscdump store stats --site SITE --json`.
+   Use `gscdump sync --site SITE --status --json` when you need sync-state details.
+4. Read the table dimensions and watermarks. Sync only missing tables and the requested dates, once per task.
+5. Use `sync --json`. Read its completion result before deciding what to do next. Never repeat a successful sync.
+
+If the task only asks about deletion, explain the scope and ask for consent.
+You may read Store metadata with `store stats` and `sync --status`.
+Do not query traffic, sync rows, or delete data to explain deletion.
+Call the local data directory the Store in your answer.
 
 ## Authentication mode
 
@@ -130,11 +148,14 @@ gscdump config set defaultSite sc-domain:example.com
 
 ## Output
 
-Pass `--json` on every command that supports it. `query` uses
+Pass `--json` on every command that supports it. `sync --json` includes completion, row counts, skipped dates, and failures.
+`query` uses
 `--format json` and prints rows to stdout. Progress goes to stderr, so stdout
 stays parseable. `--quiet` drops progress lines.
 
 Parse JSON. Never scrape human output.
+If the user requests JSON, return the CLI JSON unchanged. Do not replace it with a table.
+Do not rewrite rows, estimate metrics, or add manually calculated totals.
 
 ## Commands
 
@@ -172,9 +193,10 @@ The MCP server does not expose Bing tools. Use `gscdump bing` commands through t
 ## Sync before local analysis
 
 ```sh
+gscdump store stats --site sc-domain:example.com --json
 gscdump sync --site sc-domain:example.com --days 90 \
-  --tables pages,queries,page_queries,countries
-gscdump sync --site sc-domain:example.com --status
+  --tables pages,queries,page_queries,countries --json
+gscdump sync --site sc-domain:example.com --status --json
 ```
 
 - Pass an explicit `--tables` list. The default list has a known daily-totals
@@ -183,6 +205,8 @@ gscdump sync --site sc-domain:example.com --status
 - Sync skips completed dates. `--force` refreshes them. `--retry-failed`
   reruns only failed dates.
 - `--dry-run` prints the planned work without calling Google.
+- Use the user's date range. The 90-day example does not authorize a wider sync.
+- Empty Store metadata is expected before the first sync. It does not prove zero traffic.
 
 ## Query rows
 
@@ -195,8 +219,11 @@ gscdump query --site sc-domain:example.com --dimensions page,query \
 - Filters: `--query`, `--page`, `--country`, `--device`,
   `--search-appearance`. Prefixes: bare equals, `~` contains, `!~` not
   contains, `re:` regex, `!re:` not regex, `!` not equals.
-- `--live` bypasses the Store. `--search-type`, `--data-state`, and
-  `--aggregation-type` apply to live mode only.
+- `--live` bypasses the Store. `--type` selects a search type.
+  `--data-state` and `--aggregation-type` apply to live mode only.
+- Metrics already include clicks, impressions, CTR, and position. There is no `--metrics` option.
+- If Store coverage is missing, read the JSON error and its bounded `nextArgs` before syncing.
+  Do not switch dimensions to make a failed query succeed.
 - `--explain` prints the request body or planned SQL without executing.
 - `--sql` runs raw DuckDB SQL over the Store with `{{FILES}}` as the file list.
 
@@ -270,9 +297,9 @@ the failure and continue. Never retry an uncertain submission.
   delete local data. `--yes` is consent you borrow from the user.
 - **Never loop unattended.** One `sync` per Site per task. Inspection batches
   spend a daily pool. Use `--dry-run` and `--explain` to plan first.
-- **Report the result as the CLI gave it.** An empty result is not a clean
-  Site. Check `sync --status` for the covered date range before reading zero
-  rows as zero traffic.
+- **Report the result as the CLI gave it.** Zero clicks with impressions means rows exist with no clicks.
+  An empty row array means no rows matched. Missing coverage means the Store cannot answer that date range.
+  Check `sync --status --json` before interpreting empty rows. None of these results proves a clean Site.
 - **Do not widen the Site.** A `sc-domain:` property includes every
   subdomain. Filter with `--page` when the user means one host.
 
@@ -285,3 +312,14 @@ Hosted exports follow pagination and reject missing, unavailable, or changing da
 Hosted date ranges span at most 366 days. The default range is the last 366 days.
 Local date filters only narrow data currently returned by Bing.
 Do not treat Bing crawl evidence as proof that a URL is indexed.
+
+## Before the next command
+
+For a traffic task, run `gscdump auth status --json` now, before any `query` command.
+The user saying credentials work does not replace this check. It identifies the selected authentication mode.
+Then check Store metadata, keep the requested dimensions, and read or sync only the requested dates.
+If the user requests JSON, return the command's JSON unchanged, without a table or a separate totals summary.
+Include that JSON in your final response. Tool output alone is not a final answer.
+Include every returned row. Do not refer the user to results "above".
+
+For a deletion explanation, read metadata only if needed. Explain the scope and ask for consent, then stop.