@rivi-software/agentic-seo-check 0.0.0-stage → 0.1.1

package/dist/mcp.js

@@ -0,0 +1,380 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { MAKER, MCP_ICONS, REPOSITORY_URL } from "./brand.js";
+import { auditDirectory, auditHtml, auditSite, auditUrl, compactAudit, } from "./core/audit.js";
+import { runLighthouse } from "./core/lighthouse.js";
+import { performanceFindings } from "./core/performance-rules.js";
+import { renderMarkdown } from "./core/report/markdown.js";
+import { ALL_RULES } from "./core/rules/index.js";
+import { VERSION } from "./version.js";
+export const MCP_SERVER_NAME = "agentic-seo-check";
+export const MCP_SERVER_VERSION = VERSION;
+const format = z
+    .enum(["json", "markdown"])
+    .default("json")
+    .describe("json (default) returns the structured audit; markdown returns a human-readable report.");
+const detail = z
+    .enum(["full", "compact"])
+    .default("compact")
+    .describe("compact trims evidence lists and bulky fields to save tokens (default); full returns everything.");
+const commonOptions = {
+    keyword: z
+        .string()
+        .optional()
+        .describe("Target keyword/phrase. Enables keyword.* checks (title, H1, body, description, URL, density)."),
+    includeInfo: z
+        .boolean()
+        .default(true)
+        .describe("Include info-level findings (best practices). Set false to see only errors and warnings."),
+    disableRules: z
+        .array(z.string())
+        .optional()
+        .describe('Rule ids to skip, e.g. ["twitter.card-missing"]. Use seo_list_rules to see ids.'),
+    timeoutMs: z
+        .number()
+        .int()
+        .min(1000)
+        .max(120_000)
+        .optional()
+        .describe("Per-request timeout in milliseconds (default 15000)."),
+    userAgent: z.string().optional().describe("Override the User-Agent header."),
+    headers: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe('Extra request headers, e.g. {"Authorization": "Basic ..."} for staging sites.'),
+    format,
+    detail,
+};
+const toOptions = (input) => ({
+    keyword: input.keyword,
+    includeInfo: input.includeInfo,
+    disableRules: input.disableRules,
+    fetch: {
+        timeoutMs: input.timeoutMs,
+        userAgent: input.userAgent,
+        headers: input.headers,
+    },
+});
+const respond = (audit, fmt, det) => {
+    const report = det === "compact" ? compactAudit(audit) : audit;
+    const text = fmt === "markdown"
+        ? renderMarkdown(report)
+        : JSON.stringify(report, null, 2);
+    return {
+        content: [{ type: "text", text }],
+        structuredContent: { ...report },
+    };
+};
+// oxlint-disable-next-line anti-slop/no-unknown-parameters -- a thrown value is unknown until this reads it
+const fail = (error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        isError: true,
+        content: [
+            { type: "text", text: `agentic-seo-check error: ${message}` },
+        ],
+    };
+};
+const metricCell = (name, value) => {
+    if (value === null) {
+        return "—";
+    }
+    return name.endsWith("Ms") ? `${Math.round(value)} ms` : String(value);
+};
+const lighthouseMarkdown = (payload) => {
+    const lines = [
+        `# Lighthouse (${payload.formFactor}): ${payload.finalUrl}`,
+        "",
+        "| Metric | Value |",
+        "| --- | --- |",
+    ];
+    for (const [name, value] of Object.entries(payload.metrics)) {
+        lines.push(`| ${name} | ${metricCell(name, value)} |`);
+    }
+    lines.push("", "## Opportunities", "");
+    for (const o of payload.opportunities.slice(0, 10)) {
+        lines.push(`- ${o.title}${o.savingsMs ? ` (~${Math.round(o.savingsMs)} ms)` : ""}${o.savingsBytes ? ` (~${Math.round(o.savingsBytes / 1024)} KiB)` : ""}`);
+    }
+    lines.push("", "## Findings", "");
+    for (const f of payload.findings) {
+        lines.push(`- **\`${f.rule}\`** ${f.message}`, `  - Fix: ${f.recommendation}`);
+    }
+    return lines.join("\n");
+};
+export const createMcpServer = () => {
+    const server = new McpServer({
+        name: MCP_SERVER_NAME,
+        title: `agentic-seo-check by ${MAKER}`,
+        version: MCP_SERVER_VERSION,
+        description: "SEO audits for coding agents: pages, sites, build output and raw HTML, with findings an agent can act on.",
+        websiteUrl: REPOSITORY_URL,
+        icons: MCP_ICONS,
+    });
+    server.registerTool("seo_audit_page", {
+        title: "Audit one page for SEO",
+        description: "Audit a single page and return prioritised, actionable findings (rule id, severity, message, recommendation, CSS selector, evidence). " +
+            "Checks title, meta description, headings, canonical, robots/noindex, viewport/lang, Open Graph/Twitter cards, images, links, hreflang, structured data (JSON-LD/microdata), content quality and the HTTP response. " +
+            "Provide either `url` (live site, staging or http://localhost dev server) or `html` (raw HTML string, e.g. from a template or test render). " +
+            "Set `render: true` to also load the page in headless Chromium and report content that only exists after JavaScript runs (SPA/CSR problems). " +
+            "Set `lighthouse: true` for Core Web Vitals (LCP, CLS, TBT) and Lighthouse SEO audits; this takes 20-60 seconds. " +
+            "Typical workflow: audit, fix the errors and warnings in the source code, re-audit to confirm.",
+        inputSchema: {
+            url: z
+                .string()
+                .url()
+                .optional()
+                .describe("Absolute http(s) URL to fetch and audit."),
+            html: z
+                .string()
+                .optional()
+                .describe("Raw HTML to audit instead of fetching a URL."),
+            baseUrl: z
+                .string()
+                .url()
+                .optional()
+                .describe("With `html`: the URL the HTML would be served at (used to resolve links and classify them as internal/external)."),
+            render: z
+                .boolean()
+                .default(false)
+                .describe("Also render with headless Chromium (Playwright) and compare against the server HTML."),
+            lighthouse: z
+                .boolean()
+                .default(false)
+                .describe("Also run Lighthouse (performance, SEO, agentic-browsing categories). Slow."),
+            formFactor: z
+                .enum(["mobile", "desktop"])
+                .default("mobile")
+                .describe("Lighthouse device emulation."),
+            ...commonOptions,
+        },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: true,
+            idempotentHint: true,
+        },
+    }, async (input) => {
+        try {
+            const options = {
+                ...toOptions(input),
+                render: input.render,
+                lighthouse: input.lighthouse,
+                formFactor: input.formFactor,
+                baseUrl: input.baseUrl,
+            };
+            const { html, url } = input;
+            let audit;
+            // `html` wins over `url`; an empty `html` counts only when a `url` came with it.
+            if (html !== undefined && (html || url)) {
+                audit = await auditHtml(html, { url: input.baseUrl, source: "html", target: "inline-html" }, options);
+            }
+            else if (url) {
+                audit = await auditUrl(url, options);
+            }
+            else {
+                throw new Error("Provide `url` or `html`.");
+            }
+            return respond(audit, input.format, input.detail);
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("seo_crawl_site", {
+        title: "Crawl a site and audit every page",
+        description: "Crawl internal links from a start URL (default 25 pages, depth 3), audit every HTML page, and run site-wide checks: robots.txt, XML sitemap coverage (missing/noindex/non-canonical/broken URLs), broken internal links with their sources, redirect chains, duplicate titles/descriptions/H1s/content, orphan and deep pages, soft-404 behaviour, http→https and www redirects, hreflang return links. " +
+            "Returns site findings plus `issues` (page findings rolled up by rule with example URLs) and per-page scores. Use seo_audit_page on a specific URL for full per-page detail. " +
+            "Works on http://localhost dev servers; for those set `respectRobots: false` if the dev server serves a blocking robots.txt.",
+        inputSchema: {
+            url: z.string().url().describe("Start URL (usually the homepage)."),
+            maxPages: z
+                .number()
+                .int()
+                .min(1)
+                .max(500)
+                .default(25)
+                .describe("Maximum pages to fetch."),
+            maxDepth: z
+                .number()
+                .int()
+                .min(0)
+                .max(10)
+                .default(3)
+                .describe("Maximum link depth from the start URL."),
+            concurrency: z
+                .number()
+                .int()
+                .min(1)
+                .max(10)
+                .default(4)
+                .describe("Parallel requests."),
+            delayMs: z
+                .number()
+                .int()
+                .min(0)
+                .max(5000)
+                .default(0)
+                .describe("Delay between requests per worker (politeness)."),
+            respectRobots: z
+                .boolean()
+                .default(true)
+                .describe("Obey robots.txt disallow rules while crawling."),
+            includeSubdomains: z
+                .boolean()
+                .default(false)
+                .describe("Treat subdomains of the start host as internal."),
+            checkExternalLinks: z
+                .boolean()
+                .default(false)
+                .describe("Also probe external link targets for 4xx/5xx (slower)."),
+            includePatterns: z
+                .array(z.string())
+                .optional()
+                .describe("Only crawl URLs matching one of these regular expressions."),
+            excludePatterns: z
+                .array(z.string())
+                .optional()
+                .describe("Skip URLs matching any of these regular expressions."),
+            pageDetail: z
+                .enum(["summary", "full"])
+                .default("summary")
+                .describe("summary: per-page scores/counts only (findings are rolled up in `issues`); full: every finding on every page."),
+            ...commonOptions,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async (input) => {
+        try {
+            const audit = await auditSite(input.url, {
+                ...toOptions(input),
+                maxPages: input.maxPages,
+                maxDepth: input.maxDepth,
+                concurrency: input.concurrency,
+                delayMs: input.delayMs,
+                respectRobots: input.respectRobots,
+                includeSubdomains: input.includeSubdomains,
+                checkExternalLinks: input.checkExternalLinks,
+                includePatterns: input.includePatterns,
+                excludePatterns: input.excludePatterns,
+                pageDetail: input.pageDetail,
+            });
+            return respond(audit, input.format, input.detail);
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("seo_audit_directory", {
+        title: "Audit a static build output directory",
+        description: "Audit every .html file in a build output directory (dist/, out/, build/, .output/public) without running a server. Runs all page checks plus directory-level checks: internal links that resolve to no file, sitemap.xml/robots.txt in the output, duplicate titles/descriptions/content, unlinked files. " +
+            "Pass `baseUrl` as the production origin (e.g. https://www.example.com) so absolute links, canonicals and sitemap URLs are classified correctly.",
+        inputSchema: {
+            dir: z
+                .string()
+                .describe("Absolute or relative path to the directory containing built HTML files."),
+            baseUrl: z
+                .string()
+                .url()
+                .default("http://localhost/")
+                .describe("Origin the files will be served from."),
+            maxPages: z
+                .number()
+                .int()
+                .min(1)
+                .max(5000)
+                .default(500)
+                .describe("Maximum HTML files to audit."),
+            pageDetail: z
+                .enum(["summary", "full"])
+                .default("summary")
+                .describe("summary: per-page scores/counts only; full: every finding on every page."),
+            ...commonOptions,
+        },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+            idempotentHint: true,
+        },
+    }, async (input) => {
+        try {
+            const audit = await auditDirectory(input.dir, {
+                ...toOptions(input),
+                baseUrl: input.baseUrl,
+                maxPages: input.maxPages,
+                pageDetail: input.pageDetail,
+            });
+            return respond(audit, input.format, input.detail);
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("seo_lighthouse", {
+        title: "Run Lighthouse on a URL",
+        description: "Run Google Lighthouse (performance, SEO and agentic-browsing categories) against one URL using a local headless Chrome. Returns Core Web Vitals lab metrics (LCP, CLS, TBT, FCP, Speed Index, TTFB), the top opportunities with estimated savings, failed Lighthouse SEO audits, and findings with thresholds applied. Takes 20-60 seconds. Requires Chrome or Playwright Chromium on this machine.",
+        inputSchema: {
+            url: z.string().url().describe("Absolute http(s) URL."),
+            formFactor: z
+                .enum(["mobile", "desktop"])
+                .default("mobile")
+                .describe("Device emulation. Mobile is what Google uses for ranking."),
+            headers: z
+                .record(z.string(), z.string())
+                .optional()
+                .describe("Extra request headers (e.g. auth for staging)."),
+            format,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async (input) => {
+        try {
+            const result = await runLighthouse(input.url, {
+                formFactor: input.formFactor,
+                headers: input.headers,
+            });
+            const findings = performanceFindings(result);
+            const payload = { ...result, findings };
+            const text = input.format === "markdown"
+                ? lighthouseMarkdown(payload)
+                : JSON.stringify(payload, null, 2);
+            return {
+                content: [{ type: "text", text }],
+                structuredContent: payload,
+            };
+        }
+        catch (error) {
+            return fail(error);
+        }
+    });
+    server.registerTool("seo_list_rules", {
+        title: "List SEO rules",
+        description: "List every rule this tool can report, with id, category, typical severity, what it checks and the generic fix. Filter by category or look up one rule id to understand a finding.",
+        inputSchema: {
+            category: z
+                .string()
+                .optional()
+                .describe("Filter by category (title, meta, headings, canonical, indexing, document, social, images, links, international, structured-data, content, keyword, response, rendering, performance, site)."),
+            rule: z.string().optional().describe("Return only this rule id."),
+        },
+        annotations: {
+            readOnlyHint: true,
+            openWorldHint: false,
+            idempotentHint: true,
+        },
+    }, (input) => {
+        const rules = ALL_RULES.filter((r) => (!input.category || r.category === input.category) &&
+            (!input.rule || r.id === input.rule));
+        const payload = { count: rules.length, rules };
+        return {
+            content: [
+                { type: "text", text: JSON.stringify(payload, null, 2) },
+            ],
+            structuredContent: payload,
+        };
+    });
+    return server;
+};
+export const startMcpServer = async () => {
+    const server = createMcpServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+};
+//# sourceMappingURL=mcp.js.map

package/dist/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION: string;

package/dist/version.js

@@ -0,0 +1,6 @@
+import { readFileSync } from "node:fs";
+/** Package version, read from package.json (one level above both src/ and dist/) so a release bumps one file. */
+// SAFETY: npm and pnpm refuse to pack or publish a package.json without a string version.
+const manifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
+export const VERSION = manifest.version;
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,iHAAiH;AACjH,0FAA0F;AAC1F,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CACzB,YAAY,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC,CAC5C,CAAC;AAEzB,MAAM,CAAC,MAAM,OAAO,GAAW,QAAQ,CAAC,OAAO,CAAC"}

package/package.json

@@ -1,6 +1,110 @@
 {
   "name": "@rivi-software/agentic-seo-check",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "SEO analysis for coding agents: a CLI and MCP server that audit URLs, static build output or raw HTML and return machine-actionable findings.",
+  "license": "MIT",
+  "author": "RIVI Software (https://rivi.software)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rivi-software/agentic-seo-check.git"
+  },
+  "homepage": "https://github.com/rivi-software/agentic-seo-check#readme",
+  "bugs": {
+    "url": "https://github.com/rivi-software/agentic-seo-check/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.19"
+  },
+  "bin": {
+    "agentic-seo-check": "./dist/cli.js",
+    "agentic-seo-check-mcp": "./dist/mcp-bin.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "seo",
+    "audit",
+    "mcp",
+    "model-context-protocol",
+    "cli",
+    "coding-agents",
+    "lighthouse",
+    "crawler"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "commander": "^15.1.0",
+    "css-select": "^7.0.0",
+    "domhandler": "^6.0.1",
+    "domutils": "^4.0.2",
+    "fast-xml-parser": "^5.12.0",
+    "parse5": "^8.1.1",
+    "parse5-htmlparser2-tree-adapter": "^8.0.2",
+    "robots-parser": "^3.0.1",
+    "zod": "^4.6.7"
+  },
+  "peerDependencies": {
+    "chrome-launcher": "^1.2.3",
+    "lighthouse": "^13.6.0",
+    "playwright": "^1.65.0"
+  },
+  "peerDependenciesMeta": {
+    "chrome-launcher": {
+      "optional": true
+    },
+    "lighthouse": {
+      "optional": true
+    },
+    "playwright": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.5",
+    "@changesets/cli": "3.0.3",
+    "@types/node": "22.20.5",
+    "chrome-launcher": "^1.2.3",
+    "lefthook": "2.2.2",
+    "lighthouse": "^13.6.0",
+    "oxfmt": "0.75.0",
+    "oxlint": "1.90.0",
+    "playwright": "^1.65.0",
+    "tsx": "^4.20.0",
+    "typescript": "^7.0.2",
+    "ultracite": "8.1.1",
+    "vitest": "^5.1.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "dev": "tsx src/cli.ts",
+    "mcp": "tsx src/mcp-bin.ts",
+    "check": "tsc -p tsconfig.json",
+    "lint": "oxlint",
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
+    "fix": "ultracite fix -A unicorn/catch-error-name -A typescript/consistent-type-definitions -A unicorn/prefer-dom-node-append -A unicorn/prefer-dom-node-dataset -A unicorn/prefer-query-selector -A unicorn/prefer-at -A unicorn/prefer-set-has -A unicorn/prefer-spread -A unicorn/prefer-bigint-literals -A unicorn/prefer-import-meta-properties -A unicorn/prefer-number-coercion -A unicorn/prefer-type-error -A unicorn/prefer-regexp-test -A unicorn/text-encoding-identifier-case -A unicorn/no-useless-undefined -A vitest/prefer-describe-function-title",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "check:package": "node scripts/check-package.ts",
+    "verify": "pnpm run format:check && pnpm run lint && pnpm run check && pnpm run test && pnpm run build && pnpm run check:package",
+    "changeset": "changeset",
+    "version-packages": "changeset version && pnpm install --lockfile-only",
+    "release": "changeset publish"
+  }
 }

package/skills/seo-audit/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: seo-audit
+description: Audit and fix SEO for a website or web project with the agentic-seo-check CLI/MCP tool. Use when asked to check, improve, or fix SEO, meta tags, titles, descriptions, canonicals, Open Graph, structured data, sitemaps, robots.txt, broken links, Core Web Vitals, or "why isn't this page indexed/ranking". Works on live URLs, localhost dev servers, static build output (dist/, out/) and raw HTML.
+---
+
+# SEO audit workflow
+
+You have `agentic-seo-check` available either as MCP tools (`seo_audit_page`, `seo_crawl_site`, `seo_audit_directory`, `seo_lighthouse`, `seo_list_rules`) or as a CLI (`agentic-seo-check`, or `npx @rivi-software/agentic-seo-check`). Both return the same JSON: findings with `rule`, `severity`, `message`, `recommendation`, `selector`, `evidence`, plus a 0-100 `score`.
+
+## 1. Pick the target
+
+| Situation | Use |
+| --- | --- |
+| One page, live or on `http://localhost:3000` | `seo_audit_page { url }` / `agentic-seo-check audit <url>` |
+| Whole site, find site-wide problems | `seo_crawl_site { url, maxPages }` / `agentic-seo-check crawl <url> --max-pages 50` |
+| Static export already built (Next `out/`, Astro `dist/`, Vite `dist/`) | `seo_audit_directory { dir, baseUrl }` / `agentic-seo-check audit ./dist --base-url https://www.example.com` |
+| You rendered HTML yourself (template, test, snapshot) | `seo_audit_page { html, baseUrl }` / `cat page.html \| agentic-seo-check audit -` |
+| Suspect client-side rendering hides content from crawlers | add `render: true` / `--render` |
+| Performance / Core Web Vitals | `seo_lighthouse { url }` or `lighthouse: true` / `--lighthouse` (slow, 20-60 s) |
+| Optimising for a specific search phrase | add `keyword` / `--keyword "blue widgets"` |
+
+Prefer auditing the running dev server or the build output over guessing from source: the tool sees exactly what crawlers see.
+
+## 2. Read the result
+
+- Fix in this order: **error** → **warning** → **info**. Errors block indexing or are outright defects (missing title, conflicting canonicals, invalid JSON-LD, 4xx/5xx, broken links). Warnings hurt ranking or click-through. Info is best practice.
+- For site audits start with `siteFindings` and `issues` (page findings rolled up per rule with example URLs). One template fix usually clears a rule on many pages.
+- `selector` tells you where in the HTML the problem is; `evidence` contains the current values and the offending items (capped lists). `recommendation` says what to change.
+- `seo_list_rules { rule }` explains any rule id.
+
+## 3. Fix in the source, not in the output
+
+Find where the page's `<head>` is produced and change it there, per route:
+
+- Next.js app router: `export const metadata` / `generateMetadata` (title, description, alternates.canonical, openGraph, robots). Pages router: `next/head`. Sitemap: `app/sitemap.ts`; robots: `app/robots.ts`.
+- Astro: `<head>` in the layout, props per page; `@astrojs/sitemap`.
+- Nuxt: `useSeoMeta` / `useHead`; `@nuxtjs/sitemap`.
+- SvelteKit: `<svelte:head>`; Remix/React Router: `meta` export; TanStack Start: `head()` on the route.
+- Plain HTML/static generators: the template partial that renders `<head>`.
+
+Typical mappings: `title.*`/`meta-description.*` → per-route metadata; `canonical.*` → absolute self-referencing canonical built from the site URL; `og.*`/`twitter.*` → social metadata with an absolute image URL; `structured-data.*` → JSON-LD emitted with `JSON.stringify`; `img.alt-missing` → alt props on image components; `site.broken-internal-links` → fix hrefs or add redirects; `site.sitemap-*` → generate the sitemap from the router so it stays in sync; `rendering.*` → move data fetching to the server (SSR/SSG) so the HTML carries the content.
+
+## 4. Re-run and confirm
+
+Run the same audit again. Report before/after score and the remaining findings. In CI, `agentic-seo-check audit <target> --fail-on error` exits 1 when errors remain.
+
+## Caveats to tell the user about
+
+- `robots.noindex` on a preview/staging host is often added by the hosting platform (X-Robots-Tag); check production before "fixing" it.
+- A localhost audit cannot verify https, www redirects or the production robots.txt/sitemap; run a crawl against the deployed site for those.
+- Scores are indicative (100 minus weighted deductions), not a ranking prediction.
+- Lighthouse numbers are lab measurements from this machine; field data (CrUX) may differ.
+- `render` needs Playwright or an installed Google Chrome; `lighthouse` needs Chrome. If unavailable the audit still completes and adds a `tool.*` info finding with install instructions.