crawlmark-mcp 0.1.0 → 0.1.2

package/dist/providers/seo-data.js

@@ -29,7 +29,8 @@ const DFS_ONLY = ["serpLive", "onPageInstant", "siteCrawl", "localProfile", "loc
 export const CAPABILITIES = {
     dataforseo: new Set([...ROUTED_CAPABILITIES, ...DFS_ONLY]),
     ahrefs: new Set(ROUTED_CAPABILITIES),
-    semrush: new Set(ROUTED_CAPABILITIES),
+    /** Semrush's v4 API serves keyword volume and backlinks only; the rest routes to DataForSEO or is unavailable. */
+    semrush: new Set(["keywordVolume", "backlinksSummary"]),
 };
 const ONLY_LABEL = {
     serpLive: "Live SERP checks",
@@ -40,6 +41,15 @@ const ONLY_LABEL = {
     localReviews: "Google reviews",
     aiVisibility: "AI-search visibility checks",
 };
+/** What a Semrush-routed client is told is missing, in plain words. */
+const SEMRUSH_LACKS = {
+    rankedKeywords: "ranked keywords",
+    competitorDomains: "competitor domains",
+    keywordIdeas: "keyword ideas",
+    keywordGap: "keyword gaps",
+    organicOverview: "organic visibility",
+    competitorOverview: "the competitor overview",
+};
 const KEY_VAR = { dataforseo: "DATAFORSEO_LOGIN / DATAFORSEO_PASSWORD", ahrefs: "AHREFS_API_KEY", semrush: "SEMRUSH_API_KEY" };
 /** Today's wording when DataForSEO has no login (rule 6). */
 export const DFS_NOT_SET = "DATAFORSEO_LOGIN / DATAFORSEO_PASSWORD are not set. See .env.example.";
@@ -69,6 +79,8 @@ export function resolveProvider(client, capability, e) {
     if (!CAPABILITIES[chosen].has(capability)) {
         if (e.configured.dataforseo)
             return { provider: "dataforseo", fallbackFrom: chosen };
+        if (chosen === "semrush" && !isDfsOnly(capability))
+            return { unavailable: `Semrush's API (v4) doesn't include ${SEMRUSH_LACKS[capability] ?? capability}. Use DataForSEO or Ahrefs for it.` };
         const what = isDfsOnly(capability) ? ONLY_LABEL[capability] : capability;
         return { unavailable: `${what} need DataForSEO; ${chosen} (the provider for ${client.slug}) doesn't offer them. Run setup --step dataforseo.` };
     }

package/dist/providers/units-billing.js

@@ -11,7 +11,7 @@ import { spendKeys } from "../lib/spend.js";
 import { stripControl } from "../lib/terminal-text.js";
 /**
  * Untrusted vendor text made safe to show or throw: every secret (and any `key=...`
- * query parameter, since Semrush keys travel in the URL) replaced, control characters
+ * query parameter, since Ahrefs and older Semrush keys can travel in a URL) replaced, control characters
  * stripped, whitespace collapsed and the length capped.
  */
 export function redact(text, secrets, max = 300) {

package/dist/reports/render/sections.js

@@ -176,7 +176,6 @@ export const ISSUE_SOURCE_NAMES = {
     dataforseo_crawl: "DataForSEO crawl",
     gsc_inspection: "Google URL Inspection",
     ahrefs_site_audit: "Ahrefs Site Audit",
-    semrush_site_audit: "Semrush Site Audit",
 };
 const SEVERITY_TITLE = { critical: "Critical", high: "High", medium: "Medium", low: "Low" };
 const CHANGE_TAG = {
@@ -941,6 +940,8 @@ export const SECTION_MAPPERS = {
         if (data.resolved.length) {
             blocks.push({ kind: "table", title: "Resolved since the last report", header: ["Issue", "Example", "Found by"], rows: data.resolved.map((i) => [d(i.title), issueExample(i, ctx.domain), foundBy(i)]) });
         }
+        for (const n of data.notes ?? [])
+            blocks.push({ kind: "note", text: [t(n)] });
         if (data.noLongerChecked)
             ctx.note("Technical SEO issues: some issues from earlier reports are no longer checked by any current source, so they are left out (not counted as fixed).");
         const from = data.sources.map((x) => `${ISSUE_SOURCE_NAMES[x.source]} (${fullDay(x.ranAt)}${x.stale ? ", older data" : ""})`).join(", ");

package/dist/reports/technical-issues.js

@@ -45,11 +45,7 @@ export async function loadTechIssuesDeps() {
         },
         latestIssueSnapshotBefore: snaps.latestIssueSnapshotBefore,
         saveIssueSnapshot: snaps.saveIssueSnapshot,
-        siteAudit: async (c, source, o) => {
-            if (source === "ahrefs_site_audit")
-                return (await import("../providers/ahrefs-site-audit.js")).readAhrefsSiteAudit(c, o);
-            return (await import("../providers/semrush-site-audit.js")).readSemrushSiteAudit(c, o);
-        },
+        siteAudit: async (c, _source, o) => (await import("../providers/ahrefs-site-audit.js")).readAhrefsSiteAudit(c, o),
         markProviderData: (p) => {
             void import("../lib/provider-data.js").then((m) => m.markProviderData(p));
         },
@@ -175,7 +171,7 @@ export async function technicalIssues(client, opts, deps) {
         }
     }
     for (const s of sources.filter((x) => PAID_ISSUE_SOURCES.has(x))) {
-        const label = s === "ahrefs_site_audit" ? "Ahrefs" : "Semrush";
+        const label = "Ahrefs";
         if (!opts.allowPaid) {
             unavailable.push({ source: s, reason: "paid source: needs allowPaid (it spends provider units)" });
             continue;
@@ -188,7 +184,7 @@ export async function technicalIssues(client, opts, deps) {
             const r = await deps.siteAudit(client, s, { issueUrls: opts.issueUrls ?? 0 });
             raws.push(...r.issues);
             runs.push({ ...r.run, stale: stale(Date.parse(r.run.ranAt)) });
-            deps.markProviderData?.(s === "ahrefs_site_audit" ? "ahrefs" : "semrush");
+            deps.markProviderData?.("ahrefs");
         }
         catch (err) {
             // crawlmark's own wording only (a missing key or project names the setting); never the provider's error text.
@@ -230,10 +226,6 @@ export async function planPaidIssueSources(client, sources, issueUrls) {
         const { planAhrefsSiteAudit } = await import("../providers/ahrefs-site-audit.js");
         out.push({ source: "ahrefs_site_audit", provider: "ahrefs", ...planAhrefsSiteAudit(issueUrls) });
     }
-    if (sources.includes("semrush_site_audit")) {
-        const { estimateSemrushSiteAudit } = await import("../providers/semrush-site-audit.js");
-        out.push({ source: "semrush_site_audit", provider: "semrush", ...(await estimateSemrushSiteAudit(client, issueUrls)) });
-    }
     return out;
 }
 //# sourceMappingURL=technical-issues.js.map

package/dist/reports/templates/run.js

@@ -12,7 +12,7 @@ import { brandedSplitFor, compare, liveRanksAvailability, movers, organicTraffic
 import { aiReadinessFrom } from "../ai-readiness.js";
 import { loadTemplates, resolveTemplate, templateFileWarnings } from "./load.js";
 import { resolvePeriod } from "./period.js";
-import { isPaidSection, SECTION_TITLES } from "./schema.js";
+import { isPaidSection, PAID_ISSUE_SOURCES, REMOVED_ISSUE_SOURCE, REMOVED_ISSUE_SOURCE_NOTE, SECTION_TITLES } from "./schema.js";
 import { analyzeCrawl, topFindings } from "../../analysis/crawl.js";
 import { wholeQuarter } from "./period.js";
 /** At most this many stored points per keyword and source go into a report (evenly thinned). */
@@ -529,12 +529,16 @@ export async function runTemplate(client, opts, deps) {
         // Phase 13 A: fetchers land in A-4 (technical_issues) and A-5 (indexing_issues).
         // Phase 13 A: stored sources only (never starts a crawl).
         technical_issues: async (s) => {
+            // A source removed since 0.1.0 is dropped, with a note in the section.
+            const removed = s.sources?.includes(REMOVED_ISSUE_SOURCE) === true;
+            const kept = s.sources?.filter((x) => x !== REMOVED_ISSUE_SOURCE);
             const r = await deps.technicalIssues(client, {
-                sources: s.sources,
+                sources: kept?.length ? kept : undefined,
                 minSeverity: s.minSeverity,
                 limit: s.limit ?? 25,
                 maxAgeDays: s.maxAgeDays,
-                issueUrls: s.issueUrls,
+                // No paid source left after dropping the removed one: nothing to fetch example URLs from.
+                issueUrls: kept?.some((x) => PAID_ISSUE_SOURCES.has(x)) ? s.issueUrls : removed ? 0 : s.issueUrls,
                 allowPaid,
                 // The base is the newest snapshot from before the period ended (for a September report run on 2 October, the
                 // one the August report took about 2 September), never one this run made.
@@ -546,7 +550,7 @@ export async function runTemplate(client, opts, deps) {
             if (!r.sources.length)
                 throw new SectionUnavailableError(`no saved audit, crawl or URL Inspection results for ${client.domain} yet (run run_audit or crawlmark-cli crawl, free)`);
             const { snapshotId: _id, ...data } = r;
-            return data;
+            return removed ? { ...data, notes: [REMOVED_ISSUE_SOURCE_NOTE] } : data;
         },
         // Phase 13 A: a sample, labelled as one in the file; never Search Console's full Page indexing report.
         indexing_issues: async (s) => {

package/dist/reports/templates/schema.js

@@ -72,12 +72,15 @@ const common = {
     paid: z.boolean().optional(),
 };
 const limit = (max) => z.number().int().min(1).max(max).optional();
-/** technical_issues sources (spec 13.6.1). The two provider site audits are paid and arrive in Stage B. */
-export const ISSUE_SOURCES = ["audit", "local_crawl", "site_hygiene", "dataforseo_crawl", "gsc_inspection", "ahrefs_site_audit", "semrush_site_audit"];
+/** technical_issues sources (spec 13.6.1). The Ahrefs Site Audit is paid. */
+/** A source 0.1.0 templates may still name. It validates (with a warning) and is dropped when the section runs. */
+export const REMOVED_ISSUE_SOURCE = "semrush_site_audit";
+export const REMOVED_ISSUE_SOURCE_NOTE = "Semrush Site Audit is no longer available (Semrush's v4 API doesn't include it).";
+export const ISSUE_SOURCES = ["audit", "local_crawl", "site_hygiene", "dataforseo_crawl", "gsc_inspection", "ahrefs_site_audit"];
 /** The free sources: the default when a technical_issues section names none. */
 export const FREE_ISSUE_SOURCES = ["audit", "local_crawl", "site_hygiene", "dataforseo_crawl", "gsc_inspection"];
-/** Sources that spend Ahrefs or Semrush units. */
-export const PAID_ISSUE_SOURCES = new Set(["ahrefs_site_audit", "semrush_site_audit"]);
+/** Sources that spend Ahrefs units. */
+export const PAID_ISSUE_SOURCES = new Set(["ahrefs_site_audit"]);
 const sectionSchemas = [
     z.strictObject({ ...common, type: z.literal("search_overview"), metrics: z.array(z.enum(["clicks", "impressions", "ctr", "position"])).min(1).optional() }),
     z.strictObject({ ...common, type: z.literal("branded_split") }),
@@ -119,13 +122,13 @@ const sectionSchemas = [
     z.strictObject({ ...common, type: z.literal("ai_visibility"), mode: z.enum(["mentions", "metrics"]).optional(), platform: z.enum(["google", "chat_gpt"]).optional(), limit: limit(50) }),
     // llms.txt and AI crawler access from the newest saved audit (free, local; never fetches).
     z.strictObject({ ...common, type: z.literal("ai_readiness") }),
-    // Phase 13 A: one deduplicated technical-issues list from stored results (free sources; Ahrefs/Semrush Site Audit are paid, Stage B).
+    // Phase 13 A: one deduplicated technical-issues list from stored results (free sources; the Ahrefs Site Audit is paid, Stage B).
     z.strictObject({
         ...common,
         type: z.literal("technical_issues"),
         limit: limit(200),
         minSeverity: z.enum(["critical", "high", "medium", "low"]).optional(),
-        sources: z.array(z.enum(ISSUE_SOURCES)).min(1).max(ISSUE_SOURCES.length).optional(),
+        sources: z.array(z.enum([...ISSUE_SOURCES, REMOVED_ISSUE_SOURCE])).min(1).max(ISSUE_SOURCES.length + 1).optional(),
         issueUrls: z.number().int().min(0).max(5).optional(),
         maxAgeDays: z.number().int().min(7).max(120).optional(),
     }),
@@ -203,7 +206,7 @@ export const SECTION_CATALOGUE = {
     local_profile: { group: "local", cost: "paid", needs: "DataForSEO and a confirmed Google Business Profile", summary: "The Google Business Profile and map-pack positions." },
     ai_visibility: { group: "ai", cost: "paid", needs: "DataForSEO with AI_VISIBILITY_ENABLED=true", summary: "AI answers (Google AI Overviews, ChatGPT) that cite the site." },
     ai_readiness: { group: "ai", cost: "free", needs: "a saved audit", summary: "llms.txt and which AI crawlers robots.txt lets in." },
-    technical_issues: { group: "site", cost: "paid_optional", needs: "a saved audit or crawl (Ahrefs / Semrush Site Audit sources are paid)", summary: "One deduplicated, severity-grouped list of technical problems from every stored source, with what changed since the last report." },
+    technical_issues: { group: "site", cost: "paid_optional", needs: "a saved audit or crawl (the Ahrefs Site Audit source is paid)", summary: "One deduplicated, severity-grouped list of technical problems from every stored source, with what changed since the last report." },
     indexing_issues: { group: "site", cost: "free", needs: "Google Search Console (uses the daily URL Inspection quota)", summary: "Google's verdict for key pages, top pages and a rotating sample of sitemap URLs, plus sitemap errors." },
     backlinks: { group: "seo_data", cost: "paid", needs: "the client's SEO data provider (DataForSEO, Ahrefs or Semrush)", summary: "Referring domains, backlinks and the provider's authority metric, with the change since last month from stored snapshots." },
     organic_visibility: { group: "seo_data", cost: "paid", needs: "the client's SEO data provider (DataForSEO, Ahrefs or Semrush)", summary: "Ranking keywords by position band and estimated organic traffic, with the trend from stored snapshots." },
@@ -303,14 +306,16 @@ export function semanticIssues(file, today) {
                 push([...at, "paid"], s.type === "tracked_keywords"
                     ? "liveRanks: true is a paid live SERP check, so the section must set paid: true"
                     : s.type === "technical_issues"
-                        ? "the ahrefs_site_audit and semrush_site_audit sources spend provider units, so the section must set paid: true"
+                        ? "the ahrefs_site_audit source spends Ahrefs units, so the section must set paid: true"
                         : `${s.type} is paid, so the section must set paid: true`);
             }
             if (s.type === "technical_issues") {
                 if (s.sources && new Set(s.sources).size !== s.sources.length)
                     push([...at, "sources"], "entries must be unique");
-                if ((s.issueUrls ?? 0) > 0 && !(s.sources ?? []).some((x) => PAID_ISSUE_SOURCES.has(x)))
-                    push([...at, "issueUrls"], "issueUrls needs an ahrefs_site_audit or semrush_site_audit source (it fetches example URLs from the provider)");
+                // A 0.1.0 template pairing issueUrls with the removed semrush_site_audit source still loads (warned about in validateTemplateText).
+                const hasRemoved = s.sources?.includes(REMOVED_ISSUE_SOURCE) === true;
+                if ((s.issueUrls ?? 0) > 0 && !hasRemoved && !(s.sources ?? []).some((x) => PAID_ISSUE_SOURCES.has(x)))
+                    push([...at, "issueUrls"], "issueUrls needs the ahrefs_site_audit source (it fetches example URLs from the provider)");
             }
             if (s.type === "core_web_vitals_history") {
                 if (s.scope === "url" && !s.url)
@@ -379,6 +384,11 @@ export function validateTemplateText(text, opts = {}) {
     if (logo && opts.logoExists && !opts.logoExists(logo)) {
         warnings.push({ path: "branding.logo", message: `${logo} doesn't exist; reports are rendered without a logo until it does` });
     }
+    (parsed.data.templates ? Object.entries(parsed.data.templates) : []).forEach(([id, t]) => t.sections.forEach((s, i) => {
+        if (s.type === "technical_issues" && s.sources?.includes(REMOVED_ISSUE_SOURCE)) {
+            warnings.push({ path: `templates.${id}.sections[${i}].sources`, message: `${REMOVED_ISSUE_SOURCE}: ${REMOVED_ISSUE_SOURCE_NOTE} It is skipped when the report runs; you can remove it.${(s.issueUrls ?? 0) > 0 && !(s.sources ?? []).some((x) => PAID_ISSUE_SOURCES.has(x)) ? " issueUrls has no source left to fetch example URLs from, so it is ignored." : ""}` });
+        }
+    }));
     return errors.length ? { valid: false, errors, warnings } : { valid: true, errors: [], warnings, value: parsed.data };
 }
 //# sourceMappingURL=schema.js.map

package/dist/reports/templates/write.js

@@ -12,13 +12,13 @@ import { createHash } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 import { chmodSync, existsSync, lstatSync, mkdirSync } from "node:fs";
 import { dirname, join, relative, resolve, sep, isAbsolute } from "node:path";
-import { Document, isMap, isScalar, isSeq, parseDocument, YAMLMap } from "yaml";
+import { Document, isMap, isNode, isScalar, isSeq, parseDocument, YAMLMap } from "yaml";
 import { RegularFileError, readRegularFileCapped } from "../../lib/read-regular-file.js";
 import { writeFileAtomic } from "../../lib/atomic-file.js";
 import { clientTemplatesFile, globalTemplatesFile } from "../paths.js";
 import { BUILTIN_TEMPLATES } from "./builtin.js";
 import { readTemplateFile, resolveLogo } from "./load.js";
-import { ID_RE, isPaidSection, MAX_TEMPLATE_BYTES, SectionSchema, validateTemplateText, } from "./schema.js";
+import { ID_RE, isPaidSection, MAX_TEMPLATE_BYTES, REMOVED_ISSUE_SOURCE, REMOVED_ISSUE_SOURCE_NOTE, SectionSchema, validateTemplateText, } from "./schema.js";
 /** The proposal is invalid: nothing can be written. `errors` carry YAML paths in the target file. */
 export class TemplateWriteError extends Error {
     errors;
@@ -152,6 +152,14 @@ export function planTemplateWrite(req) {
     const templates = templatesMap(doc);
     const existing = templates.get(req.id, true);
     const inFile = existing !== undefined;
+    // Sources the saved template already names (by section id), so an update that leaves one alone isn't refused.
+    const priorRemoved = new Set();
+    if (isNode(existing)) {
+        const prior = existing.toJSON();
+        for (const s of prior?.sections ?? [])
+            if (s?.id && s.sources?.includes(REMOVED_ISSUE_SOURCE))
+                priorRemoved.add(s.id);
+    }
     const isBuiltin = Object.hasOwn(BUILTIN_TEMPLATES, req.id);
     // A client template with the same id fully replaces the global one for that client (load.ts), so say so.
     const globalIds = req.file === "client" ? globalTemplateIds(req.homeDir, req.today) : { ids: [] };
@@ -209,6 +217,11 @@ export function planTemplateWrite(req) {
     if (!result.valid)
         throw new TemplateWriteError(`The template isn't valid: ${result.errors.map((e) => `${e.path || "(file)"}: ${e.message}`).join("; ")}`, result.errors);
     const template = result.value.templates[req.id];
+    for (const [i, s] of template.sections.entries()) {
+        if (s.type === "technical_issues" && s.sources?.includes(REMOVED_ISSUE_SOURCE) && !priorRemoved.has(s.id)) {
+            throw new TemplateWriteError(`${REMOVED_ISSUE_SOURCE_NOTE} It can't be added to a template.`, [{ path: `templates.${req.id}.sections[${i}].sources`, message: `${REMOVED_ISSUE_SOURCE}: ${REMOVED_ISSUE_SOURCE_NOTE}` }]);
+        }
+    }
     const block = new Document({ [req.id]: template });
     styleTemplateNode(block.contents.get(req.id, true));
     return {

package/dist/setup/apps.js

@@ -108,7 +108,7 @@ export async function detectApps(ctx) {
  * Run an app's CLI to change its registration. Plain mode gives it the terminal,
  * as before; fancy mode captures its output and prints it inside the frame.
  */
-async function runApp(ctx, cmd, args) {
+export async function runApp(ctx, cmd, args) {
     if (!uiFor(ctx).fancy)
         return ctx.exec(cmd, args, { inherit: true });
     const r = await ctx.exec(cmd, args);

package/dist/setup/menu.js

@@ -12,6 +12,7 @@ export const MENU_CHOICES = [
     { value: "provider", label: "Add or change a data provider" },
     { value: "google", label: "Change Google sign-in" },
     { value: "register", label: "Re-register AI apps" },
+    { value: "vendor-mcp", label: "Add Semrush's or Ahrefs' own MCP server" },
     { value: "discovery", label: "Refresh clients" },
     { value: "branding", label: "Set up report branding" },
     { value: "status", label: "Check status" },
@@ -20,7 +21,7 @@ export const MENU_CHOICES = [
 ];
 /** The --step a menu action runs, if it is one. */
 export function menuStep(action) {
-    return action === "provider" || action === "google" || action === "register" || action === "discovery" || action === "branding" ? action : undefined;
+    return action === "provider" || action === "google" || action === "register" || action === "vendor-mcp" || action === "discovery" || action === "branding" ? action : undefined;
 }
 /** What the menu's status read asks for. */
 export const MENU_STATUS_IDS = ["dataforseo", "ahrefs", "semrush", "google", "clients"];

package/dist/setup/status-providers.js

@@ -5,7 +5,6 @@ import { loadOverrides } from "../clients.js";
 import { ENV_FILE, ENV_FILE_KEYS, env, HOME, PROJECT_ROOT, seoDefaultProvider } from "../config.js";
 import { globalUnitCap, unitsThisMonth } from "../lib/budget.js";
 import { checkAhrefsKey } from "../providers/ahrefs.js";
-import { checkSemrushKey } from "../providers/semrush.js";
 import { checkCruxKey, cruxKey } from "../providers/crux.js";
 import { bingKey, checkBingKey } from "../providers/bing.js";
 import { remainingAiUsd } from "../lib/budget.js";
@@ -121,9 +120,8 @@ export const realStatusProviders = {
             : { default: null, source: ENV_FILE_KEYS.has("SEO_DATA_PROVIDER") ? "envFile" : "env", invalidValue: d.invalidValue, perClientOverrides };
     },
     semrush: async () => ({
-        check: await checkSemrushKey(env.SEMRUSH_API_KEY),
+        keySet: Boolean(env.SEMRUSH_API_KEY),
         chosen: providerChoice("semrush"),
-        v4KeySet: Boolean(env.SEMRUSH_V4_API_KEY),
         unitsUsedThisMonth: unitsThisMonth(undefined, "semrush"),
         cap: globalUnitCap("semrush"),
     }),

package/dist/setup/status.js

@@ -150,40 +150,34 @@ export function ahrefsRow(a, next) {
     };
 }
 /**
- * The `semrush` row (spec 9.6): missing (no key, nobody uses it), error (used but no key,
- * or rejected), configured (the balance check couldn't be reached, the balance is 0, or a
- * v4 key is set but untested: it has no free check), working. Never a key.
+ * The `semrush` row: missing (no key, nobody uses it), error (used but no key), configured (key set; Semrush has no
+ * free key check, so it is untested until the first paid call). Never a key, never a request.
  */
 export function semrushRow(s, next) {
-    const { check, chosen } = s;
+    const { chosen } = s;
     const used = chosen.byDefault || chosen.clients > 0;
     const base = { id: "semrush", label: "Semrush" };
     const data = {
         default: chosen.byDefault,
         clients: chosen.clients,
-        keySet: check.configured,
-        v4KeySet: s.v4KeySet,
+        keySet: s.keySet,
+        keyCheck: "none",
+        capabilities: { keywordVolume: s.keySet, backlinksSummary: s.keySet },
         unitsUsedThisMonth: s.unitsUsedThisMonth,
         cap: s.cap,
-        ...(check.works === true ? { unitsLeft: check.unitsLeft } : {}),
     };
-    const usage = `crawlmark used ${fmtUnits(s.unitsUsedThisMonth)} of its ${fmtUnits(s.cap)}-unit monthly cap this month`;
-    if (!check.configured) {
+    if (!s.keySet) {
         return used
             ? { ...base, state: "error", detail: `Semrush is ${choiceText(chosen)}, but SEMRUSH_API_KEY is not set, so its paid calls fail.`, next, data }
-            : { ...base, state: "missing", detail: "Optional. A Semrush API key (SEO Business plan plus an API unit package) can supply keyword, ranking, competitor and backlink data.", next, data };
-    }
-    if (check.works === false)
-        return { ...base, state: "error", detail: check.error, next, data };
-    if (check.works === null) {
-        return { ...base, state: "configured", detail: `SEMRUSH_API_KEY is set but Semrush's balance check couldn't be reached, so it's untested: ${check.error}`, next, data };
+            : { ...base, state: "missing", detail: "Optional. A Semrush v4 API key (profile > API keys) supplies keyword volume and backlinks; rankings, competitors and visibility come from DataForSEO or Ahrefs.", next, data };
     }
-    const left = check.unitsLeft;
-    const v4 = s.v4KeySet ? " The v4 key (backlinks) has no free check; it's checked the first time backlinks_summary runs." : " Backlinks use the v3 report (no v4 key set).";
-    const head = `Key accepted, ${fmtUnits(left)} API units left; ${usage}.${used ? ` Used as ${choiceText(chosen)}.` : ""}`;
-    if (left === 0)
-        return { ...base, state: "configured", detail: `Key accepted but the balance is 0 units; Semrush API needs an SEO Business plan and a unit package.${v4}`, next, data };
-    return { ...base, state: s.v4KeySet ? "configured" : "working", detail: `${head}${v4}`, next: null, data };
+    return {
+        ...base,
+        state: "configured",
+        detail: `Key set (v4). It serves keyword volume (20 units per keyword, Early Access) and backlinks (45 units); Semrush has no free key check, so it's checked by the first paid call. crawlmark used ${fmtUnits(s.unitsUsedThisMonth)} of its ${fmtUnits(s.cap)}-unit monthly cap this month.${used ? ` Used as ${choiceText(chosen)}.` : ""}`,
+        next: null,
+        data,
+    };
 }
 async function attempt(fn) {
     try {
@@ -253,7 +247,7 @@ export async function collectSetupStatus(p, opts = {}) {
         const states = {
             dataforseo: dfs ? dfsState(dfs) : "missing",
             ahrefs: ahrefs ? keyState(ahrefs.check) : "missing",
-            semrush: semrush ? keyState(semrush.check) : "missing",
+            semrush: semrush?.keySet ? "configured" : "missing",
         };
         const row = seoProviderRow(seo, states, { cli, configuredByEnv: home.configuredByEnv });
         seoData = row.data;