seo 0.2.15 → 0.2.16

package/dist/mcp.js

@@ -1,5 +1,5 @@
 import { createRequire as __seoCreateRequire } from 'node:module'; const require = __seoCreateRequire(import.meta.url);
-import { n as load, t as version } from "./package-Cuxp-LBy.js";
+import { n as load, t as version } from "./package-D_ix15KL.js";
 import { Headers, fetch as fetch$1 } from "undici";
 import { chmodSync, createReadStream, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { arch, homedir, platform, totalmem } from "node:os";
@@ -787,6 +787,52 @@ async function createGoogleAccessTokenClient() {
 	};
 }
 //#endregion
+//#region packages/core/dist/keyword-sets/schema.js
+const KEYWORD_SET_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS keyword_sets (
+  id TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL,
+  name TEXT NOT NULL,
+  market_json TEXT NOT NULL,
+  provider TEXT CHECK(provider IS NULL OR provider IN ('dataforseo', 'semrush', 'ahrefs')),
+  source_report TEXT,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  last_refreshed_at INTEGER,
+  UNIQUE(project_id, name COLLATE NOCASE)
+);
+CREATE INDEX IF NOT EXISTS idx_keyword_sets_project
+  ON keyword_sets(project_id, updated_at DESC, id);
+
+CREATE TABLE IF NOT EXISTS keyword_set_items (
+  set_id TEXT NOT NULL,
+  normalized_keyword TEXT NOT NULL,
+  display_keyword TEXT NOT NULL,
+  metric_json TEXT,
+  metric_provider TEXT CHECK(metric_provider IS NULL OR metric_provider IN ('dataforseo', 'semrush', 'ahrefs')),
+  metric_observed_at TEXT,
+  page_kind TEXT CHECK(page_kind IS NULL OR page_kind IN ('target', 'proposed')),
+  page_url TEXT,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  PRIMARY KEY(set_id, normalized_keyword),
+  FOREIGN KEY(set_id) REFERENCES keyword_sets(id) ON DELETE CASCADE
+) WITHOUT ROWID;
+CREATE INDEX IF NOT EXISTS idx_keyword_set_items_set
+  ON keyword_set_items(set_id, normalized_keyword);
+
+CREATE TABLE IF NOT EXISTS keyword_set_tags (
+  set_id TEXT NOT NULL,
+  normalized_keyword TEXT NOT NULL,
+  tag TEXT NOT NULL,
+  PRIMARY KEY(set_id, normalized_keyword, tag),
+  FOREIGN KEY(set_id, normalized_keyword)
+    REFERENCES keyword_set_items(set_id, normalized_keyword) ON DELETE CASCADE
+) WITHOUT ROWID;
+CREATE INDEX IF NOT EXISTS idx_keyword_set_tags_lookup
+  ON keyword_set_tags(set_id, tag, normalized_keyword);
+`;
+//#endregion
 //#region packages/core/dist/storage/cache-maintenance.js
 const MEBIBYTE$2 = 1024 * 1024;
 const CACHE_MAX_AGE_MS = 720 * 60 * 60 * 1e3;
@@ -1341,6 +1387,7 @@ function initDb(database, isNewDatabase) {
 	if (isNewDatabase) database.pragma("auto_vacuum = INCREMENTAL");
 	database.transaction(() => {
 		database.exec(CREATE_SQL);
+		database.exec(KEYWORD_SET_SCHEMA_SQL);
 		database.exec(PROVIDER_SPEND_SCHEMA_SQL);
 		database.exec(`DELETE FROM semrush_cache WHERE request_json LIKE '%"key"%'`);
 		ensureColumn(database, "crawl_pages", "snapshot_json", "TEXT");
@@ -4486,7 +4533,7 @@ async function fetchPage(url, opts = {}, dependencies = {}) {
 }
 //#endregion
 //#region packages/core/dist/gsc/property-url.js
-function invalid(message) {
+function invalid$1(message) {
 	throw new SeoError("INVALID_INPUT", message);
 }
 function normalizeHttpUrl(value) {
@@ -4494,10 +4541,10 @@ function normalizeHttpUrl(value) {
 	try {
 		url = new URL(value.trim());
 	} catch {
-		return invalid(`Invalid URL: ${value}`);
+		return invalid$1(`Invalid URL: ${value}`);
 	}
-	if (url.protocol !== "http:" && url.protocol !== "https:") return invalid("The report URL must use http:// or https://.");
-	if (url.username || url.password) return invalid("The report URL must not contain embedded credentials.");
+	if (url.protocol !== "http:" && url.protocol !== "https:") return invalid$1("The report URL must use http:// or https://.");
+	if (url.username || url.password) return invalid$1("The report URL must not contain embedded credentials.");
 	url.hash = "";
 	return url.toString();
 }
@@ -4506,13 +4553,13 @@ function assertUrlMatchesGscProperty(property, value) {
 	const parsed = new URL(url);
 	if (property.startsWith("sc-domain:")) {
 		const domain = property.slice(10).trim().toLowerCase();
-		if (!domain || /[/:]/.test(domain)) return invalid(`Invalid Search Console domain property: ${property}`);
+		if (!domain || /[/:]/.test(domain)) return invalid$1(`Invalid Search Console domain property: ${property}`);
 		const hostname = parsed.hostname.toLowerCase();
-		if (hostname !== domain && !hostname.endsWith(`.${domain}`)) return invalid(`${url} is outside the Search Console property ${property}.`);
+		if (hostname !== domain && !hostname.endsWith(`.${domain}`)) return invalid$1(`${url} is outside the Search Console property ${property}.`);
 		return url;
 	}
 	const prefix = normalizeHttpUrl(property);
-	if (!url.startsWith(prefix)) return invalid(`${url} is outside the Search Console property ${property}.`);
+	if (!url.startsWith(prefix)) return invalid$1(`${url} is outside the Search Console property ${property}.`);
 	return url;
 }
 //#endregion
@@ -21745,7 +21792,7 @@ const MAX_LEDGER_ROWS = 5e4;
 const MAX_LEDGER_BYTES = 32 * 1024 * 1024;
 const MAX_TASK_IDS = 20;
 const MAX_ACTIVE_RESERVATIONS = 100;
-function boundedText(provider, value, label, max) {
+function boundedText$1(provider, value, label, max) {
 	const normalized = value.trim();
 	if (!normalized || normalized.length > max) throw new ProviderError({
 		provider,
@@ -21839,10 +21886,10 @@ function reserveProviderSpend(input, options = {}) {
 	const now = options.now ?? Date.now();
 	const normalized = {
 		...input,
-		endpoint: boundedText(input.provider, input.endpoint, "Provider endpoint", 500),
-		projectId: input.projectId ? boundedText(input.provider, input.projectId, "Project id", 200) : void 0,
-		reportId: boundedText(input.provider, input.reportId, "Report id", 100),
-		reportRunId: boundedText(input.provider, input.reportRunId, "Report run id", 100),
+		endpoint: boundedText$1(input.provider, input.endpoint, "Provider endpoint", 500),
+		projectId: input.projectId ? boundedText$1(input.provider, input.projectId, "Project id", 200) : void 0,
+		reportId: boundedText$1(input.provider, input.reportId, "Report id", 100),
+		reportRunId: boundedText$1(input.provider, input.reportRunId, "Report run id", 100),
 		requestedRows: nonnegativeInteger(input.provider, input.requestedRows, "Requested rows"),
 		estimatedCostMicros: nonnegativeInteger(input.provider, input.estimatedCostMicros, "Estimated cost")
 	};
@@ -21879,7 +21926,7 @@ function reserveProviderSpend(input, options = {}) {
 function finalizeProviderSpend(reservationId, result, options = {}) {
 	const database = options.database ?? getDb();
 	const now = options.now ?? Date.now();
-	const taskIds = [...new Set(result.taskIds)].sort((left, right) => left < right ? -1 : left > right ? 1 : 0).slice(0, MAX_TASK_IDS).map((id) => boundedText(result.provider, id, "Provider task id", 100));
+	const taskIds = [...new Set(result.taskIds)].sort((left, right) => left < right ? -1 : left > right ? 1 : 0).slice(0, MAX_TASK_IDS).map((id) => boundedText$1(result.provider, id, "Provider task id", 100));
 	const actualCostMicros = result.actualCostMicros === null ? null : nonnegativeInteger(result.provider, result.actualCostMicros, "Actual cost");
 	const returnedRows = result.returnedRows === null ? null : nonnegativeInteger(result.provider, result.returnedRows, "Returned rows");
 	return database.transaction(() => {
@@ -22163,7 +22210,7 @@ const dataForSeoUserDataResponseSchema = z.object({
 const MAX_PROVIDER_MONTHLY_SEARCH_ROWS = 120;
 const nullableNumber = z.number().finite().nullable().optional();
 const nullableCount = z.union([z.number().finite(), z.string().trim().min(1)]).nullable().optional();
-const monthlySearchSchema = z.object({
+const monthlySearchSchema$1 = z.object({
 	year: z.number().int(),
 	month: z.number().int(),
 	search_volume: z.number().finite().nullable().optional()
@@ -22174,7 +22221,7 @@ const keywordOverviewItemSchema = z.object({
 		search_volume: nullableNumber,
 		cpc: nullableNumber,
 		competition: nullableNumber,
-		monthly_searches: z.array(monthlySearchSchema).max(MAX_PROVIDER_MONTHLY_SEARCH_ROWS).nullish(),
+		monthly_searches: z.array(monthlySearchSchema$1).max(MAX_PROVIDER_MONTHLY_SEARCH_ROWS).nullish(),
 		last_updated_time: z.string().trim().min(1).nullable().optional()
 	}).nullish(),
 	keyword_properties: z.object({ keyword_difficulty: nullableNumber }).nullish(),
@@ -22188,7 +22235,7 @@ const keywordOverviewItemSchema = z.object({
 }).passthrough();
 const keywordOverviewResultSchema = z.object({
 	items_count: z.number().int().nonnegative().optional(),
-	items: z.array(keywordOverviewItemSchema).optional()
+	items: z.array(keywordOverviewItemSchema).nullable().optional()
 }).passthrough();
 const keywordOverviewTaskSchema = z.object({
 	id: z.string().trim().min(1).optional(),
@@ -23139,13 +23186,55 @@ var DataForSeoKeywordMetricsProvider = class {
 		status: "available",
 		markets: [{
 			searchEngines: ["google"],
-			location: "any"
+			location: "country-only"
 		}]
 	}];
 	client;
 	constructor(options = {}) {
 		this.client = options.client ?? new DataForSeoClient(options);
 	}
+	async estimateKeywordMetricsCost(input) {
+		if (!Number.isSafeInteger(input.requestedRows) || input.requestedRows < 1 || input.requestedRows > 1e4) throw new ProviderError({
+			provider: "dataforseo",
+			operation: "keyword-metrics-cost",
+			code: "configuration",
+			message: "Keyword metric cost estimates require 1 to 10000 rows."
+		});
+		if (!searchMarketSchema.safeParse(input.market).success) throw new ProviderError({
+			provider: "dataforseo",
+			operation: "keyword-metrics-cost",
+			code: "configuration",
+			message: "Keyword metric cost estimates require a valid market."
+		});
+		if (input.market.location) throw new ProviderError({
+			provider: "dataforseo",
+			operation: "keyword-metrics-cost",
+			code: "configuration",
+			message: "DataForSEO Labs keyword metrics supports country-level markets; omit market.location and use countryCode."
+		});
+		if (!this.client.userData) throw new ProviderError({
+			provider: "dataforseo",
+			operation: "keyword-metrics-cost",
+			code: "configuration",
+			message: "Keyword metric cost estimation is unavailable."
+		});
+		const account = await this.client.userData();
+		const { perRequestMicros, perResultMicros } = account.keywordOverviewPrice;
+		const requestCount = Math.ceil(input.requestedRows / 50);
+		const complete = perRequestMicros !== null && perResultMicros !== null;
+		return {
+			schemaVersion: 1,
+			provider: "dataforseo",
+			capability: "keyword-metrics",
+			currency: "USD",
+			requestedRows: input.requestedRows,
+			requestCount,
+			estimatedMicros: complete ? requestCount * perRequestMicros + input.requestedRows * perResultMicros : null,
+			observedAt: account.observedAt,
+			completeness: complete ? "complete" : "unavailable",
+			basis: complete ? "Current account pricing for normal-priority live keyword overview requests." : "The provider account response did not include complete keyword overview pricing."
+		};
+	}
 	async keywordMetrics(input) {
 		const market = searchMarketSchema.parse(input.market);
 		if (market.searchEngine !== "google") throw new ProviderError({
@@ -23154,6 +23243,12 @@ var DataForSeoKeywordMetricsProvider = class {
 			code: "configuration",
 			message: "DataForSEO keyword metrics currently supports Google markets."
 		});
+		if (market.location) throw new ProviderError({
+			provider: "dataforseo",
+			operation: "keyword-metrics",
+			code: "configuration",
+			message: "DataForSEO Labs keyword metrics supports country-level markets; omit market.location and use countryCode."
+		});
 		if (input.keywords.length < 1 || input.keywords.length > MAX_KEYWORDS_PER_REPORT || input.keywords.some((keyword) => {
 			const normalized = keyword.trim();
 			return normalized.length < 1 || normalized.length > 80 || normalized.split(/\s+/u).length > 10;
@@ -23369,6 +23464,7 @@ async function defaultCandidates$2() {
 }
 function providerResolutionError(input) {
 	if (input.reason === "provider-not-connected") return new SeoError("PROVIDER_UNAVAILABLE", "No connected provider can supply keyword metrics. Run `seo providers dataforseo connect` first.");
+	if (input.provider && input.reason === "market-not-supported") return new SeoError("INVALID_INPUT", input.provider === "dataforseo" ? "DataForSEO keyword metrics uses country-level Labs data. Omit location and keep countryCode, then run serp-results separately for a local snapshot." : `${input.provider} cannot supply keyword metrics for this market.`);
 	if (input.provider) return new SeoError("PROVIDER_UNAVAILABLE", `${input.provider} cannot supply keyword metrics for this market.`);
 	return new SeoError("PROVIDER_UNAVAILABLE", "No configured provider can supply keyword metrics for this market.");
 }
@@ -24970,7 +25066,7 @@ var DataForSeoKeywordDiscoveryProvider = class {
 		status: "available",
 		markets: [{
 			searchEngines: ["google"],
-			location: "any"
+			location: "country-only"
 		}]
 	}];
 	client;
@@ -24985,6 +25081,12 @@ var DataForSeoKeywordDiscoveryProvider = class {
 			code: "configuration",
 			message: "DataForSEO keyword discovery currently supports Google."
 		});
+		if (market.location) throw new ProviderError({
+			provider: "dataforseo",
+			operation: "keyword-discovery",
+			code: "configuration",
+			message: "DataForSEO Labs keyword discovery supports country-level markets; omit market.location and use countryCode."
+		});
 		const seeds = [...new Set(input.seeds.map(normalizedKeyword$1))].filter(Boolean).sort(compareCodepoints$3);
 		if (seeds.length < 1 || seeds.length > MAX_DISCOVERY_SEEDS || seeds.some((seed) => seed.length > 80 || seed.split(/\s+/u).length > 10)) throw new ProviderError({
 			provider: "dataforseo",
@@ -25183,7 +25285,10 @@ async function keywordResearchReport(input, dependencies = {}) {
 		candidates,
 		provider: validated.provider
 	});
-	if (resolution.status === "unavailable") throw new SeoError("PROVIDER_UNAVAILABLE", resolution.reason === "provider-not-connected" ? "No connected provider can discover keywords. Run `seo providers dataforseo connect` first." : validated.provider ? `${validated.provider} cannot discover keywords for this market.` : "No configured provider can discover keywords for this market.");
+	if (resolution.status === "unavailable") {
+		const message = resolution.reason === "provider-not-connected" ? "No connected provider can discover keywords. Run `seo providers dataforseo connect` first." : validated.provider ? `${validated.provider} cannot discover keywords for this market.` : "No configured provider can discover keywords for this market.";
+		throw new SeoError(validated.provider && resolution.reason === "market-not-supported" ? "INVALID_INPUT" : "PROVIDER_UNAVAILABLE", validated.provider === "dataforseo" && resolution.reason === "market-not-supported" ? "DataForSEO keyword discovery uses country-level Labs data. Omit location and keep countryCode, then run serp-results separately for a local snapshot." : message);
+	}
 	const provider = discoveryProvider(resolution.provider);
 	if (!provider) throw new SeoError("PROVIDER_UNAVAILABLE", "The selected provider has no keyword discovery implementation.");
 	let evidence;
@@ -29814,6 +29919,7 @@ var DataForSeoSerpSnapshotProvider = class {
 		const organicResults = mappedOrganicResults.slice(0, input.depth);
 		const invalidRows = organicItems.length - mappedOrganicResults.length;
 		const resultCapped = mappedOrganicResults.length > input.depth;
+		const invalidResultCount = result.se_results_count !== null && result.se_results_count !== void 0 && result.se_results_count < organicResults.length;
 		if (invalidRows > 0) warnings.push({
 			code: "invalid-organic-results",
 			field: "organicResults",
@@ -29830,6 +29936,11 @@ var DataForSeoSerpSnapshotProvider = class {
 			field: "checkUrl",
 			message: "DataForSEO returned an invalid SERP check URL."
 		});
+		if (invalidResultCount) warnings.push({
+			code: "invalid-serp-result-count",
+			field: "resultCount",
+			message: "DataForSEO returned an estimated result count below the retained organic result count; the estimate was discarded."
+		});
 		const features = [.../* @__PURE__ */ new Set([...result.item_types ?? [], ...items.map((item) => item.type)])].sort(compareCodepoints$3);
 		return {
 			schemaVersion: 1,
@@ -29841,7 +29952,7 @@ var DataForSeoSerpSnapshotProvider = class {
 				searchEngineDomain: result.se_domain?.trim().toLowerCase() ?? null,
 				checkedAt: checkedAt(result.datetime, snapshot.observedAt),
 				checkUrl,
-				resultCount: result.se_results_count === void 0 ? null : result.se_results_count,
+				resultCount: invalidResultCount ? null : result.se_results_count ?? null,
 				pagesCount: result.pages_count === void 0 ? null : result.pages_count,
 				features,
 				organicResults
@@ -29856,8 +29967,8 @@ var DataForSeoSerpSnapshotProvider = class {
 				returnedRows: snapshot.returnedRows,
 				retainedRows: organicResults.length,
 				invalidRows,
-				providerTotalRows: result.se_results_count ?? null,
-				completeness: invalidRows > 0 ? "partial" : resultCapped ? "capped" : "complete",
+				providerTotalRows: invalidResultCount ? null : result.se_results_count ?? null,
+				completeness: invalidRows > 0 || invalidResultCount ? "partial" : resultCapped ? "capped" : "complete",
 				nextCursor: null
 			},
 			cache: snapshot.cache,
@@ -30696,6 +30807,320 @@ function reportPresentation(report) {
 	};
 }
 //#endregion
+//#region packages/core/dist/keyword-sets/limits.js
+const KEYWORD_SET_LIMITS = {
+	setsPerProject: 25,
+	totalSets: 100,
+	keywordsPerSet: 1e4,
+	totalKeywords: 1e5,
+	mutationKeywords: 1e3,
+	tagsPerKeyword: 20,
+	outputRows: 1e3,
+	logicalBytes: 64 * 1024 * 1024
+};
+const KEYWORD_SET_FIELD_LIMITS = {
+	name: 80,
+	projectId: 80,
+	sourceReport: 100,
+	keyword: 80,
+	keywordWords: 10,
+	tag: 40,
+	url: 2048,
+	metricJsonBytes: 16 * 1024
+};
+//#endregion
+//#region packages/core/dist/keyword-sets/validation.js
+const unavailableValueSchema = z.strictObject({
+	state: z.enum([
+		"missing",
+		"unavailable",
+		"invalid"
+	]),
+	value: z.null(),
+	reason: z.string().min(1).max(500)
+});
+const providerValueNumberSchema = z.discriminatedUnion("state", [z.strictObject({
+	state: z.literal("observed"),
+	value: z.number().finite()
+}), unavailableValueSchema]);
+const providerValueStringSchema = z.discriminatedUnion("state", [z.strictObject({
+	state: z.literal("observed"),
+	value: z.string().max(500)
+}), unavailableValueSchema]);
+const monthlySearchSchema = z.strictObject({
+	year: z.number().int().min(2e3).max(2200),
+	month: z.number().int().min(1).max(12),
+	searchVolume: z.number().finite().nonnegative()
+});
+const providerValueMonthlySearchesSchema = z.discriminatedUnion("state", [z.strictObject({
+	state: z.literal("observed"),
+	value: z.array(monthlySearchSchema).max(24)
+}), unavailableValueSchema]);
+const keywordMetricSchema = z.strictObject({
+	keyword: z.string().min(1).max(KEYWORD_SET_FIELD_LIMITS.keyword),
+	monthlySearchVolume: providerValueNumberSchema,
+	monthlySearches: providerValueMonthlySearchesSchema,
+	searchVolumeUpdatedAt: providerValueStringSchema,
+	cpcUsd: providerValueNumberSchema,
+	paidCompetition: providerValueNumberSchema,
+	keywordDifficulty: providerValueNumberSchema,
+	intent: providerValueStringSchema,
+	resultCount: providerValueNumberSchema
+});
+const savedMetricSchema = z.strictObject({
+	schemaVersion: z.literal(1),
+	provider: providerIdSchema,
+	observedAt: z.iso.datetime(),
+	metric: keywordMetricSchema
+});
+function invalid(message) {
+	throw new SeoError("INVALID_INPUT", message);
+}
+function boundedText(value, label, max) {
+	const normalized = value.trim();
+	if (!normalized || normalized.length > max) invalid(`${label} must contain 1 to ${max} characters.`);
+	return normalized;
+}
+function normalizeSavedKeyword(value) {
+	const normalized = value.trim().replace(/\s+/gu, " ").toLowerCase();
+	if (!normalized || normalized.length > KEYWORD_SET_FIELD_LIMITS.keyword || normalized.split(" ").length > KEYWORD_SET_FIELD_LIMITS.keywordWords) invalid(`Keywords must contain 1 to ${KEYWORD_SET_FIELD_LIMITS.keyword} characters and at most ${KEYWORD_SET_FIELD_LIMITS.keywordWords} words.`);
+	return normalized;
+}
+function parseStoredJson(value, schema, label) {
+	let decoded;
+	try {
+		decoded = JSON.parse(value);
+	} catch {
+		throw new SeoError("INTERNAL_ERROR", `${label} contains invalid JSON.`);
+	}
+	const parsed = schema.safeParse(decoded);
+	if (!parsed.success) throw new SeoError("INTERNAL_ERROR", `${label} has an invalid shape.`);
+	return parsed.data;
+}
+//#endregion
+//#region packages/core/dist/keyword-sets/rows.js
+const SET_SELECT = `
+  SELECT sets.*,
+    (SELECT COUNT(*) FROM keyword_set_items items WHERE items.set_id = sets.id) AS keyword_count,
+    (SELECT COUNT(DISTINCT tags.tag) FROM keyword_set_tags tags WHERE tags.set_id = sets.id) AS tag_count
+  FROM keyword_sets sets`;
+function storeDatabase(options) {
+	return options.database ?? getDb();
+}
+function rowToSet(row) {
+	const provider = row.provider ? providerIdSchema.safeParse(row.provider) : void 0;
+	if (provider && !provider.success) throw new SeoError("INTERNAL_ERROR", "Saved keyword set provider is invalid.");
+	return {
+		schemaVersion: 1,
+		id: row.id,
+		projectId: row.project_id,
+		name: row.name,
+		market: parseStoredJson(row.market_json, searchMarketSchema, "Saved search market"),
+		provider: provider?.data ?? null,
+		sourceReport: row.source_report,
+		keywordCount: row.keyword_count,
+		tagCount: row.tag_count,
+		createdAt: new Date(row.created_at).toISOString(),
+		updatedAt: new Date(row.updated_at).toISOString(),
+		lastRefreshedAt: row.last_refreshed_at === null ? null : new Date(row.last_refreshed_at).toISOString()
+	};
+}
+function findSetRow(db, projectId, idOrName) {
+	return db.prepare(`${SET_SELECT}
+       WHERE sets.project_id = ?
+         AND (sets.id = ? OR sets.name = ? COLLATE NOCASE)
+       ORDER BY CASE WHEN sets.id = ? THEN 0 ELSE 1 END
+       LIMIT 1`).get(projectId, idOrName, idOrName, idOrName);
+}
+function requireSetRow(db, projectId, idOrName) {
+	const row = findSetRow(db, projectId, idOrName);
+	if (!row) invalid(`Keyword set not found: ${idOrName}`);
+	return row;
+}
+function rowCount(db, sql, ...params) {
+	return db.prepare(sql).get(...params).count;
+}
+//#endregion
+//#region packages/core/dist/keyword-sets/store.js
+function getKeywordSet(input, options = {}) {
+	const projectId = boundedText(input.projectId, "Project id", KEYWORD_SET_FIELD_LIMITS.projectId);
+	const idOrName = boundedText(input.idOrName, "Keyword set id or name", KEYWORD_SET_FIELD_LIMITS.name);
+	const tag = input.tag ? boundedText(input.tag, "Tag", KEYWORD_SET_FIELD_LIMITS.tag).toLowerCase() : null;
+	const limit = input.limit ?? 100;
+	const offset = input.offset ?? 0;
+	if (!Number.isSafeInteger(limit) || limit < 1 || limit > KEYWORD_SET_LIMITS.outputRows) invalid(`Keyword set output limit must be from 1 to ${KEYWORD_SET_LIMITS.outputRows}.`);
+	if (!Number.isSafeInteger(offset) || offset < 0) invalid("Keyword set output offset must be zero or greater.");
+	const db = storeDatabase(options);
+	const setRow = requireSetRow(db, projectId, idOrName);
+	const filterSql = tag ? `AND EXISTS (
+        SELECT 1 FROM keyword_set_tags filter_tags
+        WHERE filter_tags.set_id = items.set_id
+          AND filter_tags.normalized_keyword = items.normalized_keyword
+          AND filter_tags.tag = ?
+      )` : "";
+	const params = tag ? [setRow.id, tag] : [setRow.id];
+	const total = rowCount(db, `SELECT COUNT(*) AS count FROM keyword_set_items items
+     WHERE items.set_id = ? ${filterSql}`, ...params);
+	const rows = db.prepare(`SELECT items.* FROM keyword_set_items items
+       WHERE items.set_id = ? ${filterSql}
+       ORDER BY items.normalized_keyword
+       LIMIT ? OFFSET ?`).all(...params, limit, offset);
+	const tagsByKeyword = loadTags(db, setRow.id, rows);
+	const items = rows.map((row) => itemFromRow(row, tagsByKeyword.get(row.normalized_keyword) ?? []));
+	return {
+		schemaVersion: 1,
+		set: rowToSet(setRow),
+		items,
+		pagination: {
+			offset,
+			limit,
+			returned: items.length,
+			total,
+			nextOffset: offset + items.length < total ? offset + items.length : null
+		},
+		filter: { tag }
+	};
+}
+function loadTags(db, setId, rows) {
+	if (rows.length === 0) return /* @__PURE__ */ new Map();
+	const tagRows = db.prepare(`SELECT normalized_keyword, tag FROM keyword_set_tags
+       WHERE set_id = ? AND normalized_keyword IN (${rows.map(() => "?").join(", ")})
+       ORDER BY normalized_keyword, tag`).all(setId, ...rows.map((row) => row.normalized_keyword));
+	const tagsByKeyword = /* @__PURE__ */ new Map();
+	for (const row of tagRows) {
+		const tags = tagsByKeyword.get(row.normalized_keyword) ?? [];
+		tags.push(row.tag);
+		tagsByKeyword.set(row.normalized_keyword, tags);
+	}
+	return tagsByKeyword;
+}
+function itemFromRow(row, tags) {
+	const latestMetric = row.metric_json ? parseStoredJson(row.metric_json, savedMetricSchema, "Saved keyword metric") : null;
+	if (latestMetric && (latestMetric.provider !== row.metric_provider || latestMetric.observedAt !== row.metric_observed_at || normalizeSavedKeyword(latestMetric.metric.keyword) !== row.normalized_keyword)) throw new SeoError("INTERNAL_ERROR", "Saved keyword metric metadata is inconsistent.");
+	const page = row.page_kind && row.page_url ? {
+		kind: row.page_kind,
+		url: row.page_url
+	} : null;
+	return {
+		keyword: row.display_keyword,
+		normalizedKeyword: row.normalized_keyword,
+		tags,
+		page,
+		latestMetric,
+		createdAt: new Date(row.created_at).toISOString(),
+		updatedAt: new Date(row.updated_at).toISOString()
+	};
+}
+//#endregion
+//#region packages/core/dist/analyze/saved-keywords.js
+const DEFAULT_STALE_DAYS = 45;
+function savedKeywordSetReport(input, dependencies = {}) {
+	const staleDays = input.staleDays ?? DEFAULT_STALE_DAYS;
+	if (!Number.isSafeInteger(staleDays) || staleDays < 1 || staleDays > 365) throw new SeoError("INVALID_INPUT", "Metric freshness must be from 1 to 365 days.");
+	const now = (dependencies.now ?? (() => /* @__PURE__ */ new Date()))();
+	const evidence = (dependencies.getKeywordSet ?? getKeywordSet)(input);
+	const snapshots = evidence.items.filter((item) => item.latestMetric);
+	const observedVolumes = snapshots.filter((item) => item.latestMetric?.metric.monthlySearchVolume.state === "observed");
+	const staleCutoff = now.getTime() - staleDays * 864e5;
+	const staleSnapshots = snapshots.filter((item) => Date.parse(item.latestMetric?.observedAt ?? "") < staleCutoff);
+	const mapped = evidence.items.filter((item) => item.page);
+	const tagGroups = groupedCounts(evidence.items.flatMap((item) => item.tags)).map(([tag, keywordCount]) => ({
+		tag,
+		keywordCount
+	}));
+	const pageMappings = groupedMappings(evidence);
+	const missingMetrics = evidence.items.length - snapshots.length;
+	const unavailableVolumeSnapshots = snapshots.length - observedVolumes.length;
+	const unmapped = evidence.items.length - mapped.length;
+	const partial = evidence.pagination.nextOffset !== null || evidence.pagination.offset > 0 || evidence.pagination.total !== evidence.set.keywordCount;
+	const dataStatus = evidence.items.length === 0 ? "unavailable" : partial ? "partial" : "complete";
+	return {
+		schemaVersion: 1,
+		generatedAt: now.toISOString(),
+		dataStatus,
+		summary: {
+			name: evidence.set.name,
+			totalKeywords: evidence.set.keywordCount,
+			matchedKeywords: evidence.pagination.total,
+			returnedKeywords: evidence.items.length,
+			metricSnapshots: snapshots.length,
+			observedVolumes: observedVolumes.length,
+			observedZeroVolumes: observedVolumes.filter((item) => item.latestMetric?.metric.monthlySearchVolume.value === 0).length,
+			unavailableVolumeSnapshots,
+			staleMetricSnapshots: staleSnapshots.length,
+			mappedKeywords: mapped.length,
+			targetPages: pageMappings.filter((item) => item.kind === "target").length,
+			proposedPages: pageMappings.filter((item) => item.kind === "proposed").length,
+			distinctTags: tagGroups.length,
+			verdict: `${evidence.items.length} saved keywords were returned; search volume is observed for ${observedVolumes.length}, unavailable in ${unavailableVolumeSnapshots} saved snapshot${unavailableVolumeSnapshots === 1 ? "" : "s"}, and ${mapped.length} have page mappings.`
+		},
+		evidence,
+		analysis: {
+			metricFreshnessDays: staleDays,
+			tagGroups,
+			pageMappings
+		},
+		findings: [
+			...missingMetrics > 0 ? [{
+				code: "missing-metrics",
+				evidenceRef: "evidence.items[*].latestMetric",
+				detail: `${missingMetrics} returned keywords have no saved provider metric snapshot.`,
+				action: "Preview a keyword-set refresh before using provider metrics to prioritize them."
+			}] : [],
+			...unavailableVolumeSnapshots > 0 ? [{
+				code: "unavailable-volume-evidence",
+				evidenceRef: "evidence.items[*].latestMetric.metric.monthlySearchVolume",
+				detail: `${unavailableVolumeSnapshots} saved metric snapshot${unavailableVolumeSnapshots === 1 ? "" : "s"} ${unavailableVolumeSnapshots === 1 ? "has" : "have"} no observed search volume. This is not an observed zero.`,
+				action: "Keep these terms separate from observed-zero terms and verify them with another source or a later refresh before using demand as a filter."
+			}] : [],
+			...staleSnapshots.length > 0 ? [{
+				code: "stale-metrics",
+				evidenceRef: "evidence.items[*].latestMetric.observedAt",
+				detail: `${staleSnapshots.length} saved metric snapshots are older than ${staleDays} days.`,
+				action: "Preview and selectively refresh the stale provider evidence."
+			}] : [],
+			...unmapped > 0 ? [{
+				code: "unmapped-keywords",
+				evidenceRef: "evidence.items[*].page",
+				detail: `${unmapped} returned keywords have no existing or proposed page mapping.`,
+				action: "Review shared intent and current results before mapping terms to an existing page or a proposed page."
+			}] : []
+		],
+		caveats: [
+			"Tags are user-managed research labels, not proof that keywords share one intent or should use one page.",
+			"Provider metrics are market estimates; missing evidence differs from an observed zero.",
+			"Page mappings record planning state and do not prove that a page ranks, is indexed, or should be created.",
+			...partial ? ["This view is filtered or paginated and cannot support a complete-set all-clear."] : []
+		],
+		nextSteps: [
+			"Compare relevant saved terms with Search Console evidence for the project before changing priorities.",
+			"Inspect current results in the same market before turning a tag group into a page or programmatic template.",
+			"Use the refresh preview to check provider cost before updating saved metric snapshots."
+		]
+	};
+}
+function groupedCounts(values) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const value of values) counts.set(value, (counts.get(value) ?? 0) + 1);
+	return [...counts].sort(([left, leftCount], [right, rightCount]) => rightCount - leftCount || (left < right ? -1 : left > right ? 1 : 0)).slice(0, 50);
+}
+function groupedMappings(evidence) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const item of evidence.items) {
+		if (!item.page) continue;
+		const key = `${item.page.kind}\u0000${item.page.url}`;
+		const current = counts.get(key);
+		counts.set(key, {
+			...item.page,
+			count: (current?.count ?? 0) + 1
+		});
+	}
+	return [...counts.values()].sort((left, right) => right.count - left.count || (left.url < right.url ? -1 : left.url > right.url ? 1 : 0)).slice(0, 50).map(({ count, ...mapping }) => ({
+		...mapping,
+		keywordCount: count
+	}));
+}
+//#endregion
 //#region packages/core/dist/analyze/second-page.js
 const MAX_SOURCE_ROWS = 1e5;
 const defaultDependencies = {
@@ -34215,6 +34640,7 @@ const TELEMETRY_REPORTS = [
 	"keyword-metrics",
 	"keyword-opportunities",
 	"keyword-research",
+	"saved-keywords",
 	"link-evidence",
 	"server-log-analysis",
 	"link-recovery",
@@ -35979,7 +36405,33 @@ const keywordOpportunitiesInput = z$1.strictObject({
 		message: "External keyword context requires countryCode and languageCode."
 	});
 });
+const savedKeywordsInput = z$1.strictObject({
+	projectId: z$1.string().trim().min(1).max(80),
+	set: z$1.string().trim().min(1).max(80),
+	tag: z$1.string().trim().min(1).max(40).optional(),
+	limit: z$1.number().int().min(1).max(1e3).default(100),
+	offset: z$1.number().int().min(0).max(1e5).default(0),
+	staleDays: z$1.number().int().min(1).max(365).default(45)
+});
 function registerKeywordTools(server, dependencies = {}) {
+	server.registerTool("seo_saved_keywords", {
+		description: "Review one bounded local keyword set with metric freshness, tags, page mappings, and evidence limits",
+		inputSchema: savedKeywordsInput
+	}, async ({ projectId, set, tag, limit, offset, staleDays }) => {
+		try {
+			const report = (dependencies.savedKeywordSetReport ?? savedKeywordSetReport)({
+				projectId,
+				idOrName: set,
+				tag,
+				limit,
+				offset,
+				staleDays
+			});
+			return toolSuccess(report.summary.verdict, compactAgentWorkflowOutput(report));
+		} catch (error) {
+			return toolError(error);
+		}
+	});
 	server.registerTool("seo_keyword_metrics", {
 		description: "Compare bounded third-party keyword demand, cost, competition, difficulty, intent, result-count, and trend evidence",
 		inputSchema: {
@@ -37998,6 +38450,39 @@ const REPORT_DEPTH = {
 			}
 		]
 	},
+	"saved-keywords": {
+		readOrder: [
+			"dataStatus, summary, evidence pagination, and any tag filter",
+			"the saved set market, source, refresh time, and keyword count",
+			"each item metric value state, observation time, tags, and page mapping",
+			"analysis groups, findings, caveats, and nextSteps"
+		],
+		doNotClaim: [
+			"User-managed tags do not prove shared intent or justify one page or template.",
+			"Provider metrics are estimates rather than first-party rankings or traffic, and a missing value differs from an observed zero.",
+			"A target or proposed page mapping does not prove that the page should exist, ranks, or is indexed.",
+			"A filtered, capped, or paginated view cannot support a conclusion about the complete set."
+		],
+		verify: "Compare relevant terms with Search Console and inspect current results in the saved market before changing a page or template plan.",
+		related: [
+			{
+				id: "keyword-metrics",
+				reason: "Refreshes a supplied term list."
+			},
+			{
+				id: "keyword-research",
+				reason: "Discovers more candidate terms."
+			},
+			{
+				id: "keyword-opportunities",
+				reason: "Adds first-party opportunity evidence."
+			},
+			{
+				id: "pseo-opportunities",
+				reason: "Reviews repeatable programmatic patterns."
+			}
+		]
+	},
 	"query-clusters": {
 		readOrder: [
 			"summary cluster and query counts, clicks, impressions, threshold, limit, and brand filtering",
@@ -38783,6 +39268,13 @@ const REPORT_GUIDANCE = {
 		avoidWhen: ["You need exact current rankings or pages in the live results.", "You plan to turn every discovered term into a page without checking intent or fit."],
 		outcome: "A bounded keyword set with discovery sources, provider estimates, evidence states, and research follow-ups."
 	},
+	"saved-keywords": {
+		name: "Saved keyword set",
+		description: "Review one local keyword set with metric freshness, tags, page mappings, and explicit view limits.",
+		useWhen: ["You want to continue earlier keyword research from a saved project set.", "You need to review stale, unmapped, or tagged terms before deeper research."],
+		avoidWhen: ["You need independent keyword discovery or a current result snapshot.", "You plan to treat user-managed tags as proof of shared search intent."],
+		outcome: "A bounded local research view with saved evidence, freshness state, planning mappings, and next steps."
+	},
 	"query-clusters": {
 		name: "Search query clusters",
 		description: "Group related Search Console queries so repeated demand themes are easier to review.",
@@ -39338,6 +39830,7 @@ const reportGroups = [
 			"seo_keyword_metrics",
 			"seo_keyword_opportunities",
 			"seo_keyword_research",
+			"seo_saved_keywords",
 			"seo_serp_results"
 		]
 	},