@gscdump/cli 6.0.0 → 7.0.0

package/dist/auth-state.mjs

@@ -9,7 +9,7 @@ const HOSTED_SESSION_REJECTED = "gscdump.com rejected the CLI session. Run `gscd
 const HOSTED_KEY_REJECTED = "gscdump.com rejected the API key. Run `gscdump auth login --mode hosted --api-key KEY` with a valid key.";
 const LOCAL_MODE_REQUIRED = [
 	"This command calls Google, so it needs Local mode.",
-	"Hosted mode reads your gscdump.com record and never calls Google.",
+	"This command needs your own Google credentials. Hosted inspections use the platform separately.",
 	"If you want Local mode, run `gscdump auth login --mode local`."
 ].join("\n");
 function localModeRequired(detail) {

package/dist/command-meta.mjs

@@ -28,7 +28,7 @@ const storeCommandMeta = {
 };
 const inspectCommandMeta = {
 	name: "inspect",
-	description: "Inspect the indexing status of one or more URLs and save the results to the Store"
+	description: "Read Google URL Inspection results and save them to the Store"
 };
 const indexingCommandMeta = {
 	name: "indexing",
@@ -36,7 +36,7 @@ const indexingCommandMeta = {
 };
 const entitiesCommandMeta = {
 	name: "entities",
-	description: "Manage local entity snapshots (URL inspections and indexing metadata)"
+	description: "Read saved URL inspections and save Google Indexing API metadata"
 };
 const analyzeCommandMeta = {
 	name: "analyze",
@@ -44,7 +44,7 @@ const analyzeCommandMeta = {
 };
 const reportCommandMeta = {
 	name: "report",
-	description: "Run an intent-keyed report (composes analyzers into bounded sections)"
+	description: "Run a Report to find traffic changes, SEO opportunities, and risks"
 };
 const authCommandMeta = {
 	status: {

package/dist/commands/analyze.mjs

@@ -3,7 +3,7 @@ import { terminalOutputOptions } from "../render/terminal.mjs";
 import { logger, parseFetchBudget, parseIntegerOption, setJsonOutput, toCSV } from "../utils.mjs";
 import { DEFAULT_WINDOW, PERIOD_FLAGS, parseWindowFlags, windowFlagErrorToException } from "../window.mjs";
 import { analysisNeeds, analyzerTables, resolveAnalysisSource } from "../analysis-local.mjs";
-import { coverageWarning, renderAnalysis } from "../render/analysis.mjs";
+import { ANALYZER_DISPLAY, 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";
@@ -120,7 +120,7 @@ function makeToolCommand(tool) {
 	return defineCommand({
 		meta: {
 			name: tool,
-			description: `Run ${tool} analysis`
+			description: ANALYZER_DISPLAY[tool]?.description ?? `Run ${tool} analysis`
 		},
 		args: {
 			"site": {
@@ -228,7 +228,7 @@ const listCommand = defineCommand({
 			console.log(JSON.stringify(ANALYSIS_TOOLS, null, 2));
 			return;
 		}
-		for (const id of ANALYSIS_TOOLS) console.log(id);
+		for (const id of ANALYSIS_TOOLS) console.log(ANALYZER_DISPLAY[id] ? `${id}: ${ANALYZER_DISPLAY[id].description}` : id);
 	}
 });
 const analyzeCommand = defineCommand({

package/dist/commands/entities.mjs

@@ -31,7 +31,7 @@ async function readUrlList(opts) {
 const showSubCommand = defineCommand({
 	meta: {
 		name: "show",
-		description: "Print the latest inspection record for a URL from the local entity store"
+		description: "Read the latest saved URL inspection from the Store"
 	},
 	args: {
 		...OUTPUT_ARGS,
@@ -74,7 +74,7 @@ const showSubCommand = defineCommand({
 const indexingSnapshotSubCommand = defineCommand({
 	meta: {
 		name: "snapshot",
-		description: "Fetch Indexing API metadata (latest update/remove per URL) and persist to the local entity store"
+		description: "Save the latest Google Indexing API update and removal notification times for each URL to the Store"
 	},
 	args: {
 		site: {
@@ -155,7 +155,7 @@ const indexingSnapshotSubCommand = defineCommand({
 const indexingSubCommand = defineCommand({
 	meta: {
 		name: "indexing",
-		description: "Snapshot Indexing API metadata per URL"
+		description: "Save Google Indexing API notification times for URLs"
 	},
 	subCommands: { snapshot: indexingSnapshotSubCommand }
 });

package/dist/commands/gc.mjs

@@ -5,13 +5,13 @@ const DEFAULT_GRACE_HOURS = 24;
 const gcCommand = defineCommand({
 	meta: {
 		name: "gc",
-		description: "Delete orphaned object-store files not referenced by any manifest entry"
+		description: "Delete retired and unreferenced files; expire hourly files created over 90 days ago"
 	},
 	args: {
 		"grace-hours": {
 			type: "string",
 			default: String(DEFAULT_GRACE_HOURS),
-			description: `Spare orphans younger than this (default: ${DEFAULT_GRACE_HOURS}h)`
+			description: `Grace period in hours for retired and unreferenced files (default: ${DEFAULT_GRACE_HOURS}h)`
 		},
 		"site": {
 			type: "string",
@@ -21,7 +21,7 @@ const gcCommand = defineCommand({
 		"dry-run": {
 			type: "boolean",
 			default: false,
-			description: "List retired manifest entries past the grace window without deleting"
+			description: "Preview retired entries only; excludes expired hourly files and unreferenced files"
 		},
 		...OUTPUT_ARGS
 	},
@@ -55,7 +55,8 @@ const gcCommand = defineCommand({
 			console.log();
 			for (const c of candidates) console.log(`  ${c.objectKey}  \x1B[90m(retired ${new Date(c.retiredAt).toISOString()})\x1B[0m`);
 			console.log();
-			logger.info(`gc --dry-run: ${candidates.length} retired manifest entry(ies) past ${args["grace-hours"]}h grace; pass without --dry-run to delete`);
+			logger.info(`gc --dry-run: ${candidates.length} retired manifest entry(ies) past ${args["grace-hours"]}h grace.`);
+			logger.warn("This preview excludes expired hourly files and unreferenced files. The deletion run also removes those files.");
 			return;
 		}
 		const result = await store.engine.gcOrphans({
@@ -69,7 +70,7 @@ const gcCommand = defineCommand({
 			}, null, 2));
 			return;
 		}
-		logger.success(`gc: deleted ${result.deleted} orphan file(s)`);
+		logger.success(`gc: deleted ${result.deleted} retired, expired hourly, or unreferenced file(s)`);
 	}
 });
 export { gcCommand };

package/dist/commands/indexing-summary.mjs

@@ -30,7 +30,7 @@ function captureLines(capture) {
 		unrecorded: "an unrecorded scope"
 	}[capture.scope];
 	const lines = [
-		`Counted ${capture.capturedAt} from stored URL Inspection verdicts (${capture.source}).`,
+		`${capture.source === "live" ? "Counted during this request" : "Saved daily count"} at ${capture.capturedAt}, from stored URL Inspection verdicts.`,
 		`The counts cover ${scope}.`,
 		`Verdicts inspected between ${capture.oldestVerdictAt ?? "unknown"} and ${capture.newestVerdictAt ?? "unknown"}.`
 	];
@@ -95,12 +95,12 @@ const indexingSummaryCommand = defineCommand({
 			},
 			{
 				key: "discovered_not_indexed",
-				label: "Discovered",
+				label: "Discovered, not indexed",
 				numeric: true
 			},
 			{
 				key: "crawled_not_indexed",
-				label: "Crawled",
+				label: "Crawled, not indexed",
 				numeric: true
 			},
 			{

package/dist/commands/indexing-watch.mjs

@@ -41,7 +41,7 @@ function watchedRow(entry) {
 	};
 }
 function skipHint(reason, manager) {
-	return reason === "inspection_disabled" ? `gscdump never inspects this Site, so a Watched URL gets no Checkpoint. To use Watched URLs, turn on URL Inspection ${siteSettingsPlace(manager)}.` : void 0;
+	return reason === "inspection_disabled" ? `gscdump never inspects this Site, so a Watched URL gets no Watched URL inspection. To use Watched URLs, turn on URL Inspection ${siteSettingsPlace(manager)}.` : void 0;
 }
 function printChange(verb, result, siteUrl, manager) {
 	for (const url of result.changed) console.log(`${verb}: ${url}`);
@@ -81,7 +81,7 @@ async function changeInChunks(urls, send) {
 const listCommand = defineCommand({
 	meta: {
 		name: "list",
-		description: "List Watched URLs with the latest Checkpoint of each (hosted)"
+		description: "List Watched URLs with the latest Watched URL inspection of each (hosted)"
 	},
 	args: {
 		...HOSTED_ARGS,
@@ -157,7 +157,7 @@ const addCommand = defineCommand({
 const removeCommand = defineCommand({
 	meta: {
 		name: "remove",
-		description: "Remove Watched URLs and their Checkpoints (hosted)"
+		description: "Remove Watched URLs and their Watched URL inspections (hosted)"
 	},
 	args: {
 		...HOSTED_ARGS,

package/dist/commands/indexing.mjs

@@ -80,7 +80,7 @@ const removeCommand = defineCommand({
 			console.log(JSON.stringify(result, null, 2));
 			return;
 		}
-		logger.success(`Removed: ${result.url}`);
+		logger.success(`Removal notification accepted: ${result.url}`);
 		if (result.notifyTime) console.log(`  Notified: ${result.notifyTime}`);
 	}
 });

package/dist/mcp/server/index.mjs

@@ -262,7 +262,7 @@ function createGscMcpServer(options) {
 		}] };
 	});
 	registerTool("request-indexing", {
-		description: "Request Google to index or remove a URL via the Indexing API",
+		description: "Send a URL update or removal notification to Google. Acceptance does not confirm indexing or removal.",
 		inputSchema: requestIndexingInput.shape
 	}, async (args) => {
 		const result = await requestIndexing$1(args, await getContext());
@@ -272,7 +272,7 @@ function createGscMcpServer(options) {
 		}] };
 	});
 	registerTool("get-indexing-status", {
-		description: "Get indexing status metadata for a URL",
+		description: "Read the latest Google Indexing API notification times for a URL. Use inspect-url for URL Inspection results.",
 		inputSchema: getIndexingStatusInput.shape
 	}, async (args) => {
 		const result = await getIndexingStatus(args, await getContext());
@@ -282,7 +282,7 @@ function createGscMcpServer(options) {
 		}] };
 	});
 	registerTool("batch-request-indexing", {
-		description: "Batch request indexing for multiple URLs with rate limiting",
+		description: "Send Google Indexing API notifications for multiple URLs with rate limiting. Acceptance does not confirm indexing.",
 		inputSchema: batchRequestIndexingInput.shape
 	}, async (args) => {
 		const result = await batchRequestIndexing$1(args, await getContext());

package/dist/package.mjs

@@ -1,2 +1,2 @@
-var version = "6.0.0";
+var version = "7.0.0";
 export { version };

package/dist/render/analysis.mjs

@@ -3,6 +3,28 @@ import { finite, formatMetric, metricLabel } from "./metrics.mjs";
 import { barColumn, calendarBuckets, renderBars, renderShare, renderSparklines } from "./charts.mjs";
 import { MAX_FETCH_BUDGET } from "@gscdump/engine/analysis-types";
 import { parseGscSiteUrl } from "gscdump";
+const ANALYZER_DISPLAY = {
+	"zero-click": {
+		title: "Low-CTR queries",
+		description: "Find low-CTR search queries with high impressions and strong positions; clicks can be nonzero"
+	},
+	"content-velocity": {
+		title: "Newly observed search queries",
+		description: "Count search queries first observed within the selected window, by week"
+	},
+	"intent-atlas": {
+		title: "Shared-word query groups",
+		description: "Group search queries by shared words, without classifying Search Intent"
+	},
+	"dark-traffic": {
+		title: "Clicks without reported queries",
+		description: "Compare page clicks with clicks attributed to reported search queries"
+	},
+	"keyword-breadth": {
+		title: "Search queries per page",
+		description: "Count distinct reported search queries with impressions per page"
+	}
+};
 function asRecord(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
@@ -56,7 +78,7 @@ function renderAnalysis(result, context, options) {
 	const meta = result.meta;
 	const start = typeof meta.startDate === "string" ? meta.startDate : context.start;
 	const end = typeof meta.endDate === "string" ? meta.endDate : context.end;
-	const lines = [...textLines(`${parseGscSiteUrl(context.site).hostname} / ${context.id}`, options, "accent"), ...textLines(`${start} to ${end}`, options, "muted")];
+	const lines = [...textLines(`${parseGscSiteUrl(context.site).hostname} / ${ANALYZER_DISPLAY[context.id]?.title ?? context.id}`, options, "accent"), ...textLines(`${start} to ${end}`, options, "muted")];
 	if (context.previous) lines.push(...textLines(`vs ${context.previous.start} to ${context.previous.end}`, options, "muted"));
 	const warning = coverageWarning(meta.coverage);
 	if (warning) lines.push(...textLines(warning, options, "warning"));
@@ -125,4 +147,4 @@ function renderAnalysis(result, context, options) {
 	if (total !== null && total > rows.length) lines.push("", ...textLines(`${rows.length} of ${formatMetric("clicks", total)} rows`, options, "muted"));
 	return lines.join("\n");
 }
-export { asRecord, columnsFor, coverageWarning, renderAnalysis, rowLabel };
+export { ANALYZER_DISPLAY, asRecord, columnsFor, coverageWarning, renderAnalysis, rowLabel };

package/dist/render/metrics.mjs

@@ -1,4 +1,36 @@
 const METRICS = {
+	query: {
+		label: "Search query",
+		unit: "count"
+	},
+	keyword: {
+		label: "Search query",
+		unit: "count"
+	},
+	keywordCount: {
+		label: "Search queries",
+		unit: "count"
+	},
+	newKeywords: {
+		label: "First observed queries",
+		unit: "count"
+	},
+	totalKeywords: {
+		label: "Reported queries",
+		unit: "count"
+	},
+	darkClicks: {
+		label: "Clicks without queries",
+		unit: "count"
+	},
+	darkPercent: {
+		label: "Click gap share",
+		unit: "share"
+	},
+	attributedClicks: {
+		label: "Clicks with queries",
+		unit: "count"
+	},
 	clicks: {
 		label: "Clicks",
 		unit: "count"

package/package.json

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

package/skills/gscdump/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: gscdump
 description: Drive the `gscdump` CLI for Google Search Console and Bing in Local or Hosted mode. Sync Google rows to a local Store, export Bing datasets, run SEO Analyzers and Reports, inspect Indexing Evidence, and manage sitemaps. Use when the user mentions gscdump, Search Console data, Bing Webmaster data, or GSC automation.
+license: MIT
+compatibility: "Requires the gscdump CLI and Node.js 22.13+ in the 22 release line, or Node.js 24+. API tasks need network access and credentials."
 ---
 
 # gscdump CLI
@@ -278,7 +280,7 @@ A routing stop also has `siteUrl`. `STORE_RANGE_NOT_COVERED` adds `missingDates`
 | `gscdump indexing` | Indexing API notifications and quota; hosted URL Inspection results |
 | `gscdump indexing inspect <url...> --yes` | Hosted: refresh up to 10 URLs through the platform, spending shared URL Inspections. Never retry automatically |
 | `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 indexing watch` | Hosted: list, add, and remove Watched URLs and read their Watched URL inspections |
 | `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 |
@@ -337,68 +339,9 @@ gscdump sync --site example.com --json
 - If the user excludes rollups, pass `--no-rollups` on the sync command.
 - Empty Store metadata is expected before the first sync. It does not prove zero traffic.
 
-## Query rows
+## Store queries
 
-```sh
-gscdump query --site example.com --dimensions page,query \
-  --start 2026-08-01 --end 2026-08-28 --limit 1000 --format json
-```
-
-- Dimension names are singular: `page`, `query`, `date`, `country`, `device`.
-- A page breakdown uses `--tables pages` for sync and `-d page` for query.
-  `-d page,query` needs `page_queries`; syncing only `pages` does not fill that table.
-- Filters: `--query`, `--page`, `--country`, `--device`,
-  `--search-appearance`. Prefixes: bare equals, `~` contains, `!~` not
-  contains, `re:` regex, `!re:` not regex, `!` not equals.
-- `--page` takes a path or a full URL. The Store compares paths.
-- Without dates, `query` reads the 28 days ending on the newest synced day.
-- `--live` bypasses the Store and needs Local mode. `--type` selects a search type. The default is `web`.
-  `--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 run its `nextCommand`. It syncs only the missing dates and tables.
-  Do not switch dimensions to make a failed query succeed.
-- `--explain` prints the request body or planned SQL without executing.
-
-## SQL over the Store
-
-```sh
-gscdump query --schema --format json
-gscdump query --format json --sql "SELECT search_type, SUM(clicks) AS clicks,
-  gsc_position(sum_position, impressions) AS position
-  FROM pages WHERE date >= DATE '2026-08-01' GROUP BY search_type"
-```
-
-- `--sql` runs DuckDB SQL over one view per Store table: `pages`, `queries`,
-  `page_queries`, `countries`, `dates`, `hourly_pages`, and the
-  `search_appearance*` tables. Join views on `site`, `search_type`, `url`, and `date`.
-- `--schema` lists each view, its columns, its Sites, and its date range.
-- Every view has `site` (the Site URL) and `search_type`. The Store keeps
-  every search type, so filter or group by `search_type`. A plain `SUM` adds
-  web, image, and Discover rows together.
-- `url` holds the page path. `page` is the same value.
-- `sum_position` is the zero-based position times impressions. Use
-  `gsc_position(sum_position, impressions)` for the average position. It adds 1
-  and weights by impressions. Never average a per-row position.
-- The views cover every Site in the Store. `--site` and `--type` narrow them.
-- Dates return as `YYYY-MM-DD`. Integers return as numbers.
-- If a query names a table with no synced data, the JSON has a `warnings` list.
-
-## Export the Store
-
-```sh
-gscdump dump --site example.com --format parquet --out ./export
-gscdump dump --all-sites --format sqlite --out ./export
-```
-
-- `dump` reads only the Store. It never calls Google to fill a gap.
-- Every exported row has `site` and `search_type`.
-- File formats write `<site>/<search_type>/<table>.<ext>` and
-  `<site>/<dataset>.<ext>` for inspections, sitemaps, and Indexing API metadata.
-- `csv`, `json`, and `ndjson` rows also have `position`: `sum_position / impressions + 1`.
-- `sqlite` and `duckdb` write one file, `gscdump.sqlite` or `gscdump.duckdb`,
-  with one table per dataset for every Site and search type.
-- `manifest.json` lists every dataset with its row count, plus the coverage that `sync --status --json` reports. Partial coverage is progress: daily sync fills the rest.
-- `sites.json` lists each exported Site URL with its Store ID.
+Before row queries, SQL, or Store exports, read [Store queries](references/store-queries.md).
 
 ## Analyze and report
 
@@ -441,112 +384,9 @@ gscdump analyze striking-distance --site example.com --json
   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
-
-```sh
-gscdump inspect https://example.com/page https://example.com/other --site example.com --json
-gscdump inspect --site example.com --file urls.txt --json
-gscdump indexing quota --json
-```
-
-Inspection spends Google's separate quota: 2,000 requests per day and 600 per minute for each property.
-`inspect` refuses more than 2,000 URLs in one run. It saves each result to the Store.
-On a quota error it stops and reports `remaining`. It exits 1 when any URL fails or remains.
-`indexing quota` describes Indexing API limits. It does not report remaining URL Inspection requests.
-Report the Indexing Evidence fields as Google returned them.
-
-## Find URLs Google has not indexed (hosted)
-
-```sh
-gscdump indexing urls --site example.com --status not_indexed --json
-gscdump indexing urls --site example.com --status not_indexed --all --format csv
-```
-
-- The command reads URL Inspection results that gscdump.com already saved. It spends no inspection quota.
-- `--status` takes `indexed`, `not_indexed`, or `pending`. `--search` keeps URLs that contain the text.
-- Each row lists the sitemaps that contain the URL.
-- 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.
+## Hosted inspection
 
-## Inspect one Sitemap (hosted)
-
-```sh
-gscdump sitemaps inspect https://example.com/sitemap-old.xml --site example.com --engine google --json
-gscdump sitemaps inspect https://example.com/sitemap-old.xml --site example.com --engine bing --json
-```
-
-Google reads that exact Sitemap from Search Console during the request.
-That read uses Google's API quota, without spending URL Inspections.
-Bing reads its stored provider list. Quote `capture.capturedAt` and `capture.source` with the answer.
-`listed` carries provider dates, flags, and counts. A null date means the provider supplied no date.
-`missing` means that exact Sitemap was absent at Capture time.
-`unavailable` means gscdump could not establish the evidence. The command exits with code 1.
-The command never submits a Sitemap or inspects URLs inside it.
-For Hosted MCP, use `inspect-sitemap` at `https://gscdump.com/mcp`.
-
-## 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 | URL Inspection reported the URL as unknown at its check time |
-| `discovered_not_indexed` | discovered | URL Inspection reported discovery without a crawl at its check time |
-| `crawled_not_indexed` | crawled | URL Inspection reported a crawl without indexing at its check time |
-| `indexed` | indexed | URL Inspection reported the URL as indexed at its check time |
-
-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.
-- Unknown and discovered verdicts do not show Google's current crawl queue. They do not prove noindex or content rejection.
-- An accepted indexing request does not confirm crawling or indexing. Compare its receipt date with the saved inspection date.
-- If the saved inspection predates a request, it cannot show that request's outcome. A live indexability test also cannot confirm indexing.
-- 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`. Compare that date with each saved inspection date.
-  A sitemap download confirms that Google read the feed. It does not confirm discovery, crawling, or indexing of every URL.
-  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.
+Before hosted inspection, indexing, Sitemap coverage, or Watch tasks, read [Hosted inspection](references/hosted-inspection.md).
 
 ## Report a papercut
 
@@ -581,7 +421,7 @@ the failure and continue. Never retry an uncertain submission.
   `sites verify`, `sitemaps submit`, `sitemaps delete`, `indexing submit`,
   `indexing remove`, `store reset`, and `store rm-site` change Google or
   delete local data. `indexing watch add` spends URL Inspections every week,
-  and `indexing watch remove` deletes Checkpoints. `--yes` is consent you
+  and `indexing watch remove` deletes Watched URL inspections. `--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.
@@ -614,13 +454,4 @@ For a deletion explanation, read metadata only if needed. Explain the scope and
 
 ## Refresh hosted Google URL Inspection results
 
-```sh
-gscdump indexing inspect https://example.com/page --site example.com --yes --json
-```
-
-This asks Google for its current indexed-page verdict. It does not run a live-page test or request indexing.
-Pass 1 to 10 unique URLs, or use `--file` or stdin. The platform enforces its shared daily quota.
-The command sends one request. It never splits batches or retries automatically.
-If the API returns 429, wait for the reported reset before another request.
-If `errors` or `skipped` contains URLs, the command exits 1 and preserves its result on stdout.
-Read `rateLimit.remaining` before deciding whether to inspect more URLs.
+Before a hosted Google URL Inspection refresh, read [Hosted inspection](references/hosted-inspection.md).

package/skills/gscdump/references/hosted-inspection.md

@@ -0,0 +1,131 @@
+# Hosted inspection
+
+- [Inspect and index](#inspect-and-index)
+- [Find URLs Google has not indexed (hosted)](#find-urls-google-has-not-indexed-hosted)
+- [Inspect one Sitemap (hosted)](#inspect-one-sitemap-hosted)
+- [Read the coverage ladder (hosted)](#read-the-coverage-ladder-hosted)
+- [Watch URLs (hosted)](#watch-urls-hosted)
+- [Refresh hosted Google URL Inspection results](#refresh-hosted-google-url-inspection-results)
+
+## Inspect and index
+
+```sh
+gscdump inspect https://example.com/page https://example.com/other --site example.com --json
+gscdump inspect --site example.com --file urls.txt --json
+gscdump indexing quota --json
+```
+
+Inspection spends Google's separate quota: 2,000 requests per day and 600 per minute for each property.
+`inspect` refuses more than 2,000 URLs in one run. It saves each result to the Store.
+On a quota error it stops and reports `remaining`. It exits 1 when any URL fails or remains.
+`indexing quota` describes Indexing API limits. It does not report remaining URL Inspection requests.
+Report the Indexing Evidence fields as Google returned them.
+
+## Find URLs Google has not indexed (hosted)
+
+```sh
+gscdump indexing urls --site example.com --status not_indexed --json
+gscdump indexing urls --site example.com --status not_indexed --all --format csv
+```
+
+- The command reads URL Inspection results that gscdump.com already saved. It spends no inspection quota.
+- `--status` takes `indexed`, `not_indexed`, or `pending`. `--search` keeps URLs that contain the text.
+- Each row lists the sitemaps that contain the URL.
+- 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.
+
+## Inspect one Sitemap (hosted)
+
+```sh
+gscdump sitemaps inspect https://example.com/sitemap-old.xml --site example.com --engine google --json
+gscdump sitemaps inspect https://example.com/sitemap-old.xml --site example.com --engine bing --json
+```
+
+Google reads that exact Sitemap from Search Console during the request.
+That read uses Google's API quota, without spending URL Inspections.
+Bing reads its stored provider list. Quote `capture.capturedAt` and `capture.source` with the answer.
+`listed` carries provider dates, flags, and counts. A null date means the provider supplied no date.
+`missing` means that exact Sitemap was absent at Capture time.
+`unavailable` means gscdump could not establish the evidence. The command exits with code 1.
+The command never submits a Sitemap or inspects URLs inside it.
+For Hosted MCP, use `inspect-sitemap` at `https://gscdump.com/mcp`.
+
+## 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 | URL Inspection reported the URL as unknown at its check time |
+| `discovered_not_indexed` | discovered, not indexed | URL Inspection reported discovery without a crawl at its check time |
+| `crawled_not_indexed` | crawled, not indexed | URL Inspection reported a crawl without indexing at its check time |
+| `indexed` | indexed | URL Inspection reported the URL as indexed at its check time |
+
+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 from saved inspections. Neither value means Google was inspected again.
+- 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.
+- Unknown and discovered verdicts do not show Google's current crawl queue. They do not prove noindex or content rejection.
+- An accepted indexing request does not confirm crawling or indexing. Compare its receipt date with the saved inspection date.
+- If the saved inspection predates a request, it cannot show that request's outcome. A live indexability test also cannot confirm indexing.
+- 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`. Compare that date with each saved inspection date.
+  A sitemap download confirms that Google read the feed. It does not confirm discovery, crawling, or indexing of every URL.
+  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)
+
+The frozen `checkpoints` array holds Watched URL inspections. These are the scheduled inspection history for watched URLs.
+
+```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 Watched URL inspection. 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 Watched URL inspection. `watch list --json` returns Watched URL inspections newest first, with `checkedAt`, the `coverageState` key, and Google's text.
+- Compare Watched URL inspections by date to see when a URL moves up the ladder. A new Watched URL has no Watched URL inspection until its first inspection.
+- `remove` deletes the URL's Watched URL inspections. The saved URL Inspection results stay.
+
+
+## Refresh hosted Google URL Inspection results
+
+```sh
+gscdump indexing inspect https://example.com/page --site example.com --yes --json
+```
+
+This asks Google for its current indexed-page verdict. It does not run a live-page test or request indexing.
+Pass 1 to 10 unique URLs, or use `--file` or stdin. The platform enforces its shared daily quota.
+The command sends one request. It never splits batches or retries automatically.
+If the API returns 429, wait for the reported reset before another request.
+If `errors` or `skipped` contains URLs, the command exits 1 and preserves its result on stdout.
+Read `rateLimit.remaining` before deciding whether to inspect more URLs.

package/skills/gscdump/references/store-queries.md

@@ -0,0 +1,65 @@
+# Store queries
+
+## Query rows
+
+```sh
+gscdump query --site example.com --dimensions page,query \
+  --start 2026-08-01 --end 2026-08-28 --limit 1000 --format json
+```
+
+- Dimension names are singular: `page`, `query`, `date`, `country`, `device`.
+- A page breakdown uses `--tables pages` for sync and `-d page` for query.
+  `-d page,query` needs `page_queries`; syncing only `pages` does not fill that table.
+- Filters: `--query`, `--page`, `--country`, `--device`,
+  `--search-appearance`. Prefixes: bare equals, `~` contains, `!~` not
+  contains, `re:` regex, `!re:` not regex, `!` not equals.
+- `--page` takes a path or a full URL. The Store compares paths.
+- Without dates, `query` reads the 28 days ending on the newest synced day.
+- `--live` bypasses the Store and needs Local mode. `--type` selects a search type. The default is `web`.
+  `--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 run its `nextCommand`. It syncs only the missing dates and tables.
+  Do not switch dimensions to make a failed query succeed.
+- `--explain` prints the request body or planned SQL without executing.
+
+## SQL over the Store
+
+```sh
+gscdump query --schema --format json
+gscdump query --format json --sql "SELECT search_type, SUM(clicks) AS clicks,
+  gsc_position(sum_position, impressions) AS position
+  FROM pages WHERE date >= DATE '2026-08-01' GROUP BY search_type"
+```
+
+- `--sql` runs DuckDB SQL over one view per Store table: `pages`, `queries`,
+  `page_queries`, `countries`, `dates`, `hourly_pages`, and the
+  `search_appearance*` tables. Join views on `site`, `search_type`, `url`, and `date`.
+- `--schema` lists each view, its columns, its Sites, and its date range.
+- Every view has `site` (the Site URL) and `search_type`. The Store keeps
+  every search type, so filter or group by `search_type`. A plain `SUM` adds
+  web, image, and Discover rows together.
+- `url` holds the page path. `page` is the same value.
+- `sum_position` is the zero-based position times impressions. Use
+  `gsc_position(sum_position, impressions)` for the average position. It adds 1
+  and weights by impressions. Never average a per-row position.
+- The views cover every Site in the Store. `--site` and `--type` narrow them.
+- Dates return as `YYYY-MM-DD`. Integers return as numbers.
+- If a query names a table with no synced data, the JSON has a `warnings` list.
+
+## Export the Store
+
+```sh
+gscdump dump --site example.com --format parquet --out ./export
+gscdump dump --all-sites --format sqlite --out ./export
+```
+
+- `dump` reads only the Store. It never calls Google to fill a gap.
+- Every exported row has `site` and `search_type`.
+- File formats write `<site>/<search_type>/<table>.<ext>` and
+  `<site>/<dataset>.<ext>` for inspections, sitemaps, and Indexing API metadata.
+- `csv`, `json`, and `ndjson` rows also have `position`: `sum_position / impressions + 1`.
+- `sqlite` and `duckdb` write one file, `gscdump.sqlite` or `gscdump.duckdb`,
+  with one table per dataset for every Site and search type.
+- `manifest.json` lists every dataset with its row count, plus the coverage that `sync --status --json` reports. Partial coverage is progress: daily sync fills the rest.
+- `sites.json` lists each exported Site URL with its Store ID.
+