katman-mcp 0.1.0

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

@@ -0,0 +1,196 @@
+import { isFilled } from "../lib/text.js";
+function langName(code, inLang) {
+    try {
+        const n = new Intl.DisplayNames([inLang], { type: "language" }).of(code);
+        if (n && n.toLowerCase() !== code.toLowerCase())
+            return n;
+    }
+    catch {
+        // fall through
+    }
+    return code;
+}
+const THE_COUNTRIES = /^(United |Netherlands|Philippines|Czech Republic|Dominican Republic|Bahamas|Gambia|Maldives)/;
+function countryName(c, inLang) {
+    const s = c.trim();
+    let name = s;
+    if (/^[A-Za-z]{2}$/.test(s)) {
+        try {
+            name = new Intl.DisplayNames([inLang], { type: "region" }).of(s.toUpperCase()) ?? s;
+        }
+        catch {
+            name = s;
+        }
+    }
+    return inLang === "en" && THE_COUNTRIES.test(name) ? `the ${name}` : name;
+}
+/** "/import-pdf-invoices" → "import pdf invoices" (a verb phrase in most situation slugs). */
+export function jobFromUrl(url) {
+    if (!url)
+        return undefined;
+    const last = url.replace(/\/+$/, "").split("/").pop() ?? "";
+    const words = last.split("-").filter((w) => /[a-z]/i.test(w));
+    return words.length >= 2 ? words.join(" ") : undefined;
+}
+/** Lowercase the first letter of a normal word ("Invoice app" → "invoice app") but keep acronyms ("AI tool"). */
+export function lowerFirst(s) {
+    return /^\p{Lu}\p{Ll}/u.test(s) ? s.charAt(0).toLowerCase() + s.slice(1) : s;
+}
+function asQuestion(sentence, T) {
+    const s = sentence.trim();
+    if (/\?\s*$/.test(s))
+        return s;
+    const withStop = /[.!…]$/.test(s) ? s : s + ".";
+    return T === "tr" ? `${withStop} Bu konuda yardımcı olan bir site var mı?` : `${withStop} Is there a website that can help me with this?`;
+}
+const LANG_HINTS = {
+    tr: /[ğşıİ]|\b(ve|bir|ama|için|nasıl|istiyorum|yapmak|yok|mı|mi|mu|benim|değil)\b/i,
+    en: /\b(i|i'm|my|have|but|want|can't|cannot|how|the|and|is there)\b/i,
+    de: /ß|\b(ich|und|nicht|mein|meine|ein|eine|kann|wie|habe)\b/i,
+    es: /ñ|¿|\b(tengo|pero|quiero|cómo|una|para|puedo|mi)\b/i,
+    fr: /\b(je|j'ai|mais|pas|mon|une|pour|comment|peux)\b/i,
+    it: /\b(ho|ma|voglio|come|una|per|posso|il mio)\b/i,
+    pt: /ã|õ|\b(tenho|mas|quero|como|uma|para|posso|meu)\b/i,
+};
+/** Which of the site's languages a situation sentence is written in (defaults to the primary language). */
+export function detectLang(sentence, langs) {
+    const primary = langs[0] ?? "en";
+    let best = primary;
+    let bestScore = 0;
+    for (const l of langs) {
+        const re = LANG_HINTS[l.split("-")[0]];
+        if (!re)
+            continue;
+        const score = (sentence.match(new RegExp(re.source, "gi")) ?? []).length;
+        if (score > bestScore) {
+            best = l;
+            bestScore = score;
+        }
+    }
+    return best;
+}
+function diagnostics(r, T, lang, idPrefix) {
+    const out = [];
+    if (!isFilled(r.brand.name))
+        return out;
+    const b = r.brand.name.trim();
+    out.push({ id: `${idPrefix}t1`, type: "diagnostic", text: T === "tr" ? `${b} nedir?` : `What is ${b}?`, lang });
+    if (isFilled(r.site.domain))
+        out.push({ id: `${idPrefix}t2`, type: "diagnostic", text: T === "tr" ? `${b} (${r.site.domain}) nedir?` : `What is ${b} (${r.site.domain})?`, lang });
+    return out;
+}
+function primarySet(r, sits, lang, now, notes) {
+    const base = lang.split("-")[0];
+    const T = base === "tr" ? "tr" : "en";
+    const year = now.getUTCFullYear();
+    const category = isFilled(r.brand.category) ? r.brand.category.trim() : T === "tr" ? "araç" : "tool";
+    const cat = lowerFirst(category);
+    const comps = r.competitors.filter((c) => isFilled(c.name)).map((c) => c.name.trim());
+    const job = T === "en" ? sits.map((s) => jobFromUrl(s.url)).find(Boolean) : undefined;
+    const qs = [];
+    // 1–3 situation
+    const top = sits.slice(0, 3);
+    for (const s of top)
+        qs.push({ type: "situation", text: asQuestion(s.sentence, T) });
+    if (top.length < 3)
+        notes.push(`Only ${top.length} situation(s) in ${lang}: add more and regenerate (the set needs 3 situation questions).`);
+    // 4–5 tool
+    if (T === "tr") {
+        qs.push({ type: "tool", text: `Hangi ${cat} kullanmalıyım?` });
+        const s2 = sits[3] ?? sits[0];
+        qs.push({ type: "tool", text: s2 ? `"${s2.sentence.replace(/[.?!]+$/, "")}" için hangi aracı kullanabilirim?` : `Hangi ${cat} öneriliyor?` });
+    }
+    else {
+        qs.push({ type: "tool", text: `Which ${cat} should I use?` });
+        qs.push({ type: "tool", text: job ? `Which tool can ${job}?` : `What ${cat} do people recommend?` });
+    }
+    // 6–7 best
+    if (T === "tr")
+        qs.push({ type: "best", text: `en iyi ${cat} ${year}` }, { type: "best", text: `En iyi ${cat} hangisi?` });
+    else
+        qs.push({ type: "best", text: `best ${cat} ${year}` }, { type: "best", text: `What is the best ${cat}?` });
+    // 8–9 alternative
+    const [c1, c2] = comps;
+    if (!c1)
+        notes.push("No competitors in research: the alternative questions are generic. Add the names assistants recommend and regenerate.");
+    if (T === "tr") {
+        qs.push({ type: "alternative", text: c1 ? `${c1} alternatifleri` : `Büyük ${cat} markalarına alternatifler neler?` });
+        qs.push({ type: "alternative", text: c2 ? `${c2} alternatifleri` : c1 ? `${year} için ${c1} alternatifleri` : `${category} alternatifleri` });
+    }
+    else {
+        qs.push({ type: "alternative", text: c1 ? (job ? `${c1} alternatives that can ${job}` : `${c1} alternatives`) : `alternatives to the big ${cat} brands` });
+        qs.push({ type: "alternative", text: c2 ? `${c2} alternatives` : c1 ? `${c1} alternatives in ${year}` : `${cat} alternatives` });
+    }
+    // 10–11 market / language
+    const langs = r.site.languages.length ? r.site.languages : [lang];
+    const l0 = langName(langs[0], T);
+    const l1 = langs[1] ? langName(langs[1], T) : undefined;
+    const country = isFilled(r.brand.country) ? countryName(r.brand.country, T) : undefined;
+    if (T === "tr") {
+        qs.push({ type: "market", text: `${l0} için en iyi ${cat} hangisi?` });
+        qs.push({ type: "market", text: l1 ? `${l1} için en iyi ${cat} hangisi?` : country ? `${country} için en iyi ${cat}` : `${l0} destekleyen ${cat}` });
+    }
+    else {
+        qs.push({ type: "market", text: `Which ${cat} works best in ${l0}?` });
+        qs.push({ type: "market", text: l1 ? `Which ${cat} works best in ${l1}?` : country ? `best ${cat} in ${country}` : `${cat} that supports ${l0}` });
+    }
+    // 12 problem
+    const ps = sits[3] ?? sits[0];
+    if (T === "tr")
+        qs.push({ type: "problem", text: ps ? `Şunu nasıl çözerim: "${ps.sentence.replace(/[.?!]+$/, "")}"?` : `Doğru ${cat} nasıl seçilir?` });
+    else
+        qs.push({ type: "problem", text: job ? `How do I ${job}?` : ps ? `How do I solve this: "${ps.sentence.replace(/[.?!]+$/, "")}"?` : `How do I choose a ${cat}?` });
+    const questions = qs.map((q, i) => ({ id: `q${i + 1}`, type: q.type, text: q.text, lang }));
+    const diag = diagnostics(r, T, lang, "");
+    if (!isFilled(r.brand.name))
+        notes.push("No brand name yet: the two diagnostic questions were skipped.");
+    else if (diag.length < 2)
+        notes.push("No site domain yet: diagnostic T2 (\"What is <brand> (<domain>)?\") was skipped.");
+    return [...questions, ...diag];
+}
+export function generateQuestions(r, now = new Date()) {
+    const langs = [...new Set((r.site.languages.length ? r.site.languages : ["en"]).map((l) => l.trim().toLowerCase()).filter(Boolean))];
+    const primary = langs[0];
+    const notes = [];
+    const sits = r.situations.filter((s) => isFilled(s.sentence));
+    const byLang = new Map();
+    for (const s of sits) {
+        const l = langs.length > 1 ? detectLang(s.sentence, langs) : primary;
+        byLang.set(l, [...(byLang.get(l) ?? []), s]);
+    }
+    const primarySits = byLang.get(primary)?.length ? byLang.get(primary) : sits;
+    const pBase = primary.split("-")[0];
+    if (pBase !== "en" && pBase !== "tr") {
+        notes.push(`The primary language is "${primary}"; Katman has English and Turkish templates only, so the ${primary} questions use English wording. Translate them into ${langName(primary, "en")} (katman_research update with the same ids) before the first run.`);
+    }
+    const questions = primarySet(r, primarySits, primary, now, notes);
+    for (const l of langs.slice(1)) {
+        const base = l.split("-")[0];
+        const T = base === "tr" ? "tr" : "en";
+        const own = byLang.get(l) ?? [];
+        const use = own.length ? own : primarySits;
+        const set = use.slice(0, 3).map((s, i) => ({ id: `${l}-q${i + 1}`, type: "situation", text: asQuestion(s.sentence, T), lang: l }));
+        set.push(...diagnostics(r, T, l, `${l}-`));
+        questions.push(...set);
+        if (!own.length) {
+            notes.push(`${langName(l, "en")} (${l}): no situations written in ${l} yet, so its ${set.length} questions reuse the ${primary} situations. Translate them — or add the customers' own ${l} sentences as situations — with katman_research update (same ids) before the first run.`);
+        }
+        else if (base !== "en" && base !== "tr") {
+            notes.push(`${langName(l, "en")} (${l}): the wrapper sentence and T1/T2 are in English; translate them (same ids) before the first run.`);
+        }
+        else
+            notes.push(`${langName(l, "en")} (${l}): ${set.length} questions (situations + T1/T2) — a smaller set than the primary language's 12 + 2.`);
+    }
+    notes.push("Review the wording once before the first run; after that keep the set fixed — runs are only comparable with the same questions, models and temperature.");
+    return { questions, lang: primary, languages: langs, notes };
+}
+/** The primary language's situation question ids (the "3 most important situation questions" to sample 3×). */
+export function keySituationQuestionIds(r, max = 3) {
+    if (!r)
+        return [];
+    const primary = (r.site.languages[0] ?? "en").toLowerCase();
+    return r.questions
+        .filter((q) => q.type === "situation" && (!q.lang || q.lang.toLowerCase() === primary))
+        .slice(0, max)
+        .map((q) => q.id);
+}

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

@@ -0,0 +1,182 @@
+import { logEvent, writeText } from "../../../state.js";
+import { mdTable, sortFindings } from "../../../util.js";
+import { calls, hasOpenRouterKey } from "../lib/calls.js";
+import { t } from "../lib/l10n.js";
+import { loadConfigSafe, loadLatestAudit, loadResearchSafe, loadRuns, loadScan, runDate } from "../lib/state.js";
+import { addDays, isFilled, isoDay } from "../lib/text.js";
+import { API_PROXY_NOTE, MEASURE_FREQUENCY, GSC_AI_NOTE } from "../data/measurement.js";
+import { OFFICIAL_REPORTS } from "../data/evidence.js";
+import { FOOTER } from "../data/render.js";
+import { researchCompleteness } from "./research.js";
+import { keySituationQuestionIds } from "./questions.js";
+import { loadPlanState, openTasks, fmtCallShort, taskCall } from "./plan.js";
+import { siteUrlOf } from "./prompt.js";
+function rate(x) {
+    return `${Math.round(x * 100)}%`;
+}
+function delta(a, b) {
+    if (b === undefined)
+        return "–";
+    const d = Math.round((a - b) * 100);
+    return d === 0 ? "±0" : d > 0 ? `+${d} pts` : `${d} pts`;
+}
+/** Runs are only comparable with the same question set and model panel. */
+export function comparable(a, b) {
+    const qa = new Set(a.answers.map((x) => x.question));
+    const qb = new Set(b.answers.map((x) => x.question));
+    const sameQ = qa.size === qb.size && [...qa].every((q) => qb.has(q));
+    const ma = new Set(a.models.map((m) => m.id));
+    const mb = new Set(b.models.map((m) => m.id));
+    const sameM = ma.size === mb.size && [...ma].every((m) => mb.has(m));
+    if (!sameQ)
+        return { ok: false, why: "the question set changed" };
+    if (!sameM)
+        return { ok: false, why: "the model panel changed" };
+    return { ok: true };
+}
+export async function buildReport(root, args = {}) {
+    const now = args.now ?? new Date();
+    const [research, config, scan, loaded, runs, planState] = await Promise.all([loadResearchSafe(root), loadConfigSafe(root), loadScan(root), loadLatestAudit(root), loadRuns(root), loadPlanState(root)]);
+    const lang = args.lang ?? config.lang ?? "en";
+    const L = (en, tr) => (lang === "tr" ? tr : en);
+    const audit = loaded?.audit;
+    const siteUrl = siteUrlOf(research, config);
+    const brand = isFilled(research?.brand.name) ? research.brand.name : undefined;
+    const comp = researchCompleteness(research);
+    const last = runs[runs.length - 1];
+    const prev = runs.length >= 2 ? runs[runs.length - 2] : undefined;
+    const cmp = last && prev ? comparable(last, prev) : undefined;
+    const plan = planState.plan;
+    const open = plan ? openTasks(plan) : [];
+    const out = [];
+    out.push(`# ${L("Katman report", "Katman raporu")} — ${brand ?? L("your site", "siteniz")}${siteUrl ? ` (${siteUrl})` : ""}`);
+    out.push(`${isoDay(now)} · ${L("AI visibility: read, quote, fit — and whether assistants name, recommend and cite you.", "Yapay zekâ görünürlüğü: okunmak, alıntılanmak, soruya uymak — ve asistanların sizi anıp, önerip, kaynak gösterip göstermediği.")}`);
+    // Summary
+    const summary = [];
+    summary.push(`- ${L("Research", "Araştırma")}: ${research ? `${comp.percent}%` : L("not started", "başlamadı")}${comp.gaps.length && research ? ` (${L("missing", "eksik")}: ${comp.gaps.slice(0, 3).join("; ")})` : ""}`);
+    if (audit)
+        summary.push(`- ${L("Site audit", "Site denetimi")} (${isoDay(audit.ts)}): Read ${audit.gates.read.pass}/${audit.gates.read.total} · Quote ${audit.gates.quote.pass}/${audit.gates.quote.total} · Fit ${audit.gates.fit.pass}/${audit.gates.fit.total} ${L("pages pass", "sayfa geçiyor")}`);
+    else
+        summary.push(`- ${L("Site audit", "Site denetimi")}: ${L("none yet", "henüz yok")}`);
+    if (last)
+        summary.push(`- ${L("AI visibility", "Yapay zekâ görünürlüğü")} (${isoDay(runDate(last) ?? last.ts)}, ${last.summary.answered} ${L("answers", "cevap")}): ${L("mentioned", "anılma")} ${rate(last.summary.mentionRate)} · ${L("recommended first", "ilk öneri")} ${rate(last.summary.recommendedFirstRate)} · ${L("cited", "kaynak")} ${rate(last.summary.citationRate)}${prev && cmp?.ok ? ` (${delta(last.summary.mentionRate, prev.summary.mentionRate)} ${L("mentions vs", "anılma, önceki:")} ${isoDay(runDate(prev) ?? prev.ts)})` : ""}`);
+    else
+        summary.push(`- ${L("AI visibility", "Yapay zekâ görünürlüğü")}: ${L("no measurement yet", "henüz ölçüm yok")}`);
+    if (plan)
+        summary.push(`- ${L("Plan", "Plan")}: ${plan.tasks.length - open.length}/${plan.tasks.length} ${L("tasks done", "görev tamam")} (${plan.tasks.length ? Math.round(((plan.tasks.length - open.length) / plan.tasks.length) * 100) : 0}%)`);
+    out.push(`## ${L("Summary", "Özet")}\n${summary.join("\n")}`);
+    // Research
+    if (research) {
+        out.push(`## ${L("Research", "Araştırma")} (${comp.percent}%)\n${mdTable([L("Item", "Madde"), L("Status", "Durum")], comp.items.map((i) => [i.label, `${i.score >= 1 ? L("done", "tamam") : L("open", "açık")} — ${i.detail}`]))}`);
+    }
+    // Audit
+    if (audit) {
+        const rows = ["read", "quote", "fit"].map((g) => [g === "read" ? L("Read", "Okunmak") : g === "quote" ? L("Quote", "Alıntılanmak") : L("Fit", "Soruya uymak"), `${audit.gates[g].pass}/${audit.gates[g].total}`, audit.gates[g].notes.slice(0, 2).join("; ")]);
+        const site = [];
+        const blocked = audit.site.bots.filter((b) => b.blocked);
+        site.push(`- ${L("AI bots through the CDN", "CDN’den geçen yapay zekâ botları")}: ${audit.site.bots.length ? (blocked.length ? `${L("blocked", "engelli")}: ${blocked.map((b) => `${b.token} (${b.status})`).join(", ")}` : L("all tested bots get 200", "test edilen bütün botlar 200 alıyor")) : L("not tested", "test edilmedi")}`);
+        site.push(`- robots.txt: ${audit.site.robots.exists ? (audit.site.robots.blocksAll ? L("blocks the whole site", "bütün siteyi kapatıyor") : audit.site.robots.blockedAiTokens.length ? `${L("blocks", "engelliyor")} ${audit.site.robots.blockedAiTokens.join(", ")}` : "ok") : L("missing", "yok")} · sitemap: ${audit.site.sitemapUrls} URL · llms.txt: ${audit.site.llmsTxt.exists ? L("yes", "var") : L("no", "yok")}${audit.site.soft404 ? ` · ${L("soft 404s", "sahte 404")}` : ""}`);
+        out.push(`## ${L("Site audit", "Site denetimi")} (${isoDay(audit.ts)}, ${audit.pages.length} ${L("pages", "sayfa")})\n${mdTable([L("Gate", "Kapı"), L("Pages passing", "Geçen sayfa"), L("Notes", "Notlar")], rows)}\n\n${site.join("\n")}`);
+    }
+    // Visibility
+    if (last) {
+        const lines = [];
+        const rows = [
+            [L("Mentioned", "Anılma"), rate(last.summary.mentionRate), prev ? rate(prev.summary.mentionRate) : "–", prev ? delta(last.summary.mentionRate, prev.summary.mentionRate) : "–"],
+            [L("Recommended first", "İlk öneri"), rate(last.summary.recommendedFirstRate), prev ? rate(prev.summary.recommendedFirstRate) : "–", prev ? delta(last.summary.recommendedFirstRate, prev.summary.recommendedFirstRate) : "–"],
+            [L("Cited", "Kaynak gösterilme"), rate(last.summary.citationRate), prev ? rate(prev.summary.citationRate) : "–", prev ? delta(last.summary.citationRate, prev.summary.citationRate) : "–"],
+        ];
+        lines.push(mdTable([L("Rate", "Oran"), `${L("Latest", "Son")} (${isoDay(runDate(last) ?? last.ts)})`, prev ? `${L("Previous", "Önceki")} (${isoDay(runDate(prev) ?? prev.ts)})` : L("Previous", "Önceki"), L("Change", "Değişim")], rows));
+        if (cmp && !cmp.ok)
+            lines.push(`> ${L(`Not comparable: ${cmp.why}. Keep the same questions and models between runs.`, `Karşılaştırılamaz: ${cmp.why}. Ölçümler arasında aynı soruları ve modelleri kullanın.`)}`);
+        if (last.status === "partial")
+            lines.push(`> ${L("This run stopped early (credits, cost cap or cancel): skipped answers are recorded, rates cover the answered ones only.", "Bu ölçüm erken durdu (kredi, maliyet sınırı ya da iptal): atlanan cevaplar kayıtlı, oranlar yalnızca cevaplananları kapsıyor.")}`);
+        const fam = Object.entries(last.summary.byFamily);
+        if (fam.length)
+            lines.push(mdTable([L("Assistant", "Asistan"), L("Answers", "Cevap"), L("Mentioned", "Anıldı"), L("First", "İlk"), L("Cited", "Kaynak")], fam.map(([f, v]) => [f, v.answered, v.mentioned, v.recommendedFirst, v.cited])));
+        const byLang = Object.entries(last.summary.byLanguage ?? {});
+        if (byLang.length > 1)
+            lines.push(mdTable([L("Language", "Dil"), L("Answers", "Cevap"), L("Mentioned", "Anıldı"), L("First", "İlk"), L("Cited", "Kaynak")], byLang.map(([l, v]) => [l, v.answered, v.mentioned, v.recommendedFirst, v.cited])));
+        const samples = Math.max(0, ...last.answers.map((a) => a.sample ?? 1));
+        if (samples > 1)
+            lines.push(`- ${L(`Questions were asked up to ${samples} times each: read the rates as frequency (how often you're named), not rank.`, `Sorular en fazla ${samples}’er kez soruldu: oranları sıra değil sıklık olarak okuyun (ne sıklıkla anıldığınız).`)}`);
+        const noSearch = last.answers.filter((a) => a.searched === false).length;
+        if (noSearch)
+            lines.push(`- ${L(`${noSearch} answer(s) came without a web search (answered from memory: big brands dominate those).`, `${noSearch} cevap web araması yapılmadan geldi (hafızadan cevap: bunlarda büyük markalar baskın).`)}`);
+        const diag = last.answers.filter((a) => a.questionType === "diagnostic" && a.identityCorrect === false);
+        if (diag.length)
+            lines.push(`- ${L("Identity problems", "Kimlik sorunları")}: ${diag.map((a) => `${a.family} “${a.answerExcerpt.slice(0, 80)}…”`).join("; ")} → ${L("strengthen the not-X note (P5, P8)", "“X değildir” notunu güçlendirin (P5, P8)")}`);
+        lines.push(`- ${t(MEASURE_FREQUENCY, lang)}`);
+        lines.push(`- ${t(API_PROXY_NOTE, lang)}`);
+        out.push(`## ${L("AI visibility", "Yapay zekâ görünürlüğü")}\n${lines.join("\n\n")}`);
+        const comps = last.summary.topCompetitors.slice(0, 10);
+        const doms = last.summary.topCitedDomains.filter((d) => !research?.site.domain || !d.domain.endsWith(research.site.domain)).slice(0, 10);
+        if (comps.length)
+            out.push(`### ${L("Who the assistants name instead", "Asistanların yerinize andıkları")}\n${mdTable([L("Name", "Ad"), L("Times named", "Anılma")], comps.map((c) => [c.name, c.count]))}\n${L("Put these in research.competitors (with url + date) and in the comparison guide (P7).", "Bunları research.competitors’a (url + tarihle) ve karşılaştırma rehberine (P7) ekleyin.")}`);
+        if (doms.length)
+            out.push(`### ${L("Which sites the assistants cite (off-site targets)", "Asistanların alıntıladığı siteler (site dışı hedefler)")}\n${mdTable([L("Domain", "Alan adı"), L("Citations", "Alıntı")], doms.map((d) => [d.domain, d.count]))}\n${L("These are where to get mentioned (book ch. 14): list authors to contact, directories to join, video and community topics. No bought links, fake reviews or self-ranked lists.", "Bahsedilmeniz gereken yerler bunlar (14. bölüm): ulaşılacak liste yazarları, katılınacak dizinler, video ve topluluk konuları. Satın alınmış link, sahte yorum ya da kendini birinci yazan liste yok.")}`);
+    }
+    // Plan progress
+    if (plan) {
+        const rows = [1, 2, 3, 4].map((w) => {
+            const wt = plan.tasks.filter((x) => x.week === w);
+            return [`${L("Week", "Hafta")} ${w}`, `${wt.filter((x) => x.done).length}/${wt.length}`];
+        });
+        out.push(`## ${L("Plan progress", "Plan ilerlemesi")}\n${mdTable([L("Week", "Hafta"), L("Done", "Tamam")], rows)}`);
+    }
+    // Top 10 open issues
+    const findings = new Map();
+    for (const f of scan?.findings ?? [])
+        findings.set(f.id, f);
+    for (const f of audit?.findings ?? [])
+        findings.set(f.id, f);
+    const top = sortFindings([...findings.values()].filter((f) => f.severity !== "info")).slice(0, 10);
+    if (top.length) {
+        out.push(`## ${L("Top open issues", "Açık sorunlar")}\n${top.map((f, i) => `${i + 1}. **[${f.severity.toUpperCase()}] ${f.title}** (${f.gate}${f.prompt ? `, ${L("fix with", "çözüm")} ${f.prompt}` : ""})${f.fix ? ` — ${f.fix}` : ""}`).join("\n")}`);
+    }
+    // Next 7 days
+    const next = [];
+    const lastDate = last ? runDate(last) : undefined;
+    const due = lastDate ? addDays(lastDate, 14) : undefined;
+    if (!research)
+        next.push(`${L("Fill research", "Araştırmayı doldurun")}: ${fmtCallShort(calls.researchTemplate(root))}`);
+    else if (comp.blocking.length)
+        next.push(`${L("Finish research", "Araştırmayı tamamlayın")}: ${comp.blocking.join(", ")}`);
+    const crit = top.filter((f) => f.severity === "critical");
+    for (const f of crit.slice(0, 2))
+        next.push(`${L("Fix the critical issue", "Kritik sorunu düzeltin")}: ${f.title}${f.prompt ? ` (${fmtCallShort(calls.prompt(root, f.prompt))})` : ""}`);
+    for (const task of open.filter((x) => !(x.id === "research" && (!research || comp.blocking.length))).slice(0, 4)) {
+        const call = taskCall(root, task, siteUrl);
+        next.push(`${task.title}${call ? ` — ${fmtCallShort(call)}` : ""}`);
+    }
+    if (!last && !open.slice(0, 4).some((x) => x.id === "measure-1"))
+        next.push(`${L("Baseline measurement", "İlk ölçüm")}: ${fmtCallShort(hasOpenRouterKey() ? calls.visibilityDryRun(root) : calls.manualCheck(root))}`);
+    else if (due && due.getTime() <= addDays(now, 7).getTime())
+        next.push(`${L("Re-measure on", "Yeniden ölçüm")} ${isoDay(due)}: ${L("same questions, models and temperature; 3 samples for the 3 key situation questions", "aynı sorular, modeller ve sıcaklık; 3 kilit durum sorusu için 3 örnek")} (${fmtCallShort(calls.visibilityDryRun(root, { question_ids: keySituationQuestionIds(research).length ? keySituationQuestionIds(research) : ["q1", "q2", "q3"], samples: 3 }))}), ${L("and confirm them in the real apps", "ve gerçek uygulamalarda doğrulayın")} (${fmtCallShort(calls.manualCheck(root))}).`);
+    else if (due)
+        next.push(`${L("Next re-measurement", "Sonraki ölçüm")}: ${isoDay(due)}.`);
+    if (!next.length)
+        next.push(L("Verify the live pages (katman_audit_site), submit changed URLs (katman_indexnow), keep publishing 5–10 situation pages a week.", "Canlı sayfaları doğrulayın (katman_audit_site), değişen adresleri gönderin (katman_indexnow), haftada 5–10 durum sayfası yayınlamaya devam edin."));
+    out.push(`## ${L("Next 7 days", "Önümüzdeki 7 gün")}\n${next.map((n) => `- ${n}`).join("\n")}`);
+    // Where to look
+    out.push(`## ${L("Where to look outside Katman", "Katman dışında nereye bakılır")}\n${OFFICIAL_REPORTS.map((r) => `- **${r.name}** (${t(r.since, lang)}): ${t(r.shows, lang)}`).join("\n")}\n- ${t(GSC_AI_NOTE, lang)}\n- ${L("Your analytics: the AI channel (utm_source=chatgpt.com counts even without a referrer), human sessions only; server-side bot counts.", "Analitiğiniz: yapay zekâ kanalı (utm_source=chatgpt.com referrer olmadan da sayılır), yalnızca insan oturumları; sunucu tarafı bot sayıları.")}`);
+    out.push(`---\n${FOOTER}`);
+    const markdown = out.join("\n\n") + "\n";
+    return {
+        markdown,
+        data: {
+            researchPct: comp.percent,
+            audit: audit ? { ts: audit.ts, gates: audit.gates } : null,
+            visibility: last ? { ts: last.ts, ...last.summary, comparableWithPrevious: cmp?.ok ?? null } : null,
+            plan: plan ? { tasks: plan.tasks.length, done: plan.tasks.length - open.length } : null,
+            topIssues: top.map((f) => ({ id: f.id, title: f.title, severity: f.severity, prompt: f.prompt ?? null })),
+            nextSevenDays: next,
+        },
+    };
+}
+export async function runReport(root, args = {}) {
+    const { markdown, data } = await buildReport(root, args);
+    const p = await writeText(root, "report.md", markdown);
+    await logEvent(root, "katman_report: wrote report.md");
+    return { text: `Wrote ${p}\n\n${markdown}`, structured: { path: p, ...data } };
+}

package/dist/tools/method/core/research-run.js

@@ -0,0 +1,148 @@
+import { logEvent, saveConfig, saveResearch, writeText } from "../../../state.js";
+import { loadConfigSafe, loadResearchSafe, loadRuns, loadScan } from "../lib/state.js";
+import { calls, fmtCall } from "../lib/calls.js";
+import { t } from "../lib/l10n.js";
+import { codeBlock, isFilled } from "../lib/text.js";
+import { RESEARCH_FILL_GUIDE, RESEARCH_MD_TEMPLATE, RESEARCH_STEPS } from "../data/research.js";
+import { emptyResearch, mergeResearch, researchCompleteness, renderResearchMd, templateResearch, validateResearch, } from "./research.js";
+import { generateQuestions } from "./questions.js";
+const UPDATE_EXAMPLE = {
+    mode: "update",
+    data: {
+        site: { url: "https://example.com", languages: ["en"] },
+        brand: {
+            name: "<one distinctive name>",
+            category: "<category, e.g. AI invoice scanner>",
+            notX: "<what it gets confused with, or none>",
+            oneLiner: { brings: "<what the customer brings>", weDo: "<what we do>", gets: "<what they get>", fear: "<which fear is unnecessary>" },
+            pricing: "<exactly as on the pricing page>",
+        },
+        situations: [{ sentence: "<the customer's own sentence, no brand name>", url: "/<words-from-the-sentence>" }],
+        competitors: [{ name: "<name>", url: "https://…", what: "…", price: "…", forWhom: "…", checkedAt: "YYYY-MM-DD" }],
+        proof: [{ claim: "…", value: "…", source: "https://…", date: "YYYY-MM-DD" }],
+    },
+};
+async function persist(root, r, lang) {
+    await saveResearch(root, r);
+    const runs = await loadRuns(root);
+    await writeText(root, "research.md", renderResearchMd(r, runs, lang));
+}
+function statusBlock(r) {
+    const completeness = researchCompleteness(r);
+    const warnings = validateResearch(r);
+    const lines = [
+        `**Research: ${completeness.percent}% complete.**`,
+        completeness.items.map((i) => `- ${i.score >= 1 ? "[x]" : "[ ]"} ${i.label} — ${i.detail}`).join("\n"),
+    ];
+    if (warnings.length)
+        lines.push(`**Fix these (${warnings.length}):**\n${warnings.map((w) => `- ${w}`).join("\n")}`);
+    return { md: lines.join("\n\n"), completeness, warnings };
+}
+function nextAfterResearch(root, r) {
+    const c = researchCompleteness(r);
+    if (c.blocking.includes("question set") && r.situations.length >= 3 && c.blocking.length === 1) {
+        return `**Next:** build the question set: ${fmtCall(calls.generateQuestions(root))}`;
+    }
+    if (c.blocking.length) {
+        return `**Next:** fill ${c.blocking.join(", ")} with ${fmtCall(calls.researchUpdate(root, {}))} — from the codebase where possible, asking the user for customer sentences. Never invent facts: unknown stays [FILL].`;
+    }
+    return `**Next:** ${fmtCall(calls.start(root))} — it picks the next step (scan, audit, first measurement, plan).`;
+}
+export async function runResearch(root, args) {
+    const config = await loadConfigSafe(root);
+    const lang = args.lang ?? config.lang ?? "en";
+    const existing = await loadResearchSafe(root);
+    const mode = args.mode ?? (args.data || args.generateQuestions ? "update" : existing ? "show" : "template");
+    if (mode === "template") {
+        const header = `# Research template (step 1)\n\n${RESEARCH_STEPS.map((s) => `${s.n}. **${t(s.title, lang)}** — ${t(s.how, lang)}`).join("\n")}`;
+        if (existing) {
+            const st = statusBlock(existing);
+            return {
+                text: [
+                    `.katman/research.json already exists — nothing was overwritten. Use mode "update" to change it.`,
+                    st.md,
+                    header,
+                    `## How to fill it\n${t(RESEARCH_FILL_GUIDE, lang)}`,
+                    nextAfterResearch(root, existing),
+                ].join("\n\n"),
+                structured: { mode, created: false, completeness: st.completeness.percent, gaps: st.completeness.gaps, warnings: st.warnings },
+            };
+        }
+        const scan = await loadScan(root);
+        const langs = scan?.i18n.locales.length ? scan.i18n.locales.map((l) => l.toLowerCase()) : scan?.i18n.htmlLang ? [scan.i18n.htmlLang.toLowerCase()] : [];
+        const r = templateResearch(config.siteUrl, langs);
+        await persist(root, r, lang);
+        await logEvent(root, "katman_research: created research.json from the template");
+        return {
+            text: [
+                `Created \`.katman/research.json\` and \`.katman/research.md\` from the book's template (values are [FILL]).`,
+                header,
+                `## The template\n${codeBlock(t(RESEARCH_MD_TEMPLATE, lang), "md")}`,
+                `## How to fill it (do this now)\n${t(RESEARCH_FILL_GUIDE, lang)}`,
+                `## Update call shape\n${codeBlock(JSON.stringify(UPDATE_EXAMPLE, null, 2), "json")}`,
+                `Once there are ≥3 situations, add \`"generate_questions": true\` to build the 12 + 2 question set.`,
+            ].join("\n\n"),
+            structured: { mode, created: true, path: ".katman/research.json", completeness: researchCompleteness(r).percent },
+        };
+    }
+    if (mode === "show") {
+        if (!existing) {
+            return {
+                text: `No research yet. Start with ${fmtCall(calls.researchTemplate(root))}.`,
+                structured: { mode, exists: false },
+            };
+        }
+        await persist(root, existing, lang);
+        const st = statusBlock(existing);
+        const runs = await loadRuns(root);
+        return {
+            text: [st.md, "---", renderResearchMd(existing, runs, lang), nextAfterResearch(root, existing)].join("\n\n"),
+            structured: { mode, exists: true, completeness: st.completeness.percent, gaps: st.completeness.gaps, warnings: st.warnings, research: existing },
+        };
+    }
+    // update
+    const base = existing ?? emptyResearch(config.siteUrl);
+    const { research, changes } = mergeResearch(base, args.data ?? {}, !!args.replaceLists);
+    const notes = [];
+    let generated = false;
+    if (args.generateQuestions) {
+        if (base.questions.length && !args.replaceLists && !args.data?.questions) {
+            notes.push(`A question set already exists (${base.questions.length} questions); it was kept so runs stay comparable. Pass "replace_lists": true with "generate_questions": true to rebuild it (the next run won't be comparable with earlier ones).`);
+        }
+        else {
+            const g = generateQuestions(research);
+            research.questions = g.questions;
+            notes.push(...g.notes);
+            generated = true;
+            changes.push(`questions: generated ${g.questions.length} (${g.languages.join(", ")})`);
+        }
+    }
+    await persist(root, research, lang);
+    if (isFilled(research.site.url) && research.site.url !== config.siteUrl && /^https?:\/\//.test(research.site.url)) {
+        await saveConfig(root, { ...config, siteUrl: research.site.url });
+        notes.push(`Saved site URL ${research.site.url} to .katman/config.json.`);
+    }
+    await logEvent(root, `katman_research update: ${changes.join("; ") || "no changes"}`);
+    const st = statusBlock(research);
+    const parts = [
+        `Updated \`.katman/research.json\` and \`.katman/research.md\`${existing ? "" : " (new file)"}.`,
+        changes.length ? `**Changes:** ${changes.join(" · ")}` : "**No changes** (data was empty).",
+        st.md,
+    ];
+    if (generated)
+        parts.push(`**Question set** (${research.questions.length}):\n${research.questions.map((q) => `- \`${q.id}\` [${q.type}${q.lang ? `, ${q.lang}` : ""}] ${q.text}`).join("\n")}`);
+    if (notes.length)
+        parts.push(notes.map((n) => `- ${n}`).join("\n"));
+    parts.push(nextAfterResearch(root, research));
+    return {
+        text: parts.join("\n\n"),
+        structured: {
+            mode,
+            changes,
+            completeness: st.completeness.percent,
+            gaps: st.completeness.gaps,
+            warnings: st.warnings,
+            questions: research.questions,
+        },
+    };
+}