katman-mcp 0.1.0

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

@@ -0,0 +1,302 @@
+import { calls } from "../lib/calls.js";
+import { fwLabel, isCsr, pageLocation } from "../lib/framework.js";
+import { t } from "../lib/l10n.js";
+import { findPage, knownPublicPaths } from "../lib/routes.js";
+import { loadConfigSafe, loadLatestAudit, loadResearchSafe, loadScan, staticDirFor } from "../lib/state.js";
+import { FILL, brandSentence, hasNotX, isFilled, slugify } from "../lib/text.js";
+import { ANATOMY } from "../data/anatomy.js";
+import { fmtCallShort } from "./plan.js";
+import { pickSituation, siteUrlOf, situationUrl } from "./prompt.js";
+export const BRIEF_TYPES = ["situation", "comparison", "pricing", "faq", "about", "single-question", "glossary", "tool", "home"];
+function cap(s) {
+    return s ? s.charAt(0).toUpperCase() + s.slice(1) : s;
+}
+function titleWithBrand(core, brand, notes, lang) {
+    const c = cap(core.replace(/[.?!]+$/, ""));
+    if (!brand)
+        return c;
+    const full = `${c} — ${brand}`;
+    if (full.length <= 60)
+        return full;
+    notes.push(lang === "tr"
+        ? `“${full}” ${full.length} karakter: 60’ı aşınca sondaki marka düşer (kitap kuralı). Durumu daha kısa yazın ya da markasız kullanın.`
+        : `“${full}” is ${full.length} characters: over 60, the brand suffix drops (book rule). Shorten the situation wording or use it without the brand.`);
+    return c.length <= 60 ? c : `${c.slice(0, 57).replace(/\s+\S*$/, "")}…`;
+}
+export function buildBrief(type, c) {
+    const lang = c.lang;
+    const L = (en, tr) => (lang === "tr" ? tr : en);
+    const F = (hint) => `${FILL} ${hint}`;
+    const r = c.research;
+    const brand = isFilled(r?.brand.name) ? r.brand.name.trim() : undefined;
+    const category = isFilled(r?.brand.category) ? r.brand.category.trim() : undefined;
+    const sentence = brandSentence(r);
+    const pricing = isFilled(r?.brand.pricing) ? r.brand.pricing.trim() : undefined;
+    const notX = hasNotX(r?.brand.notX) ? r.brand.notX.trim() : undefined;
+    const year = (c.now ?? new Date()).getUTCFullYear();
+    const known = knownPublicPaths(c.scan, c.audit);
+    const primaryTr = (r?.site.languages[0] ?? "en").toLowerCase().startsWith("tr");
+    const notes = [];
+    const proof = (r?.proof ?? []).filter((p) => isFilled(p.source)).map((p) => `${p.claim}${p.value ? `: ${p.value}` : ""} — ${p.source}${p.date ? `, ${p.date}` : ""}`);
+    const proofOr = proof.length ? proof : [F(L("a verifiable number with its source and date — or leave the block out; never invent one", "kaynağı ve tarihi olan doğrulanabilir bir sayı — yoksa bloğu çıkarın; asla uydurmayın"))];
+    const alternatives = (r?.competitors ?? []).map((x) => `${x.name}: ${isFilled(x.forWhom) ? x.forWhom : F(L("who it fits (from its own site)", "kime uygun (kendi sitesinden)"))} (${isFilled(x.url) ? x.url : F("url")}, ${L("checked", "kontrol")} ${isFilled(x.checkedAt) ? x.checkedAt : F("YYYY-MM-DD")})`);
+    const pricingPath = findPage(known, "pricing")?.path ?? (primaryTr ? "/fiyatlandirma" : "/pricing");
+    const guidePath = findPage(known, "comparison")?.path ?? (category ? (primaryTr ? `/rehber/${slugify(category, 4)}-araclari` : `/guides/${slugify(category, 4)}-tools`) : undefined);
+    const faqPath = findPage(known, "faq")?.path ?? (primaryTr ? "/sss" : "/faq");
+    const aboutPath = findPage(known, "about")?.path ?? (primaryTr ? "/hakkimizda" : "/about");
+    const b = {
+        type, url: "", urlSuggested: false, title: "", h1: "", firstSentence: "", action: "", proof: proofOr, notFor: [], alternatives: [], faq: [], related: [],
+        blocks: [], jsonLd: [], files: [], fileNotes: [], notes,
+    };
+    const genericFaq = [
+        pricing ? L(`How much does it cost? (answer: ${pricing})`, `Ne kadar tutuyor? (cevap: ${pricing})`) : L("How much does it cost? (answer from research pricing)", "Ne kadar tutuyor? (cevap araştırmadaki fiyattan)"),
+        L("Do I need an account to try it?", "Denemek için hesap gerekiyor mu?"),
+        L("What happens to my files / data?", "Dosyalarıma / verilerime ne oluyor?"),
+        L("How long does it take?", "Ne kadar sürüyor?"),
+        L("What if the result isn't what I wanted?", "Sonuç istediğim gibi olmazsa ne olur?"),
+    ];
+    const anatomy = ANATOMY.map((a) => `${a.n}. ${a.tags.length ? `[${a.tags.join(" ")}] ` : ""}**${t(a.name, lang)}** — ${t(a.rule, lang)}`);
+    const sitewide = L("Sitewide (layout): Organization (not-X in disambiguatingDescription) + WebSite — `katman_generate` organization-jsonld / website-jsonld", "Bütün sitede (layout): Organization (“X değildir” disambiguatingDescription’da) + WebSite — `katman_generate` organization-jsonld / website-jsonld");
+    const crumbs = L("BreadcrumbList (Home → this page) — `katman_generate` breadcrumb-jsonld", "BreadcrumbList (Ana sayfa → bu sayfa) — `katman_generate` breadcrumb-jsonld");
+    const faqLd = L("FAQPage with exactly the questions and answers visible on the page — `katman_generate` faq-jsonld", "Sayfada görünen soru-cevapların aynısıyla FAQPage — `katman_generate` faq-jsonld");
+    switch (type) {
+        case "situation": {
+            const s = pickSituation(r, c.situationId, c.scan, c.audit);
+            if (c.situationId && !s)
+                return { error: `Situation "${c.situationId}" not found. Known: ${(r?.situations ?? []).map((x) => x.id).join(", ") || "none"}.` };
+            const sentenceText = s?.sentence ?? c.topic ?? F(L("the customer's sentence (katman_research)", "müşterinin cümlesi (katman_research)"));
+            if (s)
+                b.situation = { id: s.id, sentence: s.sentence };
+            b.url = s ? situationUrl(s, r?.site.languages) : c.topic ? `/${slugify(c.topic)}` : "/" + F("words-from-the-sentence");
+            b.urlSuggested = !s?.url;
+            b.title = titleWithBrand(sentenceText, brand, notes, lang);
+            b.h1 = sentenceText;
+            b.firstSentence = sentence
+                ? L(`Tailor the one sentence to this situation, keeping its four parts: “${sentence}”`, `Tek cümleyi bu duruma uyarlayın, dört parçasını koruyun: “${sentence}”`)
+                : F(L("brings → we do → they get. fear is unnecessary. (fill the 4-part sentence in research)", "getirir → yaparız → eline geçer. korku gereksiz. (4 parçalı cümleyi araştırmada doldurun)"));
+            b.action = F(L("one clear action usable in the first minute — a file drop box, a trial, or the price", "ilk dakikada kullanılabilen tek net eylem — dosya kutusu, deneme ya da fiyat"));
+            b.notFor = [F(L("who should use something else — 2–3 bullets", "kim başka bir şey kullanmalı — 2–3 madde"))];
+            b.alternatives = alternatives.length ? alternatives : [F(L("competitors from research, with who each one fits", "araştırmadaki rakipler, her birinin kime uygun olduğuyla"))];
+            const kw = (r?.keywords ?? []).filter((k) => k.page && b.url && k.page === b.url).map((k) => cap(k.term) + "?");
+            b.faq = [...kw, ...genericFaq].slice(0, 8);
+            b.related = [
+                ...(r?.situations ?? []).filter((x) => x.id !== s?.id).slice(0, 3).map((x) => `${situationUrl(x, r?.site.languages)} (“${x.sentence}”)`),
+                pricingPath,
+                ...(guidePath ? [guidePath] : []),
+            ].slice(0, 5);
+            b.blocks = anatomy;
+            b.jsonLd = [
+                L("Service — or SoftwareApplication / WebApplication for a product; offers only if the price is visible on this page (`katman_generate` software-jsonld)", "Service — ürün için SoftwareApplication / WebApplication; fiyat yalnızca bu sayfada görünüyorsa offers (`katman_generate` software-jsonld)"),
+                faqLd,
+                crumbs,
+                sitewide,
+            ];
+            break;
+        }
+        case "comparison": {
+            const topic = c.topic ?? category ?? F(L("category", "kategori"));
+            b.topic = topic;
+            b.url = c.topic ? (primaryTr ? `/rehber/${slugify(c.topic, 5)}` : `/guides/${slugify(c.topic, 5)}`) : guidePath ?? "/guides/" + F("tools-for-x");
+            b.urlSuggested = true;
+            b.title = titleWithBrand(L(`${cap(topic)} tools: an honest comparison (${year})`, `${topic} için araçlar: dürüst karşılaştırma (${year})`), undefined, notes, lang);
+            b.h1 = L(`Which ${topic} tools are there?`, `${topic} için hangi araçlar var?`);
+            b.firstSentence = F(L("a 2–3 sentence short answer: which tool for which situation", "2–3 cümlelik kısa cevap: hangi durumda hangi araç"));
+            b.action = L("Link each tool to its own site (nofollow is fine); our own entry links to the relevant situation page.", "Her aracı kendi sitesine linkleyin (nofollow olabilir); bizim satırımız ilgili durum sayfasına linklesin.");
+            b.alternatives = [
+                ...(alternatives.length ? alternatives : [F(L("at least 3 competitors from research", "araştırmadan en az 3 rakip"))]),
+                `${brand ?? F(L("our brand", "markamız"))}: ${L("who it fits", "kime uygun")}: ${FILL} · ${L("what it doesn't do", "neyi yapmıyor")}: ${FILL} ${L("(not first in the list)", "(listenin başında değil)")}`,
+            ];
+            b.notFor = [L("For every tool, ours included: “who it fits” and “what it doesn't do”.", "Bizimki dahil her araç için: “kime uygun” ve “neyi yapmıyor”.")];
+            b.faq = [L("Which one is easiest for beginners?", "Yeni başlayanlar için hangisi daha kolay?"), L("Which one is cheapest?", "Hangisi en ucuz?"), L("Which one works without an account?", "Hangisi hesapsız çalışıyor?")].map((q) => `${q} ${L("(answer only from the sourced facts above)", "(yalnızca yukarıdaki kaynaklı bilgilerden cevaplayın)")}`);
+            b.related = (r?.situations ?? []).slice(0, 4).map((x) => situationUrl(x, r?.site.languages)).concat(pricingPath).slice(0, 5);
+            b.blocks = [
+                L("Short answer at the top (2–3 sentences).", "En üstte kısa cevap (2–3 cümle)."),
+                L("One section per tool: what it does, price, who it fits, what it doesn't do, source link + date checked.", "Her araç için bir bölüm: ne yapar, fiyat, kime uygun, neyi yapmıyor, kaynak linki + kontrol tarihi."),
+                L("Don't put us first; write our gaps too. Self-ranked lists backfire (the brand was left out 69% of the time when its own list was cited).", "Bizi başa koymayın; eksiğimizi de yazın. Kendini birinci yazan listeler ters tepiyor (kendi listesi alıntılandığında marka %69 oranında dışarıda kaldı)."),
+                L("A comparison table in plain HTML.", "Düz HTML karşılaştırma tablosu."),
+                L("Visible update date and author.", "Görünür güncelleme tarihi ve yazar."),
+            ];
+            b.jsonLd = [L("Article (headline, datePublished, dateModified, author)", "Article (headline, datePublished, dateModified, author)"), L("ItemList with the tools in the same order as on the page", "Sayfadaki sırayla araçları içeren ItemList"), crumbs, sitewide];
+            break;
+        }
+        case "pricing": {
+            b.url = pricingPath;
+            b.title = titleWithBrand(L(`${brand ?? "[FILL]"} pricing: plans and prices`, `${brand ?? "[DOLDUR]"} fiyatları: planlar`), undefined, notes, lang);
+            b.h1 = L(`${brand ?? F("brand")} pricing`, `${brand ?? F("marka")} fiyatları`);
+            b.firstSentence = pricing ?? F(L("the pricing exactly as in research (and llms.txt)", "araştırmadaki (ve llms.txt’deki) fiyatın aynısı"));
+            b.action = L("The plan buttons (checkout), matching the visitor's intent.", "Ziyaretçinin niyetine uygun plan düğmeleri (ödeme).");
+            b.blocks = [
+                L("Prices in plain HTML text (no JS-only toggles).", "Fiyatlar düz HTML metinde (yalnızca JS ile değişen anahtarlar yok)."),
+                L("What each plan includes and its limits.", "Her planın içeriği ve sınırları."),
+                L("Trial, cancellation, refunds — as they really are.", "Deneme, iptal, iade — gerçekte nasılsa."),
+                L("Don't call a paid product “free”; no fake urgency.", "Ücretli ürüne “ücretsiz” demeyin; sahte aciliyet yok."),
+                L("FAQ about billing.", "Faturalandırma SSS’si."),
+            ];
+            b.faq = [L("Can I cancel any time?", "İstediğim zaman iptal edebilir miyim?"), L("Is there a trial?", "Deneme var mı?"), L("What happens when I hit the limit?", "Sınıra gelince ne olur?"), L("Do you offer refunds?", "İade var mı?"), L("Which payment methods do you accept?", "Hangi ödeme yöntemleri kabul ediliyor?")];
+            b.related = (r?.situations ?? []).slice(0, 3).map((x) => situationUrl(x, r?.site.languages)).concat(faqPath);
+            b.jsonLd = [L("SoftwareApplication / Service with offers exactly as shown on this page (`katman_generate` software-jsonld)", "Bu sayfada görünen fiyatlarla birebir offers içeren SoftwareApplication / Service (`katman_generate` software-jsonld)"), faqLd, crumbs, sitewide];
+            notes.push(L("The same prices must appear in llms.txt and schema; the linter compares them.", "Aynı fiyatlar llms.txt’de ve schema’da olmalı; denetleyici karşılaştırır."));
+            break;
+        }
+        case "faq": {
+            b.url = faqPath;
+            b.title = titleWithBrand(L(`${brand ?? "[FILL]"} FAQ`, `${brand ?? "[DOLDUR]"} SSS`), undefined, notes, lang);
+            b.h1 = L(`Questions about ${brand ?? F("brand")}`, `${brand ?? F("marka")} hakkında sorular`);
+            b.firstSentence = sentence ?? F(L("the one sentence", "tek cümle"));
+            b.faq = [
+                L(`What is ${brand ?? "[FILL]"}? (answer: the one sentence)`, `${brand ?? "[DOLDUR]"} nedir? (cevap: tek cümle)`),
+                ...(notX ? [L(`Is it the same as … ? (answer: ${notX})`, `… ile aynı mı? (cevap: ${notX})`)] : []),
+                pricing ? L(`How much does it cost? (answer: ${pricing})`, `Ne kadar tutuyor? (cevap: ${pricing})`) : L("How much does it cost?", "Ne kadar tutuyor?"),
+                ...(r?.situations ?? []).slice(0, 3).map((x) => L(`Can it help if “${x.sentence}”? (link ${situationUrl(x, r?.site.languages)})`, `“${x.sentence}” durumunda işe yarar mı? (link ${situationUrl(x, r?.site.languages)})`)),
+                F(L("the real questions from support e-mails and sales calls", "destek e-postaları ve satış görüşmelerinden gerçek sorular")),
+            ];
+            b.blocks = [L("Every answer's first sentence is the answer.", "Her cevabın ilk cümlesi cevaptır."), L("Answers link to the page that covers the topic.", "Cevaplar konuyu anlatan sayfaya link verir."), L("Plain HTML (no answers hidden behind JS-only accordions; <details> is fine).", "Düz HTML (yalnızca JS ile açılan akordeonlarda gizli cevap yok; <details> olur).")];
+            b.related = [pricingPath, aboutPath, ...(r?.situations ?? []).slice(0, 3).map((x) => situationUrl(x, r?.site.languages))];
+            b.jsonLd = [faqLd, crumbs, sitewide];
+            notes.push(L("Google retired the FAQ rich result in May 2026; write the FAQ for assistants, not for a Google box.", "Google SSS zengin sonucunu Mayıs 2026’da kaldırdı; SSS’yi Google kutusu için değil asistanlar için yazın."));
+            break;
+        }
+        case "about": {
+            b.url = aboutPath;
+            b.title = titleWithBrand(L(`About ${brand ?? "[FILL]"}`, `${brand ?? "[DOLDUR]"} hakkında`), category, notes, lang);
+            b.h1 = L(`About ${brand ?? F("brand")}`, `${brand ?? F("marka")} hakkında`);
+            b.firstSentence = sentence ?? F(L("the one sentence", "tek cümle"));
+            b.blocks = [
+                L(`Who builds it: ${isFilled(r?.brand.company) ? r.brand.company : "[FILL: company]"}${isFilled(r?.brand.country) ? ` (${r.brand.country})` : ""}.`, `Kim yapıyor: ${isFilled(r?.brand.company) ? r.brand.company : "[DOLDUR: şirket]"}${isFilled(r?.brand.country) ? ` (${r.brand.country})` : ""}.`),
+                notX ? L(`The not-X note, word for word: “${notX}”`, `“X değildir” notu, aynen: “${notX}”`) : L("Not-X note: only if the brand gets confused with something (ask ChatGPT “What is <brand>?”).", "“X değildir” notu: yalnızca marka bir şeyle karışıyorsa (ChatGPT’ye “<marka> nedir?” diye sorun)."),
+                L(`Social accounts: ${(r?.brand.socials ?? []).join(", ") || "[FILL]"}`, `Sosyal hesaplar: ${(r?.brand.socials ?? []).join(", ") || "[DOLDUR]"}`),
+                L("A contact e-mail in plain text (not obfuscated).", "Düz metin iletişim e-postası (gizlenmemiş)."),
+                L("Proof with sources; say plainly when a test was small.", "Kaynaklı kanıt; test küçükse açıkça söyleyin."),
+            ];
+            b.jsonLd = [L("AboutPage", "AboutPage"), L("Organization with alternateName, disambiguatingDescription (the not-X note) and sameAs (socials)", "alternateName, disambiguatingDescription (“X değildir” notu) ve sameAs (sosyal hesaplar) ile Organization"), crumbs];
+            b.related = [pricingPath, faqPath];
+            break;
+        }
+        case "single-question": {
+            const q = c.topic ?? F(L("the one question (from Google autocomplete: katman_keywords)", "tek soru (Google otomatik tamamlamasından: katman_keywords)"));
+            b.topic = q;
+            b.url = c.topic ? `/${slugify(c.topic)}` : "/" + F("words-from-the-question");
+            b.urlSuggested = true;
+            b.title = titleWithBrand(q, brand, notes, lang);
+            b.h1 = q;
+            b.firstSentence = F(L("the direct answer in one sentence, quotable on its own", "tek başına alıntılanabilen, tek cümlelik doğrudan cevap"));
+            b.blocks = [
+                L("The answer in the first 1–3 sentences (key claim within the first ~200 characters).", "Cevap ilk 1–3 cümlede (asıl iddia ilk ~200 karakterde)."),
+                L("Steps or details in plain HTML.", "Adımlar ya da ayrıntılar düz HTML’de."),
+                L("A link to the situation page that solves it with the product.", "Ürünle çözen durum sayfasına link."),
+                L("Sources and dates for any number.", "Her sayı için kaynak ve tarih."),
+                L("Updated date and author.", "Güncelleme tarihi ve yazar."),
+            ];
+            b.related = (r?.situations ?? []).slice(0, 3).map((x) => situationUrl(x, r?.site.languages)).concat(guidePath ? [guidePath] : []);
+            b.jsonLd = [L("Article (headline = the question, datePublished, dateModified, author)", "Article (headline = soru, datePublished, dateModified, author)"), L("FAQPage only if there's a visible FAQ", "Yalnızca görünür SSS varsa FAQPage"), crumbs, sitewide];
+            notes.push(L("Publish 5–10 new pages a week at most; if a template's “crawled – not indexed” rate passes 30%, merge or noindex. Mass-produced pages count as scaled content abuse.", "Haftada en fazla 5–10 yeni sayfa; bir şablonun “tarandı, dizine eklenmedi” oranı %30’u geçerse birleştirin ya da noindex yapın. Seri üretilmiş sayfalar ölçekli içerik istismarı sayılır."));
+            break;
+        }
+        case "glossary": {
+            b.url = findPage(known, "glossary")?.path ?? (primaryTr ? "/sozluk" : "/glossary");
+            b.title = titleWithBrand(L(`${category ?? "[FILL]"} glossary`, `${category ?? "[DOLDUR]"} sözlüğü`), brand, notes, lang);
+            b.h1 = L(`${category ?? F("category")} glossary`, `${category ?? F("kategori")} sözlüğü`);
+            b.firstSentence = L("One line on what the glossary covers; every term's first sentence is its definition.", "Sözlüğün neyi kapsadığına dair bir satır; her terimin ilk cümlesi tanımıdır.");
+            b.blocks = [L("One <h2> or <dt> per term; the definition first, then a link to the page that uses it.", "Her terim için bir <h2> ya da <dt>; önce tanım, sonra onu kullanan sayfaya link."), L("Link the glossary from the footer (a glossary with no links in doesn't get indexed).", "Sözlüğe altbilgiden link verin (hiç link almayan sözlük dizine girmez).")];
+            b.jsonLd = [L("DefinedTermSet with one DefinedTerm per visible term", "Görünen her terim için bir DefinedTerm içeren DefinedTermSet"), crumbs];
+            b.related = [faqPath, ...(guidePath ? [guidePath] : [])];
+            break;
+        }
+        case "tool": {
+            const topic = c.topic ?? F(L("the tool, e.g. a calculator or a finder", "araç, ör. bir hesaplayıcı ya da bulucu"));
+            b.topic = topic;
+            b.url = c.topic ? `/tools/${slugify(c.topic, 5)}` : "/tools/" + F("tool-name");
+            b.urlSuggested = true;
+            b.title = titleWithBrand(topic, brand, notes, lang);
+            b.h1 = F(L("what the tool does, in the customer's words", "aracın ne yaptığı, müşterinin kelimeleriyle"));
+            b.firstSentence = F(L("what it does and what you get, in one sentence", "ne yaptığı ve ne elde edildiği, tek cümlede"));
+            b.action = L("The tool itself, usable without an account.", "Aracın kendisi, hesap olmadan kullanılabilir.");
+            b.blocks = [
+                L("The tool (it may need JavaScript).", "Araç (JavaScript gerekebilir)."),
+                L("An 80+ word written explanation in plain HTML: bots don't run the tool (the sample site's quiz page showed bots 27 words until an 86-word section was added).", "Düz HTML’de 80+ kelimelik yazılı açıklama: botlar aracı çalıştırmaz (örnek sitenin test sayfası 86 kelimelik bölüm eklenene kadar botlara 27 kelime gösteriyordu)."),
+                L("How it works: 3–5 steps.", "Nasıl çalışır: 3–5 adım."),
+                L("A link to the product's matching situation page.", "Ürünün ilgili durum sayfasına link."),
+                L("FAQ 5–8.", "SSS 5–8."),
+            ];
+            b.faq = genericFaq;
+            b.related = (r?.situations ?? []).slice(0, 3).map((x) => situationUrl(x, r?.site.languages)).concat(pricingPath);
+            b.jsonLd = [L("WebApplication (name, description, url; offers only if a price is shown)", "WebApplication (name, description, url; fiyat yalnızca görünüyorsa offers)"), faqLd, crumbs, sitewide];
+            break;
+        }
+        case "home": {
+            b.url = "/";
+            b.title = brand && category ? `${brand} — ${category}` : F(L("brand — category (the home title states the category)", "marka — kategori (ana sayfa title’ı kategoriyi söyler)"));
+            if (b.title.length > 60)
+                notes.push(L(`Title is ${b.title.length} characters: shorten the category wording.`, `Title ${b.title.length} karakter: kategori ifadesini kısaltın.`));
+            b.h1 = F(L("the main promise in the customer's words (often the top situation)", "müşterinin kelimeleriyle ana vaat (çoğunlukla en önemli durum)"));
+            b.firstSentence = sentence ? L(`The one sentence, word for word: “${sentence}”`, `Tek cümle, aynen: “${sentence}”`) : F(L("the one sentence", "tek cümle"));
+            b.action = F(L("the main action (try it / pricing)", "ana eylem (dene / fiyat)"));
+            b.blocks = [
+                L("The one sentence in the first paragraph and the meta description, word for word.", "Tek cümle ilk paragrafta ve meta açıklamada, aynen."),
+                L("Links to every situation page (text links, not only cards with onClick).", "Her durum sayfasına link (yalnızca onClick’li kartlar değil, metinli linkler)."),
+                L("Links to pricing, the comparison guide, FAQ, About.", "Fiyat, karşılaştırma rehberi, SSS ve Hakkımızda’ya link."),
+                L("Proof with a source and date.", "Kaynaklı ve tarihli kanıt."),
+                notX ? L(`A short not-X line: “${notX}”`, `Kısa bir “X değildir” satırı: “${notX}”`) : L("A not-X line only if the brand gets confused with something.", "“X değildir” satırı yalnızca marka bir şeyle karışıyorsa."),
+            ];
+            b.related = [...(r?.situations ?? []).map((x) => situationUrl(x, r?.site.languages)).slice(0, 8), pricingPath, ...(guidePath ? [guidePath] : []), faqPath, aboutPath];
+            b.jsonLd = [L("Organization (alternateName, disambiguatingDescription, sameAs, logo)", "Organization (alternateName, disambiguatingDescription, sameAs, logo)"), L("WebSite", "WebSite"), L("SoftwareApplication / WebApplication if the product lives here (offers only as shown on the site)", "Ürün buradaysa SoftwareApplication / WebApplication (offers yalnızca sitede görünen)")];
+            notes.push(L("A vague home page is a common mistake: most AI referrals land on the home page, and ChatGPT names you as a brand.", "Belirsiz bir ana sayfa sık yapılan bir hata: yapay zekâdan gelenlerin çoğu ana sayfaya iner ve ChatGPT sizi marka olarak anar."));
+            break;
+        }
+    }
+    const loc = pageLocation(c.scan, b.url.includes("[FILL") ? "/new-page" : b.url, c.staticDir ?? "");
+    b.files = loc.files;
+    b.fileNotes = loc.notes.map((n) => t(n, lang));
+    if (isCsr(c.scan))
+        notes.unshift(L("This site renders in the browser: do P2 first or the new page will be empty for bots.", "Bu site tarayıcıda render ediliyor: önce P2’yi yapın, yoksa yeni sayfa botlar için boş olur."));
+    return { brief: b };
+}
+export function renderBriefMd(b, c) {
+    const lang = c.lang;
+    const L = (en, tr) => (lang === "tr" ? tr : en);
+    const list = (xs) => (xs.length ? xs.map((x) => `  - ${x}`).join("\n") : "  - –");
+    const out = [];
+    out.push(`# ${L("Page brief", "Sayfa brifi")}: ${b.type}${b.situation ? ` — “${b.situation.sentence}”` : b.topic ? ` — ${b.topic}` : ""}`);
+    out.push(L("Book ch. 9. Fill every [FILL] from research or ask the user; never invent proof, prices or competitor facts.", "Kitap, 9. bölüm. Her [DOLDUR]’u araştırmadan doldurun ya da kullanıcıya sorun; kanıt, fiyat ya da rakip bilgisi uydurmayın."));
+    out.push([
+        b.situation ? `- **${L("Situation", "Durum")}:** \`${b.situation.id}\` ${b.situation.sentence}` : "",
+        `- **URL:** ${b.url}${b.urlSuggested ? L(" (suggested — same words as the H1; lowercase, hyphens)", " (öneri — H1 ile aynı kelimeler; küçük harf, tire)") : ""}`,
+        `- **Title** (${b.title.length} ${L("chars", "karakter")}): ${b.title}`,
+        `- **H1:** ${b.h1}`,
+        `- **${L("First sentence", "İlk cümle")}:** ${b.firstSentence}`,
+        b.action ? `- **${L("Action", "Eylem")}:** ${b.action}` : "",
+        `- **${L("Proof", "Kanıt")}:**\n${list(b.proof)}`,
+        b.notFor.length ? `- **${L("Not for", "Kimler için değil")}:**\n${list(b.notFor)}` : "",
+        b.alternatives.length ? `- **${L("Alternatives", "Alternatifler")}:**\n${list(b.alternatives)}` : "",
+        b.faq.length ? `- **${L("FAQ (5–8, in the customer's words; keep only what customers really ask)", "SSS (5–8, müşterinin ağzından; yalnızca gerçekten sorulanları tutun)")}:**\n${list(b.faq)}` : "",
+        b.related.length ? `- **${L("Related pages (text links)", "İlgili sayfalar (metinli link)")}:**\n${list(b.related)}` : "",
+    ]
+        .filter(Boolean)
+        .join("\n"));
+    out.push(`## ${b.type === "situation" ? L("The 11 blocks, in order", "11 blok, sırayla") : L("Blocks", "Bloklar")}\n${b.blocks.map((x) => (/^\d+\./.test(x) ? x : `- ${x}`)).join("\n")}`);
+    out.push(`## ${L("JSON-LD to include (only information visible on the page)", "Eklenecek JSON-LD (yalnızca sayfada görünen bilgi)")}\n${b.jsonLd.map((x) => `- ${x}`).join("\n")}`);
+    out.push(`## ${L("Where the file goes", "Dosya nereye")} (${fwLabel(c.scan)})\n${b.files.map((f) => `- \`${f}\``).join("\n")}${b.fileNotes.length ? `\n${b.fileNotes.map((n) => `- ${n}`).join("\n")}` : ""}`);
+    if (b.notes.length)
+        out.push(`## ${L("Notes", "Notlar")}\n${b.notes.map((n) => `- ${n}`).join("\n")}`);
+    const next = [];
+    if (b.type === "situation")
+        next.push(fmtCallShort(calls.prompt(c.root, "P6", b.situation?.id)));
+    if (b.type === "comparison")
+        next.push(fmtCallShort(calls.prompt(c.root, "P7")));
+    next.push(fmtCallShort(calls.lint(c.root, { file: b.files[0] ?? "[FILL]", page_type: b.type, ...(b.situation ? { situation_id: b.situation.id } : {}) })));
+    const site = siteUrlOf(c.research, c.config);
+    if (site && !b.url.includes("[FILL"))
+        next.push(`${L("after deploy", "yayından sonra")}: ${fmtCallShort(calls.auditUrls(c.root, [`${site}${b.url}`]))}`);
+    out.push(`## ${L("Then", "Sonra")}\n${next.map((n) => `- ${n}`).join("\n")}`);
+    return out.join("\n\n");
+}
+export async function runBrief(root, args) {
+    const [research, config, scan, loaded] = await Promise.all([loadResearchSafe(root), loadConfigSafe(root), loadScan(root), loadLatestAudit(root)]);
+    const lang = args.lang ?? config.lang ?? "en";
+    const ctx = { root, lang, research, config, scan, audit: loaded?.audit, staticDir: staticDirFor(root, scan).dir, situationId: args.situationId, topic: args.topic };
+    const { brief, error } = buildBrief(args.type, ctx);
+    if (!brief)
+        return { text: error ?? "Couldn't build the brief.", isError: true };
+    const pre = research ? "" : `No research yet: most fields are [FILL]. Start with ${fmtCallShort(calls.researchTemplate(root))}.\n\n`;
+    return { text: pre + renderBriefMd(brief, ctx), structured: brief };
+}