katman-mcp 0.1.0

package/dist/tools/method/core/lint.js

@@ -0,0 +1,556 @@
+// katman_lint_content: checks a page against the content rules (appendix D) and the P6/P7/P8 acceptance criteria.
+import path from "node:path";
+import { httpGet } from "../../../net.js";
+import { mdTable } from "../../../util.js";
+import { loadConfigSafe, loadResearchSafe, loadScan, readProjectFile, staticDirFor } from "../lib/state.js";
+import { brandSentence, containment, containsPhrase, countWords, escapeRegExp, hasNotX, isFilled, normPath, pct, splitSentences } from "../lib/text.js";
+import { HYPE_WORDS_EN, HYPE_WORDS_TR } from "../data/render.js";
+import { extractFile, extractHtml, extractMarkdown, firstSentences, leadText } from "./extract.js";
+import { parsePrices } from "./generate.js";
+import { brandNames } from "./research.js";
+import { situationUrl } from "./prompt.js";
+export const PAGE_TYPES_LINT = ["situation", "comparison", "pricing", "faq", "about", "single-question", "glossary", "tool", "home", "other"];
+const PREAMBLE_RE = /^(welcome to|in today['’]s|in this (article|post|guide)|are you looking|have you ever|looking for|when it comes to|in the world of|hoş geldiniz|günümüzde|bu yazıda|bu makalede|merhaba)/i;
+const PLACEHOLDER_RE = /\[(?:FILL|DOLDUR)[^\]]*\]|\bTODO\b|\bTBD\b|lorem ipsum|\bXXX\b|\{\{\s*\w+\s*\}\}/i;
+const NOT_FOR_RE = /(not for|isn['’]t for|is not for|who shouldn['’]?t|not a (good )?fit|when not to use|skip it if|kimler için değil|kime uygun değil|uygun değil|kullanmayın)/i;
+const ALT_RE = /(alternatives?|compared|comparison|\bvs\.?\b|instead|other tools|other options|alternatif|karşılaştır|yerine|diğer araçlar)/i;
+const OWN_GAPS_RE = /(doesn['’]?t|does not|won['’]?t|can['’]?t|cannot|not for|limitations?|weakness|\bcons\b|missing|neyi yapmıyor|yapmaz|yapamaz|eksik|sınırlama|dezavantaj)/i;
+const SOURCE_MARK_RE = /(source|according to|survey|study|report|data from|measured|as of|kaynak|göre|ölçüm|araştırma|https?:\/\/|\[\d+\]|\b(19|20)\d{2}\b|\b\d{1,2}[./]\d{1,2}[./]\d{2,4}\b|\b(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)[a-z]*\b|\b(ocak|şubat|mart|nisan|mayıs|haziran|temmuz|ağustos|eylül|ekim|kasım|aralık)\b)/i;
+const CLAIM_NUM_RE = /(\d+(?:[.,]\d+)?\s?%|%\s?\d+|\b\d+(?:[.,]\d+)?\s?[x×]\b|\b\d{1,3}(?:[.,]\d{3})+\+?|\b\d+\+?\s+(?:users|customers|people|visitors|downloads|companies|teams|businesses|orders|sites|reviews|clients|installs|creators|members|kullanıcı|müşteri|kişi|ziyaretçi|şirket|indirme|yorum|site|üye))/i;
+const FREE_RE = /\b(free|for free|free of charge)\b|ücretsiz|bedava|\bgratis\b|kostenlos|gratuit/gi;
+const CURRENCY_NEAR = /[$€£₺]|\b(usd|eur|gbp|try|tl)\b/i;
+function stripQuotes(s) {
+    return s.replace(/“[^”]*”|"[^"]*"|«[^»]*»|„[^“]*“/g, " ");
+}
+function context(text, idx, len) {
+    const a = Math.max(0, idx - 40);
+    const b = Math.min(text.length, idx + len + 40);
+    return `…${text.slice(a, b).replace(/\s+/g, " ").trim()}…`;
+}
+/** A short quote of the block around a hit, with the hit marked. */
+function snippet(seg, idx, len) {
+    const a = Math.max(0, idx - 50);
+    const b = Math.min(seg.length, idx + len + 50);
+    const pre = a > 0 ? "…" : "";
+    const post = b < seg.length ? "…" : "";
+    return `“${pre}${seg.slice(a, idx)}**${seg.slice(idx, idx + len)}**${seg.slice(idx + len, b)}${post}”`.replace(/\s+/g, " ");
+}
+function isInternal(href, domain) {
+    const h = href.trim();
+    if (!h || h.startsWith("#") || /^(mailto|tel|javascript):/i.test(h))
+        return false;
+    if (/\.(png|jpe?g|gif|svg|webp|avif|css|js|ico|woff2?|mp4|mp3)(\?|$)/i.test(h))
+        return false;
+    if (h.startsWith("/") && !h.startsWith("//"))
+        return true;
+    if (!/^https?:\/\//i.test(h) && !h.startsWith("//"))
+        return !h.includes(":"); // relative link
+    if (!domain)
+        return false;
+    try {
+        const host = new URL(h.startsWith("//") ? "https:" + h : h).hostname.replace(/^www\./, "");
+        return host === domain || host.endsWith("." + domain);
+    }
+    catch {
+        return false;
+    }
+}
+function llmsBlockquote(llms) {
+    if (!llms)
+        return undefined;
+    const lines = llms.split(/\r?\n/);
+    const start = lines.findIndex((l) => /^>\s?/.test(l));
+    if (start < 0)
+        return undefined;
+    const out = [];
+    for (let i = start; i < lines.length && /^>\s?/.test(lines[i]); i++)
+        out.push(lines[i].replace(/^>\s?/, ""));
+    return out.join(" ").trim();
+}
+/** The part of the source that belongs to one entry: its table row, else its section (heading to next heading). */
+function sectionAround(raw, i, len) {
+    if (i < 0)
+        return "";
+    const lineStart = raw.lastIndexOf("\n", i) + 1;
+    const lineEnd = raw.indexOf("\n", i) < 0 ? raw.length : raw.indexOf("\n", i);
+    const line = raw.slice(lineStart, lineEnd);
+    if (/^\s*\|/.test(line) || /<\/?t[dr]\b/i.test(line))
+        return line;
+    const heads = [...raw.matchAll(/(^|\n)\s{0,3}#{1,6}\s|<h[1-6]\b|<(section|article|li|tr)\b/gi)].map((m) => (m.index ?? 0) + (m[1] ? m[1].length : 0));
+    const before = heads.filter((h) => h <= i).pop();
+    const after = heads.find((h) => h > i + len);
+    const start = before !== undefined && i - before < 1500 ? before : Math.max(0, i - 300);
+    const end = after !== undefined && after - i < 2500 ? after : Math.min(raw.length, i + 900);
+    return raw.slice(start, end);
+}
+export function lintPage(x, c) {
+    const checks = [];
+    const t = c.pageType;
+    const r = c.research;
+    const bs = brandSentence(r);
+    const names = r ? brandNames(r) : [];
+    const first = firstSentences(x);
+    const firstText = first.join(" ");
+    const isFileMode = x.source === "file";
+    const add = (ch) => checks.push(ch);
+    const answerTypes = ["situation", "single-question", "tool", "home", "pricing", "comparison", "other", "about", "glossary"];
+    // 1. first sentences answer on their own
+    if (answerTypes.includes(t)) {
+        if (!first.length) {
+            add({
+                id: "first-sentences",
+                label: "First 1–3 sentences answer on their own",
+                status: "fail",
+                detail: x.source === "url" ? "No paragraph text after the H1 in the server HTML — the text may be rendered by JavaScript." : "No paragraph text found after the H1.",
+                fix: "Put a short answer (what the customer brings → what you do → what they get → which fear is unnecessary) right under the H1 as plain text.",
+            });
+        }
+        else {
+            const long = first.filter((s) => countWords(s) > 35);
+            const pre = PREAMBLE_RE.test(first[0]);
+            const status = pre || countWords(first[0]) > 50 ? "fail" : long.length ? "warn" : "pass";
+            add({
+                id: "first-sentences",
+                label: "First 1–3 sentences answer on their own",
+                status,
+                detail: first.map((s, i) => `(${i + 1}) ${countWords(s)} words: “${s}”`).join(" "),
+                ...(status !== "pass"
+                    ? { fix: pre ? "Drop the preamble (“Welcome to…”, “In today's world…”): start with the answer itself." : "Split sentences over 35 words; each of the first three must make sense when quoted alone." }
+                    : {}),
+            });
+        }
+    }
+    // 2. key claim in the lead: the one sentence (else the situation) within the first ~200 characters after the H1
+    if (["situation", "home", "tool", "single-question"].includes(t) && first.length) {
+        const lead = leadText(x, 200);
+        const ref = bs ? { label: "the one sentence", text: bs } : c.situation ? { label: "the situation", text: c.situation.sentence } : undefined;
+        if (!ref) {
+            add({ id: "key-claim", label: "Key claim in the first ~200 characters", status: "skip", detail: "No one sentence or situation in research to compare with." });
+        }
+        else {
+            const score = Math.max(containment(ref.text, lead), containment(ref.text, firstText));
+            const threshold = t === "home" ? 0.6 : 0.4;
+            const status = score >= threshold ? "pass" : score >= threshold / 2 ? "warn" : "fail";
+            add({
+                id: "key-claim",
+                label: "Key claim in the first ~200 characters",
+                status,
+                detail: `${pct(score)} of ${ref.label}'s words appear right after the H1 (target ≥ ${pct(threshold)}).`,
+                ...(status !== "pass" ? { fix: `Open with ${bs ? `the one sentence, tailored to the page (“${bs}”)` : "the answer to the situation"}${c.situation ? ` for “${c.situation.sentence}”` : ""}, within the first ~200 characters.` } : {}),
+            });
+        }
+    }
+    // 3. H1
+    if (!x.h1.length) {
+        add({ id: "h1", label: "H1 present", status: t === "other" ? "warn" : "fail", detail: "No H1 found.", fix: t === "situation" ? "Make the H1 the customer's own sentence." : "Add one H1 that states the page's question or topic." });
+    }
+    else if (t === "situation" && c.situation) {
+        const score = containment(c.situation.sentence, x.h1[0]);
+        const branded = names.some((n) => containsPhrase(x.h1[0], n));
+        const status = score >= 0.5 && !branded ? "pass" : "warn";
+        add({
+            id: "h1",
+            label: "H1 is the customer's own sentence",
+            status,
+            detail: `H1 “${x.h1[0]}” — ${pct(score)} of the situation's words${branded ? "; contains the brand name" : ""}.`,
+            ...(status !== "pass" ? { fix: `Use the customer's sentence as the H1: “${c.situation.sentence}” (no brand name; the URL uses the same words).` } : {}),
+        });
+    }
+    else {
+        add({ id: "h1", label: "H1 present", status: "pass", detail: `“${x.h1[0]}”${x.h1.length > 1 ? ` (+${x.h1.length - 1} more; fine for Google, but one is tidier)` : ""}` });
+    }
+    // 4. one-sentence consistency (page / meta description / llms.txt vs research)
+    if (["home", "about", "situation", "pricing", "other", "tool"].includes(t)) {
+        if (!bs) {
+            add({ id: "one-sentence", label: "One sentence matches research and llms.txt", status: "skip", detail: "Research has no one sentence yet (katman_research: brand.oneLiner)." });
+        }
+        else {
+            const firstPara = firstText || x.blocks.slice(x.afterH1, x.afterH1 + 2).join(" ");
+            const page = containment(bs, firstPara);
+            const meta = x.description !== undefined ? containment(bs, x.description) : undefined;
+            const quote = llmsBlockquote(c.llmsTxt);
+            const llms = quote !== undefined ? containment(bs, quote) : undefined;
+            const parts = [`page lead ${pct(page)}`, meta !== undefined ? `meta description ${pct(meta)}` : "meta description not found", llms !== undefined ? `llms.txt ${pct(llms)}` : c.llmsTxt ? "llms.txt has no > quote line" : "no llms.txt found"];
+            let status;
+            if (t === "home")
+                status = page >= 0.7 && (meta === undefined || meta >= 0.7) ? "pass" : page < 0.4 ? "fail" : "warn";
+            else
+                status = page >= 0.5 || (meta ?? 0) >= 0.5 ? "pass" : "warn";
+            if (llms !== undefined && llms < 0.9 && status === "pass")
+                status = "warn";
+            const fixes = [];
+            if (page < (t === "home" ? 0.7 : 0.5))
+                fixes.push(`put the one sentence in the first paragraph (“${bs}”)`);
+            if (meta !== undefined && meta < 0.7)
+                fixes.push("use the same sentence as the meta description");
+            if (llms !== undefined && llms < 0.9)
+                fixes.push("regenerate llms.txt so its > line is the same sentence (katman_generate llms.txt)");
+            add({ id: "one-sentence", label: "One sentence matches research and llms.txt", status, detail: `Share of the research sentence's words found: ${parts.join(" · ")}.`, ...(fixes.length ? { fix: fixes.join("; ") + "." } : {}) });
+        }
+    }
+    // 5. hype words (outside quotes)
+    const segments = [x.title ?? "", ...x.headings.map((h) => h.text), ...x.blocks].filter(Boolean).map(stripQuotes);
+    {
+        const hits = [];
+        const res = [...HYPE_WORDS_EN, ...HYPE_WORDS_TR].map((w) => w.startsWith("#") ? new RegExp(escapeRegExp(w) + "(?!\\d)", "gi") : new RegExp(`(^|[^\\p{L}\\p{N}])${escapeRegExp(w)}(?=$|[^\\p{L}\\p{N}])`, "giu"));
+        for (const seg of segments) {
+            for (const re of res) {
+                for (const m of seg.matchAll(re)) {
+                    const at = m.index ?? 0;
+                    if (/best practices?/i.test(seg.slice(at, at + 20)))
+                        continue;
+                    hits.push(snippet(seg, at + (m[1]?.length ?? 0), m[0].length - (m[1]?.length ?? 0)));
+                }
+            }
+            if (hits.length >= 6)
+                break;
+        }
+        const status = !hits.length ? "pass" : hits.length >= 3 ? "fail" : "warn";
+        add({
+            id: "hype",
+            label: "No hype words",
+            status,
+            detail: hits.length ? `${hits.length} found: ${hits.slice(0, 4).join(" | ")}` : "None found.",
+            ...(hits.length ? { fix: "Replace quality words (best, perfect, #1, en iyi, mükemmel…) with a concrete, sourced fact — or a quote from someone else, in quotation marks." } : {}),
+        });
+    }
+    // 6. numbers without a nearby source/date
+    {
+        const unsourced = [];
+        const blocks = x.blocks.length ? x.blocks : [x.text];
+        for (const b of blocks) {
+            const ss = splitSentences(b);
+            for (let i = 0; i < ss.length; i++) {
+                const s = ss[i];
+                const m = CLAIM_NUM_RE.exec(s);
+                if (!m)
+                    continue;
+                if (CURRENCY_NEAR.test(s.slice(Math.max(0, (m.index ?? 0) - 3), (m.index ?? 0) + m[0].length + 3)))
+                    continue;
+                if (SOURCE_MARK_RE.test(s) || (ss[i + 1] && SOURCE_MARK_RE.test(ss[i + 1])))
+                    continue;
+                unsourced.push(`“${s.length > 140 ? s.slice(0, 137) + "…" : s}”`);
+                if (unsourced.length >= 6)
+                    break;
+            }
+            if (unsourced.length >= 6)
+                break;
+        }
+        const status = !unsourced.length ? "pass" : unsourced.length >= 3 ? "fail" : "warn";
+        add({
+            id: "numbers",
+            label: "Numbers have a source or a date",
+            status,
+            detail: unsourced.length ? `${unsourced.length} claim(s) without a nearby source or date: ${unsourced.slice(0, 4).join(" ")}` : "No unsourced percentages, multipliers or counts found.",
+            ...(unsourced.length ? { fix: "Next to every number: its source (link) and date — only numbers that are in research.proof. If the test was small, say so; otherwise remove the number." } : {}),
+        });
+    }
+    // 7. placeholders
+    {
+        const hay = `${x.title ?? ""}\n${x.description ?? ""}\n${x.headings.map((h) => h.text).join("\n")}\n${x.text}`;
+        const m = PLACEHOLDER_RE.exec(hay);
+        add({
+            id: "placeholders",
+            label: "No placeholders left",
+            status: m ? "fail" : "pass",
+            detail: m ? `Found ${context(hay, m.index, m[0].length)}` : "No [FILL], [DOLDUR], TODO or lorem ipsum.",
+            ...(m ? { fix: "Fill every placeholder from research, or ask the user; never publish a page with [FILL]." } : {}),
+        });
+    }
+    // 8. "free" for a paid product
+    {
+        const pricing = isFilled(r?.brand.pricing) ? r.brand.pricing : undefined;
+        if (!pricing) {
+            add({ id: "free", label: "No “free” for a paid product", status: "skip", detail: "No pricing in research to compare with." });
+        }
+        else if (/\bfree\b|ücretsiz|bedava|gratis|\$\s?0\b|\b0\s?(usd|\$|€|£|tl)/i.test(pricing)) {
+            add({ id: "free", label: "No “free” for a paid product", status: "pass", detail: `Research pricing mentions a free option (“${pricing}”).` });
+        }
+        else {
+            // "free" next to a tool/resource word (free VAT calculator, free checker, free guide, ücretsiz araç) is a
+            // genuinely free side offer, which the method recommends (free tools are link magnets): not a violation.
+            const FREE_SIDE_OFFER = /^\W{0,3}(?:\p{L}+[\s-]+){0,3}?(?:tool|tools|finder|checker|calculator|counter|generator|guide|book|ebook|pdf|template|templates|course|webinar|audit|test|trial|plan|tier|version|download|araç|araçlar|araci|aracı|bulucu|hesaplayıcı|sayacı|rehber|kitap|şablon|deneme|sürüm|plan)\b/iu;
+            const hits = [];
+            for (const seg of [...segments, stripQuotes(x.description ?? "")]) {
+                for (const m of seg.matchAll(FREE_RE)) {
+                    const after = seg.slice((m.index ?? 0) + m[0].length, (m.index ?? 0) + m[0].length + 60);
+                    if (FREE_SIDE_OFFER.test(after))
+                        continue;
+                    if (hits.length < 4)
+                        hits.push(snippet(seg, m.index ?? 0, m[0].length));
+                }
+            }
+            add({
+                id: "free",
+                label: "No “free” for a paid product",
+                status: hits.length ? "fail" : "pass",
+                detail: hits.length
+                    ? `Research pricing is paid (“${pricing}”) but the page says “free” (not about a free tool, guide, trial or plan): ${hits.join(" | ")}`
+                    : "The page doesn't call the paid product free (free tools, guides and trials are fine).",
+                ...(hits.length ? { fix: "If this calls the paid product free, remove it (appendix D); if it's a genuinely free tool, trial or plan, say exactly what is free." } : {}),
+            });
+        }
+    }
+    // 9. update date
+    if (["situation", "comparison", "single-question", "tool", "other", "pricing", "glossary"].includes(t)) {
+        add({
+            id: "updated",
+            label: "Update date visible",
+            status: x.hasDate ? "pass" : t === "comparison" ? "fail" : "warn",
+            detail: x.hasDate ? "An update date / dateModified was found." : "No “Updated …” date or dateModified found.",
+            ...(x.hasDate ? {} : { fix: "Show “Updated: <date> · <author>” at the bottom, and change it only when the words change (the sample site's pages all carried the launch date)." }),
+        });
+    }
+    // 10. FAQ 5–8
+    {
+        const n = x.faqQuestions.length;
+        if (["situation", "tool"].includes(t)) {
+            const status = n >= 5 && n <= 8 ? "pass" : n === 0 ? "fail" : "warn";
+            add({ id: "faq", label: "FAQ with 5–8 questions", status, detail: `${n} question(s) found${n ? `: ${x.faqQuestions.slice(0, 3).map((q) => `“${q}”`).join(", ")}${n > 3 ? "…" : ""}` : ""}.`, ...(status !== "pass" ? { fix: "An FAQ block with 5–8 questions in the customer's words; each answer's first sentence is the answer." } : {}) });
+        }
+        else if (t === "faq") {
+            add({ id: "faq", label: "At least 5 real questions", status: n >= 5 ? "pass" : "warn", detail: `${n} question(s) found.`, ...(n >= 5 ? {} : { fix: "Use the customers' real questions (support e-mails, sales calls)." }) });
+        }
+        else if (n) {
+            add({ id: "faq", label: "FAQ", status: "pass", detail: `${n} question(s) found.` });
+        }
+    }
+    // 11. not-for section
+    if (["situation", "tool"].includes(t)) {
+        const hay = `${x.headings.map((h) => h.text).join("\n")}\n${x.text}`;
+        const ok = NOT_FOR_RE.test(hay);
+        add({ id: "not-for", label: "“Who it's not for” section", status: ok ? "pass" : t === "situation" ? "fail" : "warn", detail: ok ? "Found." : "No “not for” section found.", ...(ok ? {} : { fix: "Add “Who it's not for” with 2–3 honest bullets: assistants quote one-sided pages less." }) });
+    }
+    // 12. alternatives
+    if (["situation", "comparison"].includes(t)) {
+        const hay = `${x.headings.map((h) => h.text).join("\n")}\n${x.text}`;
+        const compNames = (r?.competitors ?? []).map((cc) => cc.name).filter((n) => containsPhrase(hay, n));
+        const ok = ALT_RE.test(hay) || compNames.length >= 2;
+        add({
+            id: "alternatives",
+            label: "Alternatives named honestly",
+            status: ok ? "pass" : t === "comparison" ? "fail" : "warn",
+            detail: ok ? `Found${compNames.length ? ` (competitors named: ${compNames.join(", ")})` : ""}.` : "No alternatives section and fewer than 2 competitors named.",
+            ...(ok ? {} : { fix: "Add “Alternatives” naming the competitors from research and whom each one fits (facts from their own sites, with dates)." }),
+        });
+    }
+    // 13–15. comparison-specific
+    if (t === "comparison") {
+        const raw = x.raw;
+        const comps = (r?.competitors ?? []).filter((cc) => containsPhrase(raw, cc.name));
+        if (!comps.length) {
+            add({ id: "competitor-sources", label: "A source and a date next to every competitor", status: "warn", detail: "None of the research competitors appear on the page.", fix: "Cover the competitors in research (P7), each with its source link and the date you checked." });
+        }
+        else {
+            const lacking = [];
+            for (const cc of comps) {
+                const i = raw.search(new RegExp(escapeRegExp(cc.name), "i"));
+                const win = sectionAround(raw, i, cc.name.length);
+                const hasSrc = /https?:\/\/|href=|\]\(/.test(win);
+                const hasDate = /\b(19|20)\d{2}-\d{2}(-\d{2})?\b|\b\d{1,2}[./]\d{1,2}[./]\d{2,4}\b|\b(checked|as of|kontrol)\b|\b(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)[a-z]* \d{1,2},? \d{4}\b/i.test(win);
+                if (!hasSrc || !hasDate)
+                    lacking.push(`${cc.name}${!hasSrc ? " (no source link)" : ""}${!hasDate ? " (no date)" : ""}`);
+            }
+            add({ id: "competitor-sources", label: "A source and a date next to every competitor", status: lacking.length ? "fail" : "pass", detail: lacking.length ? `Missing: ${lacking.join("; ")}.` : `All ${comps.length} named competitors have a source and a date nearby.`, ...(lacking.length ? { fix: "Next to each competitor fact: a link to its own page and the date you checked it (a comparison once said a competitor “can't” do what it could)." } : {}) });
+        }
+        const brand = names[0];
+        if (brand) {
+            const i = raw.search(new RegExp(escapeRegExp(brand), "i"));
+            const win = i >= 0 ? sectionAround(raw, i, brand.length) : "";
+            const ok = i >= 0 && OWN_GAPS_RE.test(win);
+            add({ id: "own-gaps", label: "Our own gaps are written down", status: ok ? "pass" : "fail", detail: ok ? "The entry for us says what it doesn't do." : i < 0 ? "The brand isn't on the page." : "No “what it doesn't do” near the brand's entry.", ...(ok ? {} : { fix: "Write “who it fits” and “what it doesn't do” for us too (P7)." }) });
+            const productHeads = x.headings.filter((h) => h.level >= 2 && h.level <= 3 && (containsPhrase(h.text, brand) || (r?.competitors ?? []).some((cc) => containsPhrase(h.text, cc.name))));
+            if (productHeads.length >= 2) {
+                const firstIsUs = containsPhrase(productHeads[0].text, brand);
+                add({ id: "brand-not-first", label: "Brand not ranked first", status: firstIsUs ? "fail" : "pass", detail: `First tool heading: “${productHeads[0].text}”.`, ...(firstIsUs ? { fix: "Don't put yourself first: self-ranked lists backfire (the brand was left out 69% of the time when its own list was cited) and carry spam-policy risk." } : {}) });
+            }
+        }
+    }
+    // 16. pricing matches research
+    if (t === "pricing" || t === "home") {
+        const pricing = isFilled(r?.brand.pricing) ? r.brand.pricing : undefined;
+        const prices = pricing ? parsePrices(pricing) : [];
+        if (!prices.length) {
+            if (t === "pricing")
+                add({ id: "pricing-match", label: "Prices match research and llms.txt", status: "skip", detail: pricing ? `No amounts could be read from research pricing (“${pricing}”).` : "No pricing in research." });
+        }
+        else {
+            const text = x.text.replace(/\s+/g, " ");
+            const missing = prices.filter((p) => !new RegExp(`(^|[^\\d])${escapeRegExp(String(p.price))}([.,]0+)?([^\\d]|$)`).test(text));
+            add({ id: "pricing-match", label: "Prices match research and llms.txt", status: missing.length ? (t === "pricing" ? "fail" : "warn") : "pass", detail: missing.length ? `Not on the page: ${missing.map((p) => `${p.price} ${p.currency}`).join(", ")} (research: “${pricing}”).` : "Every research price appears on the page.", ...(missing.length ? { fix: "Prices come from one source: make the page, research, llms.txt and schema say the same thing." } : {}) });
+        }
+    }
+    // 17. not-X on About
+    if (t === "about") {
+        if (hasNotX(r?.brand.notX)) {
+            const score = containment(r.brand.notX, x.text);
+            add({ id: "not-x", label: "Not-X note on the page", status: score >= 0.6 ? "pass" : "warn", detail: `${pct(score)} of the not-X note's words found.`, ...(score >= 0.6 ? {} : { fix: `Say it plainly on About (and FAQ, llms.txt, Organization schema): “${r.brand.notX}”.` }) });
+        }
+        else
+            add({ id: "not-x", label: "Not-X note on the page", status: "skip", detail: "Research has no not-X note (fine if the brand isn't confused with anything)." });
+    }
+    // 18. internal links
+    {
+        const pool = x.contentLinks ?? x.links;
+        const internal = pool.filter((h) => isInternal(h, c.siteDomain));
+        const all = x.links.filter((h) => isInternal(h, c.siteDomain));
+        const need = ["situation", "comparison", "single-question", "tool", "home"].includes(t) ? 3 : 1;
+        const n = new Set(internal).size;
+        let status = n >= need ? "pass" : n === 0 && need > 1 ? "fail" : "warn";
+        let detail = `${n} internal link(s) in the content${x.contentLinks && all.length > internal.length ? ` (${new Set(all).size} including navigation)` : ""}.`;
+        if (x.kind === "jsx" && !x.links.length) {
+            status = "warn";
+            detail = "No <a>/<Link> found in the source (links may come from shared components).";
+        }
+        add({ id: "internal-links", label: `≥${need} internal link${need > 1 ? "s" : ""}`, status, detail, ...(status !== "pass" ? { fix: "Link 3–5 related pages with descriptive anchor text (not “click here”), and make sure other pages link here too." } : {}) });
+    }
+    // 19. title length
+    if (x.title !== undefined) {
+        const len = x.title.length;
+        const status = len <= 60 ? "pass" : len <= 70 ? "warn" : "fail";
+        let detail = `${len} characters: “${x.title}”.`;
+        let fix = status !== "pass" ? "About 60 characters; the situation first, then the brand (drop the brand suffix if it goes over)." : undefined;
+        if (t === "situation" && c.situation && containment(c.situation.sentence, x.title) < 0.4) {
+            detail += " It doesn't start from the situation.";
+            fix = `Start the title with the situation (“${c.situation.sentence}”), then the brand.`;
+        }
+        add({ id: "title", label: "Title ≈60 characters", status: fix && status === "pass" ? "warn" : status, detail, ...(fix ? { fix } : {}) });
+    }
+    else if (!isFileMode) {
+        add({ id: "title", label: "Title ≈60 characters", status: "fail", detail: "No <title> in the HTML.", fix: "Add a unique <title> (P3)." });
+    }
+    // 20. meta description length
+    if (x.description !== undefined) {
+        const len = x.description.length;
+        const status = len >= 150 && len <= 160 ? "pass" : len < 70 ? "fail" : "warn";
+        add({ id: "description", label: "Meta description 150–160 characters", status, detail: `${len} characters.`, ...(status !== "pass" ? { fix: len > 160 ? "Cut it at the last full sentence within 160 characters." : "Write the one sentence as the description, about 150–160 characters." } : {}) });
+    }
+    else if (!isFileMode) {
+        add({ id: "description", label: "Meta description 150–160 characters", status: "fail", detail: "No meta description in the HTML.", fix: "Add a unique meta description built from the one sentence (P3)." });
+    }
+    // 21. URL mode: JS-off text, robots meta, JSON-LD
+    if (x.source === "url") {
+        const w = x.wordsJsOff ?? 0;
+        // lead-approved thresholds: < 50 words = text is in JavaScript (critical); 50–99 = thin page
+        const jsStatus = w < 50 ? "fail" : w < 100 ? "warn" : w < 250 && t === "situation" ? "warn" : "pass";
+        add({
+            id: "js-off",
+            label: "Text visible without JavaScript",
+            status: jsStatus,
+            detail: `${w} words in the raw HTML (what OAI-SearchBot and other AI crawlers see)${w < 50 ? ": almost nothing to read — the text is rendered by JavaScript, or the page is nearly empty" : w < 100 ? ": a thin page" : ""}.`,
+            ...(jsStatus !== "pass" ? { fix: w < 50 ? "If the text is rendered by JavaScript, render it on the server or prerender it (P2) — AI crawlers don't run JavaScript; otherwise write the answer as plain HTML text." : "Add the missing written blocks as plain HTML text (how it works, not-for, alternatives, FAQ)." } : {}),
+        });
+        if (x.robotsMeta && /noindex|nosnippet|none/i.test(x.robotsMeta)) {
+            add({ id: "robots-meta", label: "No unwanted noindex / nosnippet", status: "fail", detail: `meta robots: “${x.robotsMeta}”.`, fix: "Remove noindex/nosnippet from pages you want found and quoted (nosnippet keeps AI Overviews from citing the page)." });
+        }
+        if (x.jsonLdErrors)
+            add({ id: "schema", label: "JSON-LD is valid JSON", status: "fail", detail: `${x.jsonLdErrors} block(s) don't parse.`, fix: "Generate JSON-LD with JSON.stringify from the page data (P5)." });
+    }
+    // 22. thin page
+    if (["situation", "comparison", "single-question"].includes(t)) {
+        const words = countWords(x.text);
+        if (words < 250)
+            add({ id: "length", label: "Enough text to answer", status: "warn", detail: `${words} words in the content.`, fix: "Add the missing blocks (how it works, not-for, alternatives, FAQ) rather than filler." });
+    }
+    return checks;
+}
+async function findLlms(root, staticDir, llmsPath) {
+    const candidates = [llmsPath, staticDir ? `${staticDir}/llms.txt` : "llms.txt", "public/llms.txt", "static/llms.txt", "llms.txt"].filter(Boolean);
+    for (const c of [...new Set(candidates)]) {
+        const f = await readProjectFile(root, c, 500_000);
+        if (f.text !== undefined)
+            return f.text;
+    }
+    return undefined;
+}
+export async function runLint(root, args) {
+    const [research, config, scan] = await Promise.all([loadResearchSafe(root), loadConfigSafe(root), loadScan(root)]);
+    let x;
+    let pagePath;
+    if (args.file) {
+        const f = await readProjectFile(root, args.file);
+        if (f.text === undefined)
+            return { text: `Can't read ${args.file}: ${f.error}`, isError: true };
+        x = extractFile(f.text, args.file, path.extname(args.file).toLowerCase());
+        if (path.basename(args.file).toLowerCase() === "llms.txt")
+            x.notes.push("This is llms.txt: the one-sentence and placeholder checks matter most here.");
+    }
+    else if (args.url) {
+        let u;
+        try {
+            u = new URL(/^https?:\/\//i.test(args.url) ? args.url : `https://${args.url}`);
+        }
+        catch {
+            return { text: `"${args.url}" isn't a valid URL.`, isError: true };
+        }
+        const res = await httpGet(u.toString(), { redirect: "follow", timeoutMs: 20000 });
+        if (res.error || !res.status)
+            return { text: `Couldn't fetch ${u}: ${res.error ?? "no response"}.`, isError: true };
+        const ct = res.headers["content-type"] ?? "";
+        x = /html/i.test(ct) || /<html|<body/i.test(res.body.slice(0, 2000)) ? extractHtml(res.body, u.toString(), "url") : extractMarkdown(res.body, u.toString(), "url");
+        x.status = res.status;
+        if (x.kind !== "html")
+            x.wordsJsOff = countWords(res.body);
+        pagePath = normPath(u.pathname);
+    }
+    else if (args.text) {
+        x = extractMarkdown(args.text, "text", "text");
+    }
+    else {
+        return { text: "Pass one of: file (path in the project), url (a live page) or text (the page copy).", isError: true };
+    }
+    // situation: by id, by URL, or by H1 similarity
+    let situation;
+    if (args.situationId) {
+        situation = research?.situations.find((s) => s.id === args.situationId);
+        if (!situation)
+            return { text: `Situation "${args.situationId}" not found in research (${(research?.situations ?? []).map((s) => s.id).join(", ") || "none"}).`, isError: true };
+    }
+    else if (research?.situations.length && (args.pageType === "situation" || !args.pageType)) {
+        if (pagePath)
+            situation = research.situations.find((s) => normPath(situationUrl(s, research.site.languages)) === pagePath);
+        if (!situation && x.h1[0]) {
+            const best = research.situations.map((s) => ({ s, score: containment(s.sentence, x.h1[0]) })).sort((a, b) => b.score - a.score)[0];
+            if (best && best.score >= 0.5)
+                situation = best.s;
+        }
+    }
+    const pageType = args.pageType ?? (situation ? "situation" : "other");
+    const staticDir = staticDirFor(root, scan).dir;
+    let llmsTxt = await findLlms(root, staticDir, scan?.files.llms.path);
+    if (!llmsTxt && args.url) {
+        try {
+            const res = await httpGet(new URL("/llms.txt", args.url.startsWith("http") ? args.url : `https://${args.url}`).toString(), { redirect: "follow", timeoutMs: 10000 });
+            if (res.status === 200 && !/<html/i.test(res.body.slice(0, 500)))
+                llmsTxt = res.body;
+        }
+        catch {
+            // ignore
+        }
+    }
+    const domain = research && isFilled(research.site.domain) ? research.site.domain : config.siteUrl ? new URL(config.siteUrl).hostname.replace(/^www\./, "") : pagePath && args.url ? new URL(args.url.startsWith("http") ? args.url : `https://${args.url}`).hostname.replace(/^www\./, "") : undefined;
+    const checks = lintPage(x, { pageType, research, situation, llmsTxt, siteDomain: domain });
+    if (x.source === "url" && x.status && x.status !== 200)
+        checks.unshift({ id: "status", label: "Returns 200", status: "fail", detail: `HTTP ${x.status}.`, fix: "Public pages must return 200 (P14)." });
+    const counts = { pass: 0, warn: 0, fail: 0, skip: 0 };
+    for (const ch of checks)
+        counts[ch.status]++;
+    const icon = { pass: "PASS", warn: "WARN", fail: "FAIL", skip: "skip" };
+    const fixes = checks.filter((ch) => ch.fix && (ch.status === "fail" || ch.status === "warn"));
+    const parts = [
+        `# Content check: ${x.label}`,
+        `Page type: **${pageType}**${situation ? ` · situation \`${situation.id}\` “${situation.sentence}”` : ""} · ${counts.pass} pass · ${counts.warn} warn · ${counts.fail} fail${counts.skip ? ` · ${counts.skip} skipped` : ""}`,
+        mdTable(["Check", "Result", "Details"], checks.map((ch) => [ch.label, icon[ch.status], ch.detail])),
+    ];
+    if (fixes.length)
+        parts.push(`## Fixes\n${fixes.map((f, i) => `${i + 1}. **${f.label}** — ${f.fix}`).join("\n")}`);
+    if (!research)
+        parts.push("No research yet: the one-sentence, pricing and situation checks were skipped. Run katman_research.");
+    if (x.notes.length)
+        parts.push(x.notes.map((n) => `_${n}_`).join("\n"));
+    parts.push(counts.fail ? "Fix every FAIL, then run katman_lint_content again. Don't tick the task until it passes." : "No failures. After deploy, verify the live page with katman_audit_site (urls mode).");
+    return {
+        text: parts.join("\n\n"),
+        structured: { pageType, situationId: situation?.id ?? null, counts, checks: checks.map(({ id, label, status, detail, fix }) => ({ id, label, status, detail, ...(fix ? { fix } : {}) })) },
+    };
+}