katman-mcp 0.1.0

package/dist/tools/method/data/verify.js

@@ -0,0 +1,88 @@
+export const VERIFY_INTRO = {
+    en: "Don't trust the coding tool saying “done”. These commands run in a Mac or Linux terminal.",
+    tr: "Kod aracının “yaptım” demesine güvenmeyin. Bu komutlar Mac ve Linux terminalinde çalışır.",
+};
+export const NINE_COMMANDS = [
+    {
+        n: 1,
+        title: { en: "Does the page return 200; does http go to https?", tr: "Sayfa 200 dönüyor mu, http https'e gidiyor mu?" },
+        cmd: `curl -sI {site_url}/ | head -1
+curl -sI http://{domain}/ | grep -i -E "^HTTP|^location"`,
+        expect: { en: "HTTP/2 200; the http request answers 301/308 with location: https://…", tr: "HTTP/2 200; http isteği 301/308 ve location: https://… ile cevap veriyor" },
+        katman: "katman_audit_site → status, site.httpsRedirect",
+    },
+    {
+        n: 2,
+        title: { en: "Is a missing URL a real 404?", tr: "Olmayan adres gerçek 404 mü?" },
+        cmd: `curl -s -o /dev/null -w "%{http_code}\\n" {site_url}/this-page-does-not-exist`,
+        expect: { en: "404", tr: "404" },
+        katman: "katman_audit_site → site.soft404",
+    },
+    {
+        n: 3,
+        title: { en: "Title, description, canonical, robots, og:image", tr: "Title, açıklama, canonical, robots, og:image" },
+        cmd: `curl -s {site_url}/ | grep -o -i -E '<title>[^<]*|name="description" content="[^"]*|rel="canonical" href="[^"]*|name="robots" content="[^"]*|og:image" content="[^"]*'`,
+        expect: { en: "All five present; canonical is the page's own full URL; no unwanted noindex", tr: "Beşi de var; canonical sayfanın kendi tam adresi; istenmeyen noindex yok" },
+        katman: "katman_audit_site → title, description, canonicalSelf, noindex, ogImage",
+    },
+    {
+        n: 4,
+        title: { en: "How many words are visible without JavaScript?", tr: "JavaScript olmadan kaç kelime görünüyor?" },
+        cmd: `curl -s {site_url}/ | sed 's/<[^>]*>/ /g' | wc -w`,
+        expect: { en: "Hundreds, not a few dozen", tr: "Birkaç düzine değil, yüzlerce" },
+        katman: "katman_audit_site → pages[].wordsJsOff",
+    },
+    {
+        n: 5,
+        title: { en: "Can AI bots get in? (all should be 200)", tr: "Yapay zekâ botları içeri girebiliyor mu? (hepsi 200 olmalı)" },
+        cmd: `for b in GPTBot/1.2 OAI-SearchBot/1.0 ClaudeBot/1.0 PerplexityBot/1.0; do
+  echo "$b $(curl -s -o /dev/null -w '%{http_code}' -A "Mozilla/5.0 (compatible; $b)" {site_url}/)"; done`,
+        expect: { en: "200 for every bot", tr: "Her bot için 200" },
+        katman: "katman_audit_site → site.bots",
+    },
+    {
+        n: 6,
+        title: { en: "robots.txt and the sitemap", tr: "robots.txt ve sitemap" },
+        cmd: `curl -s {site_url}/robots.txt
+curl -s {site_url}/sitemap.xml | grep -c "<loc>"`,
+        expect: { en: "No Disallow: /, a Sitemap line; the number of URLs you expect", tr: "Disallow: / yok, Sitemap satırı var; beklediğiniz sayıda adres" },
+        katman: "katman_audit_site → site.robots, site.sitemapUrls",
+    },
+    {
+        n: 7,
+        title: { en: "Is the page's JSON-LD valid JSON? (needs python3)", tr: "Sayfadaki JSON-LD geçerli JSON mu? (python3 gerekir)" },
+        cmd: `curl -s {site_url}/ | python3 -c "import sys,re,json; b=re.findall(r'<script[^>]*application/ld\\+json[^>]*>(.*?)</script>', sys.stdin.read(), re.S); [json.loads(x) for x in b]; print(len(b), 'valid JSON-LD blocks')"`,
+        expect: { en: "N valid JSON-LD blocks, no traceback", tr: "N geçerli JSON-LD bloğu, hata yok" },
+        katman: "katman_audit_site → pages[].jsonLdErrors",
+    },
+    {
+        n: 8,
+        title: { en: "Mobile speed and SEO score", tr: "Mobil hız ve SEO puanı" },
+        cmd: `npx lighthouse {site_url}/ --form-factor=mobile --only-categories=performance,seo --view`,
+        expect: { en: "LCP ≤ 2.5 s, CLS ≤ 0.1, SEO 100", tr: "LCP ≤ 2,5 sn, CLS ≤ 0,1, SEO 100" },
+        katman: "manual (Katman doesn't run Lighthouse)",
+    },
+    {
+        n: 9,
+        title: { en: "Is the HTML compressed? (re-check after every technical fix)", tr: "HTML sıkıştırılıyor mu? (her teknik düzeltmeden sonra tekrar)" },
+        cmd: `curl -s -o /dev/null -D - -H 'Accept-Encoding: br, gzip' {site_url}/ | grep -i content-encoding`,
+        expect: { en: "content-encoding: br (or gzip)", tr: "content-encoding: br (ya da gzip)" },
+        katman: "katman_audit_site → site.compression",
+    },
+];
+export const BROWSER_CHECKS = [
+    {
+        en: "Search Console → URL Inspection → Test live URL → View tested page: the HTML and screenshot Google sees. If your text isn't there, it isn't in Google either.",
+        tr: "Search Console → URL denetimi → Canlı URL’yi test et → Taranan sayfayı görüntüle: Google’ın gördüğü HTML ve ekran görüntüsü. Metniniz burada yoksa Google’da da yok.",
+    },
+    { en: "Rich Results Test (search.google.com/test/rich-results): JSON-LD errors.", tr: "Zengin Sonuçlar Testi (search.google.com/test/rich-results): JSON-LD hataları." },
+    {
+        en: "Chrome → Developer tools → Settings → Disable JavaScript: see the page through the bot's eyes.",
+        tr: "Chrome → Geliştirici araçları → Ayarlar → JavaScript’i devre dışı bırak: sayfayı botun gözüyle görün.",
+    },
+    { en: "Paste a link into a chat app: does the og:image card appear?", tr: "Bir sohbet uygulamasına link yapıştırın: og:image kartı çıkıyor mu?" },
+];
+export const VERIFY_EXERCISE = {
+    en: "Run the nine commands on your home page and on your most important situation page. Paste the output into research; run them again in 30 days and compare.",
+    tr: "Dokuz komutu kendi sitenizin ana sayfasında ve en önemli durum sayfanızda çalıştırın. Çıktıları research.md’ye yapıştırın; 30 gün sonra tekrar çalıştırıp karşılaştırın.",
+};

