@gscdump/cli 4.4.0 → 4.6.0

package/dist/commands/analyze.mjs

@@ -7,7 +7,7 @@ import { coverageWarning, renderAnalysis } from "../render/analysis.mjs";
 import { defineCommand } from "citty";
 import { DEFAULT_FETCH_BUDGET, MAX_FETCH_BUDGET } from "@gscdump/engine/analysis-types";
 import { unwrapResult } from "gscdump/result";
-import { MOVERS_SORT_METRICS } from "@gscdump/analysis";
+import { MOVERS_SORT_METRICS, TRAJECTORY_DEFAULT_DAYS } from "@gscdump/analysis";
 import { defaultAnalyzerRegistry } from "@gscdump/analysis/registry";
 const ANALYSIS_TOOLS = defaultAnalyzerRegistry.listAnalyzerIds();
 const COMPARISON_ARGS = {
@@ -85,6 +85,16 @@ function buildParams(tool, args) {
 }
 function withWindow(tool, params, args, anchor) {
 	const optional = (key) => args[key] ? String(args[key]) : void 0;
+	if (tool === "trajectory" && !optional("period") && !optional("start")) {
+		const endDate = optional("end") ?? anchor;
+		if (!/^\d{4}-\d{2}-\d{2}$/.test(endDate) || Number.isNaN(Date.parse(`${endDate}T00:00:00Z`))) throw new Error(`Invalid --end "${endDate}". Use YYYY-MM-DD.`);
+		const start = /* @__PURE__ */ new Date(Date.parse(`${endDate}T00:00:00Z`) - (TRAJECTORY_DEFAULT_DAYS - 1) * 864e5);
+		return {
+			...params,
+			startDate: start.toISOString().slice(0, 10),
+			endDate
+		};
+	}
 	const window = unwrapResult(parseWindowFlags({
 		period: optional("period"),
 		start: optional("start"),

package/dist/commands/auth.mjs

@@ -37,6 +37,8 @@ const HOSTED_COMMANDS = [
 	"sitemaps lastmod",
 	"sitemaps export",
 	"indexing urls",
+	"indexing summary",
+	"indexing watch",
 	"bing login",
 	"bing sites",
 	"bing status",

package/dist/commands/indexing-summary.mjs

@@ -0,0 +1,120 @@
+import { terminalOutputOptions } from "../render/terminal.mjs";
+import { applyOutputMode, logger, parseIntegerOption } from "../utils.mjs";
+import { renderTable } from "../render/layout.mjs";
+import { HOSTED_ARGS, resolveHostedSite } from "../hosted-site.mjs";
+import { defineCommand } from "citty";
+import { COVERAGE_LADDER } from "@gscdump/contracts";
+const MAX_DAYS = 90;
+function ladderRow(point) {
+	const states = point.coverageStates;
+	if (!states || states._tag === "not_counted") return {
+		date: point.date,
+		unknown_to_google: "not counted",
+		discovered_not_indexed: "",
+		crawled_not_indexed: "",
+		indexed: "",
+		capturedAt: ""
+	};
+	return {
+		date: point.date,
+		...Object.fromEntries(COVERAGE_LADDER.map((tag) => [tag, states.counts[tag]])),
+		capturedAt: states.capturedAt.slice(0, 16).replace("T", " ")
+	};
+}
+function captureLines(capture) {
+	if (!capture) return ["This host does not report when it counted the verdicts."];
+	if (capture._tag === "empty") return ["No URL Inspection verdicts are stored for this Site."];
+	const scope = {
+		sitemap_members: "URLs in the Site's live sitemaps",
+		inspected_urls: "every inspected URL, because sitemap membership was not available",
+		unrecorded: "an unrecorded scope"
+	}[capture.scope];
+	const lines = [
+		`Counted ${capture.capturedAt} from stored URL Inspection verdicts (${capture.source}).`,
+		`The counts cover ${scope}.`,
+		`Verdicts inspected between ${capture.oldestVerdictAt ?? "unknown"} and ${capture.newestVerdictAt ?? "unknown"}.`
+	];
+	if (capture.freshness._tag === "measured") {
+		const { verdicts, olderThan7dPercent, olderThan30dPercent } = capture.freshness;
+		lines.push(`Of ${verdicts} verdicts, ${olderThan7dPercent}% are older than 7 days and ${olderThan30dPercent}% are older than 30 days.`);
+	}
+	return lines;
+}
+const indexingSummaryCommand = defineCommand({
+	meta: {
+		name: "summary",
+		description: "Show the coverage ladder per day from stored URL Inspection verdicts, with capture time (hosted)"
+	},
+	args: {
+		...HOSTED_ARGS,
+		days: {
+			type: "string",
+			default: "28",
+			description: `Trend days, 1 to ${MAX_DAYS}`
+		},
+		json: {
+			type: "boolean",
+			default: false,
+			description: "Output as JSON"
+		},
+		quiet: {
+			type: "boolean",
+			alias: "q",
+			default: false,
+			description: "Suppress info output"
+		}
+	},
+	async run({ args }) {
+		const days = parseIntegerOption(args.days, "--days") ?? 28;
+		if (days < 1 || days > MAX_DAYS) throw new Error(`--days must be between 1 and ${MAX_DAYS}.`);
+		const { json } = applyOutputMode(args);
+		const { client, site } = await resolveHostedSite(args, {
+			name: "indexing summary",
+			localAlternative: "run `gscdump inspect --site <site>` and read the saved results with `gscdump entities`"
+		});
+		const { data } = await client.getSiteIndexing({
+			params: { siteId: site.siteId },
+			query: { days }
+		});
+		if (json) {
+			console.log(JSON.stringify(data, null, 2));
+			return;
+		}
+		const options = terminalOutputOptions();
+		if (data.trend.length === 0) logger.info(`No daily coverage counts are stored for ${site.siteUrl}.`);
+		else for (const line of renderTable(data.trend.map(ladderRow), [
+			{
+				key: "date",
+				label: "Date",
+				numeric: true
+			},
+			{
+				key: "unknown_to_google",
+				label: "Unknown",
+				numeric: true
+			},
+			{
+				key: "discovered_not_indexed",
+				label: "Discovered",
+				numeric: true
+			},
+			{
+				key: "crawled_not_indexed",
+				label: "Crawled",
+				numeric: true
+			},
+			{
+				key: "indexed",
+				label: "Indexed",
+				numeric: true
+			},
+			{
+				key: "capturedAt",
+				label: "Counted (UTC)"
+			}
+		], options)) console.log(line);
+		for (const line of captureLines(data.capture)) console.log(line);
+		logger.info("These counts are stored URL Inspection verdicts. They are not Google's live index or the Search Console Page indexing report.");
+	}
+});
+export { indexingSummaryCommand };

package/dist/commands/indexing-watch.mjs

@@ -0,0 +1,196 @@
+import { terminalOutputOptions } from "../render/terminal.mjs";
+import { applyOutputMode, logger, readUrlList } from "../utils.mjs";
+import { renderTable } from "../render/layout.mjs";
+import { HOSTED_ARGS, resolveHostedSite } from "../hosted-site.mjs";
+import { defineCommand } from "citty";
+import { WATCHED_URL_LIMIT } from "@gscdump/contracts";
+const OUTPUT = {
+	json: {
+		type: "boolean",
+		default: false,
+		description: "Output as JSON"
+	},
+	quiet: {
+		type: "boolean",
+		alias: "q",
+		default: false,
+		description: "Suppress info output"
+	}
+};
+const URL_ARGS = {
+	urls: {
+		type: "positional",
+		required: false,
+		description: "URLs on the Site host (or use --file or stdin)"
+	},
+	file: {
+		type: "string",
+		alias: "f",
+		description: "File with URLs (one per line)"
+	}
+};
+const LOCAL_ALTERNATIVE = "run `gscdump inspect --site <site> <url...>` on your own schedule";
+function watchedRow(entry) {
+	const latest = entry.checkpoints[0];
+	return {
+		url: entry.url,
+		coverageState: latest?.coverageState ?? "awaiting inspection",
+		checkedAt: latest?.checkedAt.slice(0, 10) ?? "never",
+		dueAt: entry.dueAt.slice(0, 10)
+	};
+}
+const SKIP_HINTS = { inspection_disabled: "gscdump never inspects this Site, so a Watched URL gets no Checkpoint. To use Watched URLs, turn on URL Inspection in the Site settings on gscdump.com." };
+function printChange(verb, result, siteUrl) {
+	for (const url of result.changed) console.log(`${verb}: ${url}`);
+	for (const url of result.unchanged) console.log(`${verb === "Added" ? "Already watched" : "Not watched"}: ${url}`);
+	for (const { url, reason } of result.skipped) console.log(`Skipped (${reason}): ${url}`);
+	for (const hint of new Set(result.skipped.map(({ reason }) => SKIP_HINTS[reason]).filter(Boolean))) console.log(hint);
+	logger.info(`${siteUrl} has ${result.total} of ${result.limit} Watched URLs.`);
+}
+async function readUrls(args) {
+	const urls = await readUrlList({
+		file: args.file,
+		positionals: args._
+	});
+	if (urls.length === 0) throw new Error("No URLs provided. Pass URLs as arguments, --file, or stdin.");
+	const relative = urls.find((url) => !URL.canParse(url));
+	if (relative) throw new Error(`Not an absolute URL: ${relative}. Pass full URLs such as https://example.com/guide.`);
+	return [...new Set(urls)];
+}
+async function changeInChunks(urls, send) {
+	const merged = {
+		changed: [],
+		unchanged: [],
+		skipped: [],
+		total: 0,
+		limit: WATCHED_URL_LIMIT
+	};
+	for (let start = 0; start < urls.length; start += WATCHED_URL_LIMIT) {
+		const result = await send(urls.slice(start, start + WATCHED_URL_LIMIT));
+		merged.changed.push(...result.changed);
+		merged.unchanged.push(...result.unchanged);
+		merged.skipped.push(...result.skipped);
+		merged.total = result.total;
+		merged.limit = result.limit;
+	}
+	return merged;
+}
+const listCommand = defineCommand({
+	meta: {
+		name: "list",
+		description: "List Watched URLs with the latest Checkpoint of each (hosted)"
+	},
+	args: {
+		...HOSTED_ARGS,
+		...OUTPUT
+	},
+	async run({ args }) {
+		const { json } = applyOutputMode(args);
+		const { client, site } = await resolveHostedSite(args, {
+			name: "indexing watch list",
+			localAlternative: LOCAL_ALTERNATIVE
+		});
+		const { data } = await client.listSiteWatchedUrls({ params: { siteId: site.siteId } });
+		if (json) {
+			console.log(JSON.stringify(data, null, 2));
+			return;
+		}
+		if (data.watched.length === 0) {
+			logger.info(`${site.siteUrl} has no Watched URLs.`);
+			return;
+		}
+		for (const line of renderTable(data.watched.map(watchedRow), [
+			{
+				key: "url",
+				label: "URL"
+			},
+			{
+				key: "coverageState",
+				label: "Coverage state"
+			},
+			{
+				key: "checkedAt",
+				label: "Checked"
+			},
+			{
+				key: "dueAt",
+				label: "Due"
+			}
+		], terminalOutputOptions())) console.log(line);
+		logger.info(`${data.watched.length} of ${data.limit} Watched URLs. gscdump inspects each one every ${data.cadenceDays} days.`);
+	}
+});
+const addCommand = defineCommand({
+	meta: {
+		name: "add",
+		description: "Add Watched URLs, inspected every 7 days before other URLs (hosted; spends URL Inspections)"
+	},
+	args: {
+		...HOSTED_ARGS,
+		...URL_ARGS,
+		...OUTPUT
+	},
+	async run({ args }) {
+		const { json } = applyOutputMode(args);
+		const urls = await readUrls(args);
+		const { client, site } = await resolveHostedSite({
+			...args,
+			_: []
+		}, {
+			name: "indexing watch add",
+			localAlternative: LOCAL_ALTERNATIVE
+		});
+		const data = await changeInChunks(urls, async (chunk) => (await client.addSiteWatchedUrls({
+			params: { siteId: site.siteId },
+			body: { urls: chunk }
+		})).data);
+		if (json) {
+			console.log(JSON.stringify(data, null, 2));
+			return;
+		}
+		printChange("Added", data, site.siteUrl);
+	}
+});
+const removeCommand = defineCommand({
+	meta: {
+		name: "remove",
+		description: "Remove Watched URLs and their Checkpoints (hosted)"
+	},
+	args: {
+		...HOSTED_ARGS,
+		...URL_ARGS,
+		...OUTPUT
+	},
+	async run({ args }) {
+		const { json } = applyOutputMode(args);
+		const urls = await readUrls(args);
+		const { client, site } = await resolveHostedSite({
+			...args,
+			_: []
+		}, {
+			name: "indexing watch remove",
+			localAlternative: LOCAL_ALTERNATIVE
+		});
+		const data = await changeInChunks(urls, async (chunk) => (await client.removeSiteWatchedUrls({
+			params: { siteId: site.siteId },
+			body: { urls: chunk }
+		})).data);
+		if (json) {
+			console.log(JSON.stringify(data, null, 2));
+			return;
+		}
+		printChange("Removed", data, site.siteUrl);
+	}
+});
+const indexingWatchCommand = defineCommand({
+	meta: {
+		name: "watch",
+		description: "Manage Watched URLs: a Site's URLs inspected on a fixed 7 day cadence (hosted)"
+	},
+	subCommands: {
+		list: listCommand,
+		add: addCommand,
+		remove: removeCommand
+	}
+});
+export { indexingWatchCommand };

package/dist/commands/indexing.mjs

@@ -2,7 +2,9 @@ import { indexingCommandMeta } from "../command-meta.mjs";
 import { OUTPUT_ARGS, applyOutputMode, logger, parseIntegerOption, readUrlList } from "../utils.mjs";
 import { createCommandContext } from "../context.mjs";
 import { loadSitemapUrls } from "../sitemap.mjs";
+import { indexingSummaryCommand } from "./indexing-summary.mjs";
 import { indexingUrlsCommand } from "./indexing-urls.mjs";
+import { indexingWatchCommand } from "./indexing-watch.mjs";
 import process from "node:process";
 import { defineCommand } from "citty";
 import { batchRequestIndexing, getIndexingMetadata, requestIndexing, runSequentialBatch } from "gscdump/indexing";
@@ -318,7 +320,9 @@ const indexingCommand = defineCommand({
 		"batch": batchCommand,
 		"batch-status": batchStatusCommand,
 		"quota": quotaCommand,
-		"urls": indexingUrlsCommand
+		"urls": indexingUrlsCommand,
+		"summary": indexingSummaryCommand,
+		"watch": indexingWatchCommand
 	}
 });
 export { indexingCommand };

package/dist/package.mjs

@@ -1,2 +1,2 @@
-var version = "4.4.0";
+var version = "4.6.0";
 export { version };

package/dist/render/analysis.mjs

@@ -29,6 +29,28 @@ function coverageWarning(coverage) {
 	if (coverage?.kind !== "truncated") return void 0;
 	return `! Partial data: a fetch stopped at ${coverage.fetched.toLocaleString("en-US")} rows. To read more rows, pass --fetch-budget (max ${MAX_FETCH_BUDGET}).`;
 }
+function renderTrajectory(result, options) {
+	const window = (value) => {
+		const w = asRecord(value);
+		return w.startDate === void 0 ? "n/a" : `${w.startDate} to ${w.endDate}: ${formatMetric("clicks", finite(w.clicks) ?? 0)} clicks, ${formatMetric("impressions", finite(w.impressions) ?? 0)} impressions`;
+	};
+	const classification = asRecord(result.classification);
+	const basis = asRecord(result.basis);
+	const ratio = finite(result.latestToPeakRatio);
+	const lines = [
+		`Shape: ${String(classification._tag)}`,
+		`First data: ${String(result.firstDataDate ?? "n/a")}`,
+		`Peak 7 days: ${window(result.peak)}`,
+		`Latest 7 days: ${window(result.latest)}`,
+		`Latest to peak (${String(basis._tag)}): ${ratio === null ? "n/a" : `${(ratio * 100).toFixed(1)}%`}`,
+		...typeof basis.note === "string" ? [basis.note] : []
+	];
+	for (const caveat of Array.isArray(result.caveats) ? result.caveats : []) {
+		const note = asRecord(caveat).note;
+		if (typeof note === "string") lines.push(`! ${note}`);
+	}
+	return lines.flatMap((line) => textLines(line, options));
+}
 function renderAnalysis(result, context, options) {
 	const rows = result.results;
 	const meta = result.meta;
@@ -97,7 +119,8 @@ function renderAnalysis(result, context, options) {
 		})), context.metric ?? "clicks", options));
 		if (meta.insufficientData === true || values.size < 12) lines.push(...textLines(`! ${values.size} of 12 months`, options, "warning"));
 		if (months.some((month) => partial.has(month))) lines.push(...textLines("* partial month", options, "muted"));
-	} else lines.push(...renderTable(rows, columnsFor(rows), options));
+	} else if (context.id === "trajectory") lines.push(...renderTrajectory(asRecord(rows[0]), options));
+	else lines.push(...renderTable(rows, columnsFor(rows), options));
 	const total = finite(meta.total);
 	if (total !== null && total > rows.length) lines.push("", ...textLines(`${rows.length} of ${formatMetric("clicks", total)} rows`, options, "muted"));
 	return lines.join("\n");