package/dist/tools/method/data/viral-list.js

@@ -0,0 +1,39 @@
+export const VERDICT_LABEL = {
+    true: { en: "TRUE", tr: "DOĞRU" },
+    partly: { en: "PARTLY", tr: "KISMEN" },
+    myth: { en: "MYTH", tr: "EFSANE" },
+};
+export const VIRAL_LIST = [
+    { n: 1, item: { en: "noindex tags", tr: "noindex etiketleri" }, verdict: "true", google: { en: "noindex removes a page from the index. If robots.txt closes the same URL, Google never sees the noindex and the URL can still appear.", tr: "noindex sayfayı dizinden çıkarır. robots.txt aynı adresi kapatırsa Google noindex’i hiç göremez ve adres yine çıkabilir." } },
+    { n: 2, item: { en: "Page titles", tr: "Sayfa başlıkları (title)" }, verdict: "true", google: { en: "A separate, descriptive title for every page. Google may write the title it shows itself, from the H1 or og:title.", tr: "Her sayfaya ayrı, içeriği anlatan bir title. Google sonuçta gösterdiği başlığı kendisi yazabilir; H1’i ya da og:title’ı kullanabilir." } },
+    { n: 3, item: { en: "Meta descriptions", tr: "Meta açıklamalar" }, verdict: "partly", google: { en: "The snippet mostly comes from the page text; the meta description is used only sometimes. No ranking effect is stated. Write a separate one for every page.", tr: "Snippet çoğunlukla sayfanın metninden çıkar; meta açıklama yalnızca bazen kullanılır. Sıralama etkisi yazmıyor. Her sayfaya ayrı yazın." } },
+    { n: 4, item: { en: "Image alt text", tr: "Görsellere alt metin" }, verdict: "true", google: { en: "Google understands images through alt text, image recognition and page text. Keyword-stuffed alt text can count as spam.", tr: "Google görseli alt metin, görüntü tanıma ve sayfa metniyle anlar. Anahtar kelime doldurulmuş alt metin spam sayılabilir." } },
+    { n: 5, item: { en: "Core Web Vitals", tr: "Core Web Vitals" }, verdict: "partly", google: { en: "Used in ranking. Good: LCP ≤ 2.5 s, INP ≤ 200 ms, CLS ≤ 0.1 (at 75% of page loads). Not decisive on its own; relevance comes first.", tr: "Sıralamada kullanılır. İyi: LCP ≤ 2,5 sn, INP ≤ 200 ms, CLS ≤ 0,1 (sayfa yüklemelerinin %75’inde). Tek başına belirleyici değil; alakalılık önce gelir." } },
+    { n: 6, item: { en: "sitemap.xml", tr: "sitemap.xml" }, verdict: "partly", google: { en: "Helps discovery but doesn't guarantee indexing. A well-linked site under ~500 pages may not need one.", tr: "Keşfe yardım eder, dizine almayı garanti etmez. Yaklaşık 500 sayfanın altındaki, iyi linklenmiş bir site ihtiyaç duymayabilir." } },
+    { n: 7, item: { en: "og:image", tr: "og:image" }, verdict: "partly", google: { en: "The Open Graph protocol is for share previews. Since 2 March 2026 Google also uses og:image as a source for the search thumbnail; no effect on indexing or ranking.", tr: "Açık Grafik protokolü paylaşım önizlemesi içindir. Google 2 Mart 2026’dan beri og:image’i arama küçük resmi için bir kaynak olarak da kullanıyor; dizine alma ya da sıralama etkisi yok." } },
+    { n: 8, item: { en: "Broken links", tr: "Kırık linkler" }, verdict: "partly", google: { en: "404s don't penalise the rest of the site on their own; a URL returning 4xx drops out of the index. Fix broken links to important pages; 301 moved URLs.", tr: "404’ler sitenin geri kalanını tek başına cezalandırmaz; 4xx dönen adres dizinden düşer. Önemli sayfalara giden kırık linkleri düzeltin, taşınan adresi 301 ile yönlendirin." } },
+    { n: 9, item: { en: "Heading hierarchy", tr: "Başlık hiyerarşisi" }, verdict: "partly", google: { en: "Heading order doesn't matter to Google; a clean order helps screen readers. Bing wants a logical H1–H6 structure.", tr: "Google için başlıkların sırası önemli değil; düzgün sıra ekran okuyuculara yardım eder. Bing mantıklı bir H1–H6 düzeni istiyor." } },
+    { n: 10, item: { en: "Backlink strategy", tr: "Backlink stratejisi" }, verdict: "partly", google: { en: "Google finds pages mostly through links and expects links to come naturally over time. Buying links and excessive link exchanges are spam.", tr: "Google sayfaları çoğunlukla linklerle bulur ve linklerin zamanla doğal gelmesini bekler. Link satın almak ve aşırı link takası spam." } },
+    { n: 11, item: { en: "Clean URLs", tr: "Temiz URL’ler" }, verdict: "partly", google: { en: "Readable words, hyphens instead of underscores. Words in the URL have very little ranking effect. If you change a live URL, a 301 is a must.", tr: "Okunabilir kelimeler, alt çizgi yerine tire. URL’deki kelimelerin sıralamaya etkisi çok az. Canlı adresi değiştirirseniz 301 şart." } },
+    { n: 12, item: { en: "Internal links", tr: "İç linkler" }, verdict: "true", google: { en: "Link to every page you care about from another page. A link must be an <a> with an href; the link text should describe the target.", tr: "Önem verdiğiniz her sayfaya başka bir sayfadan link verin. Link, href’i olan bir <a> olmalı; link metni hedefi anlatmalı." } },
+    { n: 13, item: { en: "Canonical tags", tr: "Canonical etiketleri" }, verdict: "partly", google: { en: "rel=canonical is a strong signal but a hint, not a rule. None of it is mandatory; Google also picks the canonical itself.", tr: "rel=canonical güçlü bir işaret ama kural değil, ipucu. Hiçbiri zorunlu değil; Google kanonik adresi kendisi de seçer." } },
+    { n: 14, item: { en: "HTTPS everywhere", tr: "HTTPS zorunlu" }, verdict: "true", google: { en: "HTTPS is a small ranking signal and part of page experience. Among equivalent pages Google picks the HTTPS one as canonical.", tr: "HTTPS küçük bir sıralama işareti ve sayfa deneyiminin parçası. Google eşdeğer sayfalarda HTTPS olanı kanonik seçer." } },
+    { n: 15, item: { en: "Compress images", tr: "Görselleri sıkıştır" }, verdict: "true", google: { en: "Images are often the biggest part of page weight. The benefit is indirect: speed and LCP. WebP and AVIF are supported.", tr: "Görseller çoğu zaman sayfa boyutunun en büyük parçası. Faydası dolaylı: hız ve LCP. WebP ve AVIF destekleniyor." } },
+    { n: 16, item: { en: "Schema markup", tr: "Schema işaretlemesi" }, verdict: "partly", google: { en: "Only makes you eligible for rich results, no guarantee; must match the visible content. The HowTo rich result was retired in 2023, the FAQ rich result on 7 May 2026.", tr: "Yalnızca zengin sonuca aday yapar, garanti vermez; görünen içerikle aynı olmalı. HowTo zengin sonucu 2023’te, SSS zengin sonucu 7 Mayıs 2026’da kalktı." } },
+    { n: 17, item: { en: "Verify Search Console", tr: "Search Console doğrula" }, verdict: "partly", google: { en: "Not required to be indexed; most pages are found on their own. It's a monitoring and debugging tool (URL Inspection, sitemap report).", tr: "İndekslenmek için gerekmez; sayfaların çoğu kendiliğinden bulunur. İzleme ve hata ayıklama aracıdır (URL denetimi, sitemap raporu)." } },
+    { n: 18, item: { en: "One H1 per page", tr: "Sayfada tek H1" }, verdict: "myth", google: { en: "According to Google there's no ideal number of headings; more than one H1 is fine.", tr: "Google’a göre ideal bir başlık sayısı yok; birden fazla H1 sorun değil." } },
+    { n: 19, item: { en: "Write a robots.txt", tr: "robots.txt yaz" }, verdict: "partly", google: { en: "Not mandatory: if robots.txt returns 404, Google treats it as no restrictions. It manages crawling, not indexing; it doesn't hide a page from Google.", tr: "Zorunlu değil: robots.txt 404 dönerse Google kısıtlama yok sayar. Taramayı yönetir, dizine almayı değil; bir sayfayı Google’dan saklamaz." } },
+    { n: 20, item: { en: "Mobile friendly", tr: "Mobil uyum" }, verdict: "true", google: { en: "Google indexes and ranks the mobile version of the site. Responsive design is recommended; content, headings and schema must be the same on mobile.", tr: "Google sitenin mobil hâlini dizine alır ve sıralar. Duyarlı tasarım önerilir; içerik, başlıklar ve schema mobilde de aynı olmalı." } },
+];
+export const VIRAL_LIST_MISLEADING = [
+    { en: "One H1: according to Google there's no ideal number of headings. One H1 is a tidy habit, not a ranking rule.", tr: "Tek H1: Google’a göre ideal bir başlık sayısı yok. Tek H1 düzenli bir alışkanlık, sıralama kuralı değil." },
+    { en: "“Write a robots.txt”: you can do without one. Written wrong, it does harm: Disallow: / closes the whole site; closing a noindex page in robots.txt hides the noindex from Google.", tr: "“robots.txt yaz”: Yazmasanız da olur. Yanlış yazarsanız zarar verir: Disallow: / bütün siteyi kapatır; noindex’li bir sayfayı robots.txt’de kapatırsanız Google noindex’i göremez." },
+    { en: "Schema: no rich-result guarantee. HowTo was retired in 2023, the FAQ rich result on 7 May 2026.", tr: "Schema: Zengin sonuç garantisi yok. HowTo 2023’te, SSS zengin sonucu 7 Mayıs 2026’da Google’dan kalktı." },
+    { en: "Search Console: not needed to get indexed; needed to see the errors.", tr: "Search Console: İndekslenmek için gerekmez; hatayı görmek için gerekir." },
+    { en: "Backlink “strategy”: bought links and link exchanges are in Google's spam policy. Links come when you publish something others want to quote.", tr: "Backlink “stratejisi”: Satın alınan link ve link takası Google’ın spam politikasında. Link, başkasının alıntılamak isteyeceği bir şey yayınlayınca gelir." },
+    { en: "The real gap: the three things that most often make a vibe-coded site invisible aren't on the list at all — text in JavaScript, soft 404s, and open preview copies.", tr: "Asıl eksik: Vibe-coded bir siteyi en sık görünmez yapan üç şey listede hiç yok: metnin JavaScript’te olması, sahte 404’ler, açık kalmış önizleme kopyaları." },
+];
+export const VIRAL_LIST_FOUND = {
+    en: "Not on the list, found on katman.pro: AI training bots (GPTBot, ClaudeBot, CCBot, Bytespider) were getting 403 because of Cloudflare's legacy “Block AI bots” toggle. The list's biggest gap: if a bot can't get through the door, none of the other 20 items matter to the assistant.",
+    tr: "Listede yok, katman.pro’da bulduk: Yapay zekâ eğitim botları (GPTBot, ClaudeBot, CCBot, Bytespider) Cloudflare’deki eski “Block AI bots” düğmesi yüzünden 403 alıyordu. Listenin en büyük eksiği bu: bot kapıdan giremiyorsa diğer 20 maddenin asistan tarafında karşılığı yok.",
+};

package/dist/tools/method/index.js

@@ -0,0 +1,209 @@
+// Method module: the Katman book as tools (katman_start, katman_research, katman_plan, katman_prompt,
+// katman_page_brief, katman_generate, katman_lint_content, katman_report), MCP prompts and resources.
+import { z } from "zod";
+import { resolveRoot, rootWarning } from "../../context.js";
+import { fail, ok } from "../../util.js";
+import { PRO_NOTE, startLicense, withPro } from "../../license.js";
+import { hasOpenRouterKey } from "./lib/calls.js";
+import { runStart } from "./core/start.js";
+import { runResearch } from "./core/research-run.js";
+import { runPlan } from "./core/plan.js";
+import { runPrompt } from "./core/prompt.js";
+import { BRIEF_TYPES, runBrief } from "./core/brief.js";
+import { ARTIFACTS, runGenerate } from "./core/generate.js";
+import { PAGE_TYPES_LINT, runLint } from "./core/lint.js";
+import { runReport } from "./core/report.js";
+import { BOT_PLATFORMS } from "./core/snippets.js";
+import { registerMethodPrompts } from "./mcp/prompts.js";
+import { registerMethodResources } from "./mcp/resources.js";
+const projectRoot = z
+    .string()
+    .optional()
+    .describe("Absolute path of the website's codebase. Default: KATMAN_PROJECT_ROOT, then the client's workspace root, then the server's cwd.");
+const lang = z.enum(["en", "tr"]).optional().describe("Output language: en or tr (default: .katman/config.json lang, else en).");
+const QUESTION_TYPES = ["situation", "tool", "best", "alternative", "market", "problem", "diagnostic"];
+const researchData = z
+    .object({
+    site: z
+        .object({
+        url: z.string().optional().describe("Live site URL, e.g. https://example.com"),
+        languages: z.array(z.string()).optional().describe("Site languages, primary first, e.g. [\"en\", \"tr\"]"),
+        previewUrls: z.array(z.string()).optional().describe("Preview/staging hosts that must redirect or be noindex"),
+    })
+        .optional(),
+    brand: z
+        .object({
+        name: z.string().describe("One distinctive name"),
+        alternateNames: z.array(z.string()),
+        category: z.string().describe("What it is, e.g. \"AI invoice scanner\""),
+        notX: z.string().describe("What it's NOT confused with (ask ChatGPT \"What is <brand>?\"), or \"none\""),
+        oneLiner: z
+            .object({
+            brings: z.string().describe("What the customer brings"),
+            weDo: z.string().describe("What we do"),
+            gets: z.string().describe("What they get"),
+            fear: z.string().describe("Which fear is unnecessary"),
+        })
+            .partial(),
+        sentence: z.string().describe("Optional hand-written final one sentence (else composed from oneLiner)"),
+        pricing: z.string().describe("Exactly as on the pricing page"),
+        company: z.string(),
+        country: z.string(),
+        socials: z.array(z.string()),
+    })
+        .partial()
+        .optional(),
+    situations: z
+        .array(z.object({
+        id: z.string().optional(),
+        sentence: z.string().describe("The customer's own sentence, no brand name"),
+        url: z.string().optional().describe("Planned or live path, e.g. /import-pdf-invoices"),
+        status: z.enum(["planned", "live"]).optional(),
+    }))
+        .optional(),
+    competitors: z
+        .array(z.object({
+        name: z.string(),
+        url: z.string().optional().describe("The competitor's own page the facts come from"),
+        what: z.string().optional(),
+        price: z.string().optional(),
+        forWhom: z.string().optional(),
+        source: z.string().optional(),
+        checkedAt: z.string().optional().describe("YYYY-MM-DD"),
+    }))
+        .optional(),
+    proof: z
+        .array(z.object({ claim: z.string(), value: z.string().optional(), source: z.string().optional().describe("Link or document"), date: z.string().optional() }))
+        .optional(),
+    keywords: z
+        .array(z.object({ term: z.string(), page: z.string().optional(), source: z.enum(["autocomplete", "search-console", "bing", "manual"]).optional() }))
+        .optional(),
+    questions: z.array(z.object({ id: z.string().optional(), type: z.enum(QUESTION_TYPES).optional(), text: z.string() })).optional(),
+})
+    .describe("Research fields to merge");
+const generateOptions = z
+    .object({
+    app_paths: z.array(z.string()).optional().describe("robots.txt: extra app paths to close, e.g. [\"/app\", \"/account\"]"),
+    training: z.enum(["allow", "block"]).optional().describe("robots.txt: AI training bots (default allow; search/user bots always allowed)"),
+    sitemap_url: z.string().optional(),
+    faq: z.array(z.object({ q: z.string(), a: z.string() })).optional().describe("faq-jsonld: the exact Q&A visible on the page"),
+    items: z.array(z.object({ name: z.string(), url: z.string() })).optional().describe("breadcrumb-jsonld: Home → … → page"),
+    target: z.enum(["auto", "gtag", "gtm", "plausible", "posthog", "none"]).optional().describe("analytics-channel-snippet: where to push events"),
+    platform: z.enum(BOT_PLATFORMS).optional().describe("bot-counter-snippet platform"),
+    type: z.enum(["SoftwareApplication", "WebApplication"]).optional(),
+    application_category: z.string().optional(),
+    logo: z.string().optional().describe("organization-jsonld: logo URL"),
+    page_url: z.string().optional(),
+})
+    .optional();
+function wrap(ctx, fn, opts = {}) {
+    return async (args) => {
+        try {
+            const root = await resolveRoot(ctx, args.project_root);
+            const out = await fn(root, args);
+            const warning = opts.warn === false ? undefined : rootWarning(root);
+            const text = warning ? `**Warning:** ${warning}\n\n${out.text}` : out.text;
+            return out.isError ? fail(text) : ok(text, out.structured);
+        }
+        catch (e) {
+            return fail(`Katman error: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    };
+}
+export function registerMethodTools(server, ctx) {
+    server.registerTool("katman_start", {
+        title: "Katman: start here",
+        description: "Call this FIRST, and again after every step. Shows the Katman method (gates Read / Quote / Fit; steps Research → Plan → Build → Verify), the status of each step from .katman/ (research %, scan, audit, plan tasks, visibility runs, 14-day re-measure) and the NEXT STEP as an exact tool call with arguments — do that next. Pass project_root (absolute path of the site's codebase) and site_url when known; site_url is saved to .katman/config.json. Writes nothing else.",
+        inputSchema: {
+            project_root: projectRoot,
+            site_url: z.string().optional().describe("The live site URL, e.g. https://example.com (saved to .katman/config.json)"),
+            lang,
+        },
+        annotations: { title: "Katman: start here", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async (args) => {
+        try {
+            const root = await resolveRoot(ctx, args.project_root);
+            const out = await runStart(root, { siteUrl: args.site_url, hasOpenRouterKey: hasOpenRouterKey(), warning: rootWarning(root), lang: args.lang, license: await startLicense(ctx) });
+            return out.isError ? fail(out.text) : ok(out.text, out.structured);
+        }
+        catch (e) {
+            return fail(`Katman error: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
+    server.registerTool("katman_research", {
+        title: "Katman: research (step 1)",
+        description: "Step 1. Creates and maintains .katman/research.json + research.md: brand, category, the one sentence in 4 parts (brings → weDo → gets → fear), not-X note, 10–12 unbranded customer situations, competitors (url + checkedAt), proof (with source), keywords, question set. mode template = skeleton; update = merge data (lists merge by id/name/sentence; replace_lists replaces); show = print with completeness % and warnings. generate_questions builds the question set per site language (12+2 for the primary). Fill from the codebase, ask the user for customer sentences; never invent.",
+        inputSchema: {
+            project_root: projectRoot,
+            mode: z.enum(["template", "update", "show"]).optional().describe("Default: update when data/generate_questions is given, else show (or template when there's no research)"),
+            data: researchData.optional(),
+            replace_lists: z.boolean().optional().describe("Replace the lists given in data instead of merging (also allows regenerating the question set)"),
+            generate_questions: z.boolean().optional().describe("Build the 12 + 2 question set from research (book ch. 15) in the site's primary language"),
+            lang,
+        },
+        annotations: { title: "Katman: research", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, wrap(ctx, (root, a) => runResearch(root, { mode: a.mode, data: a.data, replaceLists: a.replace_lists, generateQuestions: a.generate_questions, lang: a.lang })));
+    server.registerTool("katman_plan", {
+        title: "Katman: plan (step 2)",
+        description: "Step 2. Builds .katman/plan.md + plan.json from research, scan.json, the latest audit and runs: the page plan (existing vs missing pages), what stays out of the index (noindex vs robots.txt Disallow), and the first-30-days task list (P-code, files, acceptance criterion, verifying tool; critical findings first). Ticks in plan.md are kept when it regenerates. Show the plan to the user and get approval before changing code. Re-run after new scans or audits." + PRO_NOTE,
+        inputSchema: { project_root: projectRoot, lang },
+        annotations: { title: "Katman: plan", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, withPro(ctx, "plan", wrap(ctx, (root, a) => runPlan(root, { lang: a.lang }))));
+    server.registerTool("katman_prompt", {
+        title: "Katman: prompt P0–P14 (step 3)",
+        description: "Step 3. Returns prompt P0–P14 from the Katman prompt book filled with this project's research (brand, domain, one sentence, not-X, competitors, situation) plus Accept (acceptance criterion), Why, how Katman verifies it (exact tool call) and framework notes from scan.json. Do the prompt, list the changed files, run the check; tick the task in .katman/plan.md only when it passes. P6 takes situation_id. Unknown values stay [FILL] — ask, don't guess. Read-only." + PRO_NOTE,
+        inputSchema: {
+            id: z.string().describe("Prompt id: P0–P14 (P0 context, P1 audit, P2 text in HTML, P3 head tags, P4 robots/sitemap, P5 schema, P6 situation page, P7 comparison guide, P8 llms.txt, P9 images, P10 links, P11 404/redirects, P12 speed, P13 measurement, P14 pre-release check)"),
+            project_root: projectRoot,
+            situation_id: z.string().optional().describe("For P6: the situation id from research (s1, s2…)"),
+            lang,
+        },
+        annotations: { title: "Katman: prompt", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, withPro(ctx, "prompts", wrap(ctx, (root, a) => runPrompt(root, { id: a.id, situationId: a.situation_id, lang: a.lang }))));
+    server.registerTool("katman_page_brief", {
+        title: "Katman: page brief",
+        description: "Filled page brief before writing a page: URL, title (situation first, ≈60 chars), H1, first sentence, action, proof, not-for, alternatives, FAQ candidates, related pages, the 11-block anatomy, the JSON-LD to include (only information visible on the page) and where the file goes in this framework. type: situation | comparison | pricing | faq | about | single-question | glossary | tool | home. Use it before P6 / P7. Read-only." + PRO_NOTE,
+        inputSchema: {
+            type: z.enum(BRIEF_TYPES).describe("Page type"),
+            project_root: projectRoot,
+            situation_id: z.string().optional().describe("For type situation: the research situation id (default: the next one without a page)"),
+            topic: z.string().optional().describe("For comparison / single-question / tool: the topic, question or tool name"),
+            lang,
+        },
+        annotations: { title: "Katman: page brief", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, withPro(ctx, "briefs", wrap(ctx, (root, a) => runBrief(root, { type: a.type, situationId: a.situation_id, topic: a.topic, lang: a.lang }))));
+    server.registerTool("katman_generate", {
+        title: "Katman: generate files from research",
+        description: "Generates from research (single source of truth): robots.txt (a group per AI bot, app paths closed with trailing slashes, auth pages left to noindex), llms.txt, Organization / WebSite / SoftwareApplication / FAQPage / BreadcrumbList JSON-LD, the AI-channel analytics snippet, a server-side bot counter, the IndexNow key file. Returns content + target path. write: true writes static files into the site's static dir (never over an existing file without overwrite: true) and code/JSON-LD into .katman/generated/; refuses while [FILL] remains." + PRO_NOTE,
+        inputSchema: {
+            artifact: z.enum(ARTIFACTS).describe("What to generate"),
+            project_root: projectRoot,
+            options: generateOptions,
+            write: z.boolean().optional().describe("Write the file (static artifacts into the static dir; code and JSON-LD into .katman/generated/)"),
+            overwrite: z.boolean().optional().describe("Allow replacing an existing file (review the diff first)"),
+        },
+        annotations: { title: "Katman: generate", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, withPro(ctx, "generate", wrap(ctx, (root, a) => runGenerate(root, { artifact: a.artifact, options: a.options, write: a.write, overwrite: a.overwrite }))));
+    server.registerTool("katman_lint_content", {
+        title: "Katman: check a page's content",
+        description: "Checks one page against the Katman content rules before shipping: first 1–3 sentences answer (≤35 words, no preamble), key claim in the first ~200 chars, one sentence consistent with research + llms.txt, hype words, unsourced numbers, placeholders, \"free\" on a paid product, update date, FAQ 5–8, not-for and alternatives sections, ≥3 internal links, title/description length; comparison pages: sources + dates, own gaps, brand not first. Pass file (project path), url (live page, fetched without JS) or text. Read-only." + PRO_NOTE,
+        inputSchema: {
+            project_root: projectRoot,
+            file: z.string().optional().describe("Page source in the project (.md, .mdx, .html, .astro, .tsx, .jsx, .vue, .svelte, llms.txt), relative to project_root"),
+            url: z.string().optional().describe("A live page URL (fetched as bots see it, without JavaScript)"),
+            text: z.string().optional().describe("The page copy as Markdown/plain text"),
+            page_type: z.enum(PAGE_TYPES_LINT).optional().describe("Default: situation when it matches a research situation, else other"),
+            situation_id: z.string().optional().describe("Research situation id the page is written for"),
+            lang,
+        },
+        annotations: { title: "Katman: lint content", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, withPro(ctx, "lint", wrap(ctx, (root, a) => runLint(root, { file: a.file, url: a.url, text: a.text, pageType: a.page_type, situationId: a.situation_id, lang: a.lang }))));
+    server.registerTool("katman_report", {
+        title: "Katman: report",
+        description: "Writes .katman/report.md, a shareable summary: research completeness, the latest audit's gate pass rates (Read / Quote / Fit), AI visibility rates with changes vs the previous comparable run, the competitors named instead and the cited domains (off-site targets), plan progress, the top 10 open issues and the next 7 days. Use after a measurement or at the end of a work session." + PRO_NOTE,
+        inputSchema: { project_root: projectRoot, lang },
+        annotations: { title: "Katman: report", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, withPro(ctx, "report", wrap(ctx, (root, a) => runReport(root, { lang: a.lang }))));
+    registerMethodPrompts(server);
+    registerMethodResources(server, ctx);
+}

package/dist/tools/method/lib/calls.js

@@ -0,0 +1,53 @@
+// Canonical tool calls the method module recommends as "next step". Kept in one place so argument names
+// stay in sync with the crawl and visibility modules.
+export const calls = {
+    start: (root, siteUrl) => ({ tool: "katman_start", args: { project_root: root, ...(siteUrl ? { site_url: siteUrl } : {}) } }),
+    researchTemplate: (root) => ({ tool: "katman_research", args: { project_root: root, mode: "template" } }),
+    researchShow: (root) => ({ tool: "katman_research", args: { project_root: root, mode: "show" } }),
+    researchUpdate: (root, data, extra = {}) => ({
+        tool: "katman_research",
+        args: { project_root: root, mode: "update", data, ...extra },
+    }),
+    generateQuestions: (root) => ({ tool: "katman_research", args: { project_root: root, mode: "update", generate_questions: true } }),
+    scan: (root) => ({ tool: "katman_scan_code", args: { project_root: root } }),
+    audit: (root, siteUrl) => ({ tool: "katman_audit_site", args: { project_root: root, site_url: siteUrl } }),
+    auditUrls: (root, urls) => ({ tool: "katman_audit_site", args: { project_root: root, urls } }),
+    visibilityDryRun: (root, extra = {}) => ({
+        tool: "katman_visibility_run",
+        args: { project_root: root, dry_run: true, ...extra },
+    }),
+    /** Without answer_text the tool returns the instructions and the questions to ask. */
+    manualCheck: (root, assistant = "chatgpt") => ({ tool: "katman_manual_check", args: { project_root: root, assistant } }),
+    plan: (root) => ({ tool: "katman_plan", args: { project_root: root } }),
+    prompt: (root, id, situationId) => ({
+        tool: "katman_prompt",
+        args: { project_root: root, id, ...(situationId ? { situation_id: situationId } : {}) },
+    }),
+    brief: (root, type, situationId) => ({
+        tool: "katman_page_brief",
+        args: { project_root: root, type, ...(situationId ? { situation_id: situationId } : {}) },
+    }),
+    generate: (root, artifact, options) => ({
+        tool: "katman_generate",
+        args: { project_root: root, artifact, ...(options ? { options } : {}) },
+    }),
+    lint: (root, args) => ({ tool: "katman_lint_content", args: { project_root: root, ...args } }),
+    indexnow: (root) => ({ tool: "katman_indexnow", args: { project_root: root, dry_run: true } }),
+    keywords: (seed) => ({ tool: "katman_keywords", args: { seed } }),
+    report: (root) => ({ tool: "katman_report", args: { project_root: root } }),
+    setupMonitoring: (root) => ({ tool: "katman_setup_monitoring", args: { project_root: root } }),
+};
+/** Inline form: `katman_audit_site` {"url":"…"} */
+export function fmtCall(c) {
+    return `\`${c.tool}\` \`${JSON.stringify(c.args)}\``;
+}
+/** Block form for the "Next step" section. */
+export function fmtCallBlock(c) {
+    return "```json\n" + JSON.stringify({ tool: c.tool, arguments: c.args }, null, 2) + "\n```";
+}
+/** Visibility panels (katman_visibility_run `models`), approximate cost per full question-set run. */
+export const PANEL_COSTS = { economy: "≈$2.4", full: "≈$4.6", probe: "≈$1.8" };
+export const PANEL_COST_TEXT = `default panel "economy" ${PANEL_COSTS.economy} per run; "full" ${PANEL_COSTS.full}; "probe" ${PANEL_COSTS.probe} — paid from the user's OpenRouter credits, shown as a dry-run estimate first`;
+export function hasOpenRouterKey() {
+    return !!(process.env.OPENROUTER_API_KEY || process.env.KATMAN_OPENROUTER_API_KEY);
+}