package/dist/utils.mjs

@@ -178,7 +178,7 @@ function toCSV(data, columns) {
 	return [columns.join(","), ...data.map((row) => columns.map((col) => {
 		const val = row[col];
 		if (val === null || val === void 0) return "";
-		const str = String(val);
+		const str = typeof val === "object" ? JSON.stringify(val) : String(val);
 		return str.includes(",") || str.includes("\"") || str.includes("\n") ? `"${str.replace(/"/g, "\"\"")}"` : str;
 	}).join(","))].join("\n");
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gscdump/cli",
   "type": "module",
-  "version": "4.4.0",
+  "version": "4.6.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": "^4.4.0",
-    "@gscdump/contracts": "^4.4.0",
-    "@gscdump/engine": "^4.4.0",
-    "@gscdump/engine-gsc-api": "^4.4.0",
-    "@gscdump/sdk": "^4.4.0",
+    "@gscdump/analysis": "^4.6.0",
+    "@gscdump/contracts": "^4.6.0",
+    "@gscdump/engine": "^4.6.0",
+    "@gscdump/engine-gsc-api": "^4.6.0",
+    "@gscdump/sdk": "^4.6.0",
     "@modelcontextprotocol/sdk": "^1.30.1",
     "citty": "^0.2.2",
     "consola": "^3.4.2",
     "google-auth-library": "^11.1.0",
-    "gscdump": "^4.4.0",
+    "gscdump": "^4.6.0",
     "ofetch": "^1.5.1",
     "open": "^11.0.4",
     "proper-lockfile": "^4.1.2",

package/skills/gscdump/SKILL.md

@@ -67,7 +67,8 @@ gscdump query --site example.com -d page -f json
 ```
 
 Hosted mode can run only these commands: `sites`, `query`, `sitemaps current`, `sitemaps history`, `sitemaps membership`,
-`sitemaps lastmod`, `sitemaps export`, `indexing urls`, and the `bing` commands `login --site`, `sites`, `status`, `dump`, `inspect`, and `verify`.
+`sitemaps lastmod`, `sitemaps export`, `indexing urls`, `indexing summary`, `indexing watch list|add|remove`,
+and the `bing` commands `login --site`, `sites`, `status`, `dump`, `inspect`, and `verify`.
 Every other command calls Google, so it needs Local mode: `sync`, `inspect`, `query --live`, `analyze --live`, `report --live`,
 `sites add|get|delete|verify*`, `sitemaps list|get|submit|delete`, `indexing submit|remove|status|batch`, `entities`, and `mcp`.
 In Hosted mode these commands stop with this error: `This command calls Google, so it needs Local mode.`
@@ -93,7 +94,7 @@ gscdump bing dump --site https://example.com/ --out ./bing-export
 
 Hosted Bing commands use the API's access rules.
 Hosted connection verification uses `bing verify --site s_SITE_ID`.
-Hosted sitemap reads and `indexing urls` need Hosted mode. Their `--site` takes a Site URL, such as `example.com`.
+Hosted sitemap reads and the hosted `indexing` commands need Hosted mode. Their `--site` takes a Site URL, such as `example.com`.
 
 ## Data boundaries
 
@@ -236,6 +237,8 @@ Do not rewrite rows, estimate metrics, or add manually calculated totals.
 | `gscdump inspect <url...>` | URL Inspection with Indexing Evidence, saved to the Store |
 | `gscdump sitemaps` | List, submit, delete, and probe sitemaps |
 | `gscdump indexing` | Indexing API notifications and quota; hosted URL Inspection results |
+| `gscdump indexing summary` | Hosted: the coverage ladder per day, with the time gscdump counted the verdicts |
+| `gscdump indexing watch` | Hosted: list, add, and remove Watched URLs and read their Checkpoints |
 | `gscdump dump` | Export Store tables, inspections, sitemaps, and Bing data as Parquet, CSV, JSON, NDJSON, SQLite, or DuckDB |
 | `gscdump store` | Store stats, compaction, garbage collection, resets |
 | `gscdump entities` | Read saved inspections; snapshot Indexing API metadata |
@@ -393,6 +396,10 @@ gscdump analyze striking-distance --site example.com --json
 - SQL-only Analyzers need Store rows. `--live` runs row-based Analyzers
   against Google.
 - Results name candidates for review. They do not prove why traffic changed.
+- On a traffic collapse, run `gscdump analyze trajectory --site example.com --json` first. It reads the whole
+  record, 486 days by default. Quote `classification._tag`, such as `launch-honeymoon-then-cliff` or `sudden-drop`,
+  with its dates, and quote `basis`. `basis._tag` is `clicks` when impressions cannot carry the read, for example
+  when the peak falls in the period Search Console over-counted impressions, which ended 2026-04-27.
 
 ## Inspect and index
 
@@ -421,6 +428,66 @@ gscdump indexing urls --site example.com --status not_indexed --all --format csv
 - Pages hold 100 rows by default and 500 at most. Use `--offset` for the next page, or `--all` for every page.
 - With local authentication, the command fails. Pipe `gscdump sitemaps urls <sitemap-url>` into `gscdump inspect --site <site>` instead.
 
+## Read the coverage ladder (hosted)
+
+```sh
+gscdump indexing summary --site example.com --json
+gscdump indexing summary --site example.com --days 90 --json
+```
+
+The command reads saved URL Inspection verdicts. It spends no inspection quota.
+Each day in `trend` has `coverageStates`:
+
+- `counted` has `counts`, one URL count per coverage state, and `capturedAt`, the time gscdump counted them.
+- `not_counted` means gscdump stored the day before it counted coverage states. That day has no ladder. Say so.
+
+Read the 4 ladder states in `counts`, lowest rung first. Name each state with these words:
+
+| Key | Name | Meaning |
+| --- | --- | --- |
+| `unknown_to_google` | unknown | Google has no record of the URL |
+| `discovered_not_indexed` | discovered | Google queued the URL and has not crawled it |
+| `crawled_not_indexed` | crawled | Google crawled the URL and left it out of the index |
+| `indexed` | indexed | Google indexed the URL |
+
+The other keys in `counts` are exclusions, such as `noindex`, `not_found`, and `redirect`.
+`unrecognized` counts coverage text gscdump cannot map yet. `not_reported` counts results with no coverage text.
+A newer host can add keys to `counts`. Treat a key you do not know as its own state. Treat a missing key as 0.
+
+Rules for every answer:
+
+- `capture.source` is `stored` for counts gscdump saved on its daily run, and `live` for counts made during the request.
+- Quote `capturedAt` with every count. Also quote `capture.oldestVerdictAt` and the `capture.freshness` percents: `olderThan7dPercent` and `olderThan30dPercent`.
+- If `capture._tag` is `empty`, gscdump holds no verdicts for the Site. Report no ladder.
+- The counts are stored URL Inspection verdicts. They are not Google's live index.
+  They are also not the Search Console Page indexing report. The two can differ a lot, and the Page indexing report can list many more URLs.
+- `olderThan7d` and `olderThan30d` count verdicts inspected more than 7 times 24 hours and 30 times 24 hours before `capturedAt`. They are not calendar days.
+- A verdict can be months older than its capture. Unchanged URLs are rechecked less often over time. Say when most verdicts are old.
+- A move between rungs shows in the trend. Compare two `counted` days and name the dates.
+- `capture.scope` says which URLs the counts cover. `sitemap_members` means every counted URL is in a live sitemap.
+  `inspected_urls` means sitemap membership was not available, so the counts can include URLs outside every sitemap.
+- If `unknown_to_google` URLs are already in a sitemap, the sitemap is not the gap. Do not tell the owner to add them to it.
+  Read the sitemap's last download with `gscdump sitemaps current --site SITE --json`. If Google downloaded it, say that Google read the sitemap and did not take the URLs.
+  Check one URL's membership with `gscdump sitemaps membership`.
+- Name no cause beyond what the evidence shows.
+- Cite the command behind each number.
+
+## Watch URLs (hosted)
+
+```sh
+gscdump indexing watch add --site example.com https://example.com/guide https://example.com/pricing
+gscdump indexing watch list --site example.com --json
+gscdump indexing watch remove --site example.com https://example.com/pricing
+```
+
+- A Site can hold 50 Watched URLs. `add` and `remove` send 50 URLs per request, so a longer list works. Every URL must be absolute. `add` fails before any request if one is relative.
+- If `add` skips a URL with `inspection_disabled`, the Site has URL Inspection off. gscdump never inspects it, so the URL gets no Checkpoint. Tell the owner to turn on URL Inspection in the Site settings.
+- gscdump inspects each Watched URL every 7 days, before other scheduled URLs. It never backs off.
+- Each scheduled inspection spends the Site's daily URL Inspection budget and the URL Inspections meter. Get consent before `add`.
+- Each scheduled inspection stores one Checkpoint. `watch list --json` returns Checkpoints newest first, with `checkedAt`, the `coverageState` key, and Google's text.
+- Compare Checkpoints by date to see when a URL moves up the ladder. A new Watched URL has no Checkpoint until its first inspection.
+- `remove` deletes the URL's Checkpoints. The saved URL Inspection results stay.
+
 ## Report a papercut
 
 If CLI behavior blocks or slows your work, report it once per distinct
@@ -453,7 +520,9 @@ the failure and continue. Never retry an uncertain submission.
 - **Get consent before a mutation.** `sites add`, `sites delete`,
   `sites verify`, `sitemaps submit`, `sitemaps delete`, `indexing submit`,
   `indexing remove`, `store reset`, and `store rm-site` change Google or
-  delete local data. `--yes` is consent you borrow from the user.
+  delete local data. `indexing watch add` spends URL Inspections every week,
+  and `indexing watch remove` deletes Checkpoints. `--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.** Zero clicks with impressions means rows exist with no clicks.