katman-mcp 0.1.0

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

@@ -0,0 +1,292 @@
+// Code generators for katman_generate: the browser AI-channel snippet (book ch. 15 human filter + channel rule)
+// and the server-side bot counter (per day, per bot, per path) for 5 platforms.
+import { CRAWLERS } from "../../../crawlers.js";
+import { AI_REFERRER_HOSTS, AI_UTM_MARKERS, SOCIAL_REFERRER_HOSTS } from "../data/measurement.js";
+export const BOT_PLATFORMS = ["cloudflare-worker", "nextjs-middleware", "express", "astro-middleware", "sveltekit-hooks"];
+/** Bots worth counting beyond Katman's crawler list (seen on the sample site). */
+const EXTRA_BOTS = [
+    ["YandexBot", "Yandex · search"],
+    ["DuckDuckBot", "DuckDuckGo · search"],
+];
+export function botTable() {
+    const rows = CRAWLERS.map((c) => [c.token, `${c.org} · ${c.purpose}`]);
+    for (const e of EXTRA_BOTS)
+        if (!rows.some((r) => r[0] === e[0]))
+            rows.push(e);
+    return rows;
+}
+export function analyticsChannelSnippet(target = "auto") {
+    const js = (xs) => JSON.stringify(xs);
+    return `/*! Katman AI channel + human filter (Katman book, ch. 15) — https://katman.pro
+ * channel: "ai" (assistant referrer OR utm_source such as chatgpt.com), "search", "social", "referral", "direct".
+ * human: the session scrolled, viewed more than 2 pages, converted (katmanChannel.convert("signup")), or came
+ * from an in-app browser (TikTok / Instagram). Bots that run JavaScript rarely do any of these.
+ * No cookies; sessionStorage only. Include it once on every public page:
+ *   <script src="/katman-channel.js" defer></script>
+ */
+(function () {
+  "use strict";
+  var TARGET = ${JSON.stringify(target)}; // auto | gtag | gtm | plausible | posthog | none
+  var AI_HOSTS = ${js(AI_REFERRER_HOSTS)};
+  var AI_UTM = ${js(AI_UTM_MARKERS)};
+  var SEARCH = [/(^|\\.)google\\.[a-z.]+$/, /(^|\\.)bing\\.com$/, /(^|\\.)yandex\\.[a-z.]+$/, /^search\\.brave\\.com$/, /(^|\\.)duckduckgo\\.com$/,
+    /(^|\\.)ecosia\\.org$/, /(^|\\.)search\\.yahoo\\.com$/, /(^|\\.)baidu\\.com$/, /(^|\\.)naver\\.com$/, /(^|\\.)seznam\\.cz$/, /(^|\\.)yep\\.com$/];
+  var SOCIAL = ${js(SOCIAL_REFERRER_HOSTS)};
+  var IN_APP = /Instagram|FBAN|FBAV|TikTok|Bytedance/i;
+  var KEY = "katman_session_v1";
+
+  function hostOf(u) {
+    try { return new URL(u).hostname.replace(/^www\\./, "").toLowerCase(); } catch (e) { return ""; }
+  }
+  function matchHost(h, list) {
+    for (var i = 0; i < list.length; i++) {
+      var d = list[i];
+      if (h === d || h.slice(-(d.length + 1)) === "." + d) return d;
+    }
+    return "";
+  }
+  function classify(referrer, utmSource) {
+    var utm = (utmSource || "").toLowerCase();
+    for (var i = 0; i < AI_UTM.length; i++) if (utm.indexOf(AI_UTM[i]) !== -1) return { channel: "ai", source: utm };
+    var h = hostOf(referrer);
+    var self = location.hostname.replace(/^www\\./, "").toLowerCase();
+    if (!h || h === self) return { channel: "direct", source: utm };
+    var ai = matchHost(h, AI_HOSTS);
+    if (ai) return { channel: "ai", source: ai };
+    for (var j = 0; j < SEARCH.length; j++) if (SEARCH[j].test(h)) return { channel: "search", source: h };
+    var social = matchHost(h, SOCIAL);
+    if (social) return { channel: "social", source: social };
+    return { channel: "referral", source: h };
+  }
+  function load() {
+    try { var raw = sessionStorage.getItem(KEY); return raw ? JSON.parse(raw) : null; } catch (e) { return null; }
+  }
+  function save() {
+    try { sessionStorage.setItem(KEY, JSON.stringify(s)); } catch (e) { /* private mode */ }
+  }
+
+  var s = load();
+  var isNew = !s;
+  if (!s) {
+    var c = classify(document.referrer, new URLSearchParams(location.search).get("utm_source"));
+    s = { channel: c.channel, source: c.source, landing: location.pathname, pages: 0, scrolled: false, conversion: "", inApp: IN_APP.test(navigator.userAgent), human: false };
+  }
+  s.pages += 1;
+
+  function props() {
+    return { katman_channel: s.channel, katman_source: s.source, katman_landing: s.landing, katman_human: s.human };
+  }
+  function push(event) {
+    var w = window, p = props();
+    try {
+      if (TARGET === "gtm") w.dataLayer = w.dataLayer || [];
+      if ((TARGET === "auto" || TARGET === "gtm") && Array.isArray(w.dataLayer)) w.dataLayer.push(Object.assign({ event: event }, p));
+      if ((TARGET === "auto" || TARGET === "gtag") && typeof w.gtag === "function") w.gtag("event", event, p);
+      if ((TARGET === "auto" || TARGET === "plausible") && typeof w.plausible === "function") w.plausible(event, { props: p });
+      if ((TARGET === "auto" || TARGET === "posthog") && w.posthog && typeof w.posthog.capture === "function") {
+        w.posthog.register({ katman_channel: s.channel, katman_source: s.source });
+        w.posthog.capture(event, p);
+      }
+    } catch (e) { /* never break the page */ }
+  }
+  function whenReady(fn) {
+    if (document.readyState === "complete") setTimeout(fn, 0);
+    else window.addEventListener("load", function () { setTimeout(fn, 0); });
+  }
+  function evaluate() {
+    var human = s.scrolled || s.pages > 2 || !!s.conversion || s.inApp;
+    if (human && !s.human) {
+      s.human = true;
+      whenReady(function () { push("katman_human"); });
+    }
+    api.channel = s.channel; api.source = s.source; api.landing = s.landing; api.pages = s.pages; api.human = s.human;
+    save();
+  }
+  var api = {
+    channel: s.channel, source: s.source, landing: s.landing, pages: s.pages, human: s.human,
+    /** Call on a real conversion (quiz finished, sign-up, payment): marks the session human. */
+    convert: function (name) { s.conversion = String(name || "conversion"); evaluate(); },
+    classify: classify
+  };
+  window.katmanChannel = api;
+  if (isNew) whenReady(function () { push("katman_session"); });
+  evaluate();
+  if (!s.scrolled) {
+    var onScroll = function () {
+      if ((window.scrollY || document.documentElement.scrollTop) > 0) {
+        s.scrolled = true;
+        window.removeEventListener("scroll", onScroll);
+        evaluate();
+      }
+    };
+    window.addEventListener("scroll", onScroll, { passive: true });
+  }
+})();
+`;
+}
+export function botBlock(ts) {
+    const rows = botTable()
+        .map(([tok, who]) => `  [${JSON.stringify(tok)}, ${JSON.stringify(who)}],`)
+        .join("\n");
+    return `// Katman bot counter (Katman book, ch. 15): bots don't run browser analytics, so count them on the server.
+// Counts requests per day, per bot, per path. Bot list generated from Katman's crawler list.
+const KATMAN_BOTS${ts ? ": [string, string][]" : ""} = [
+${rows}
+];
+
+/** The bot's token (e.g. "OAI-SearchBot") or null for anything else. */
+export function katmanBot(userAgent${ts ? ": string | null | undefined" : ""})${ts ? ": string | null" : ""} {
+  if (!userAgent) return null;
+  const ua = userAgent.toLowerCase();
+  for (const [token] of KATMAN_BOTS) if (ua.includes(token.toLowerCase())) return token;
+  return null;
+}
+`;
+}
+export function botCounterSnippet(platform) {
+    const common = botBlock(true);
+    switch (platform) {
+        case "cloudflare-worker":
+            return {
+                fileName: "bot-counter.cloudflare-worker.ts",
+                placeAt: "your Worker entry (or a pass-through Worker on your site's route)",
+                notes: [
+                    "Add to wrangler.toml: [[analytics_engine_datasets]] binding = \"KATMAN_BOTS\", dataset = \"katman_bots\" (Workers Analytics Engine; free tier included). Types: @cloudflare/workers-types.",
+                    "Don't count into KV: its write limits are too low for per-request counters. D1 works (INSERT … ON CONFLICT(day, bot, path) DO UPDATE SET hits = hits + 1).",
+                    "Requests blocked by the WAF/bot settings never reach the Worker: if a bot never shows up here, check Security → Events (book ch. 6).",
+                ],
+                code: `${common}
+export interface Env {
+  /** Workers Analytics Engine dataset (wrangler.toml: [[analytics_engine_datasets]] binding = "KATMAN_BOTS", dataset = "katman_bots"). */
+  KATMAN_BOTS?: AnalyticsEngineDataset;
+}
+
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const bot = katmanBot(request.headers.get("user-agent"));
+    // Pass through to your origin — or call your own handler here if this Worker serves the site.
+    const response = await fetch(request);
+    if (bot) {
+      const url = new URL(request.url);
+      // Storage adapter: Analytics Engine (day comes from the event timestamp).
+      env.KATMAN_BOTS?.writeDataPoint({ blobs: [bot, url.pathname, String(response.status)], doubles: [1], indexes: [bot] });
+    }
+    void ctx;
+    return response;
+  },
+};
+
+// Read it (Cloudflare SQL API for Analytics Engine):
+//   SELECT toStartOfInterval(timestamp, INTERVAL '1' DAY) AS day, blob1 AS bot, blob2 AS path,
+//          SUM(_sample_interval) AS hits
+//   FROM katman_bots WHERE timestamp > NOW() - INTERVAL '7' DAY
+//   GROUP BY day, bot, path ORDER BY day DESC, hits DESC
+`,
+            };
+        case "nextjs-middleware":
+            return {
+                fileName: "bot-counter.nextjs-middleware.ts",
+                placeAt: "middleware.ts at the project root (or src/middleware.ts); on Next.js 16+ the file is proxy.ts and the export is `proxy`",
+                notes: [
+                    "If the project already has a middleware/proxy file, merge the katmanBot() call into it instead of replacing it.",
+                    "The default storage adapter logs one JSON line per bot hit (visible in your host's logs / log drain). Swap record() for Upstash Redis HINCRBY or a database upsert to keep daily counts.",
+                ],
+                code: `${common}
+import { NextResponse, type NextFetchEvent, type NextRequest } from "next/server";
+
+export function middleware(request: NextRequest, event: NextFetchEvent) {
+  const bot = katmanBot(request.headers.get("user-agent"));
+  if (bot) event.waitUntil(record({ day: new Date().toISOString().slice(0, 10), bot, path: request.nextUrl.pathname }));
+  return NextResponse.next();
+}
+
+export const config = { matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"] };
+
+/** Storage adapter: replace with your store (Upstash Redis HINCRBY katman:bots:<day> "<bot> <path>" 1, a DB upsert, …). */
+async function record(hit: { day: string; bot: string; path: string }): Promise<void> {
+  console.log(JSON.stringify({ katman_bot: hit }));
+}
+`,
+            };
+        case "express":
+            return {
+                fileName: "bot-counter.express.ts",
+                placeAt: "your Express server: app.use(katmanBotCounter) before the routes",
+                notes: [
+                    "Counts are kept in memory and appended to katman-bots.tsv every minute (day, bot, path, hits); sum rows with the same day/bot/path when you read it. Swap flush() for your database.",
+                ],
+                code: `${common}
+import type { NextFunction, Request, Response } from "express";
+import { appendFile } from "node:fs/promises";
+
+const counts = new Map<string, number>();
+
+export function katmanBotCounter(req: Request, _res: Response, next: NextFunction): void {
+  const bot = katmanBot(req.get("user-agent"));
+  if (bot) {
+    const key = \`\${new Date().toISOString().slice(0, 10)}\\t\${bot}\\t\${req.path}\`;
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  next();
+}
+
+/** Storage adapter: a TSV file (day, bot, path, hits). Replace with a database upsert if you have one. */
+async function flush(): Promise<void> {
+  if (!counts.size) return;
+  const lines = [...counts].map(([k, n]) => \`\${k}\\t\${n}\\n\`).join("");
+  counts.clear();
+  await appendFile("katman-bots.tsv", lines).catch(() => undefined);
+}
+setInterval(() => void flush(), 60_000).unref();
+`,
+            };
+        case "astro-middleware":
+            return {
+                fileName: "bot-counter.astro-middleware.ts",
+                placeAt: "src/middleware.ts",
+                notes: [
+                    "Astro middleware runs only for on-demand (SSR) routes. Prerendered pages are served as static files and never reach it: for a static Astro site count bots at the edge (platform cloudflare-worker) or in your host's logs.",
+                    "Swap record() for your store; the default logs one JSON line per bot hit.",
+                ],
+                code: `${common}
+import { defineMiddleware } from "astro:middleware";
+
+export const onRequest = defineMiddleware(async (context, next) => {
+  const bot = katmanBot(context.request.headers.get("user-agent"));
+  const response = await next();
+  if (bot) await record({ day: new Date().toISOString().slice(0, 10), bot, path: context.url.pathname, status: response.status });
+  return response;
+});
+
+/** Storage adapter: replace with your store (a DB upsert, Redis HINCRBY, …). */
+async function record(hit: { day: string; bot: string; path: string; status: number }): Promise<void> {
+  console.log(JSON.stringify({ katman_bot: hit }));
+}
+`,
+            };
+        case "sveltekit-hooks":
+            return {
+                fileName: "bot-counter.sveltekit-hooks.ts",
+                placeAt: "src/hooks.server.ts (merge with an existing handle using sequence())",
+                notes: [
+                    "Prerendered pages don't pass through hooks at request time: count those at the edge (platform cloudflare-worker) or in your host's logs.",
+                    "Swap record() for your store; the default logs one JSON line per bot hit.",
+                ],
+                code: `${common}
+import type { Handle } from "@sveltejs/kit";
+
+export const handle: Handle = async ({ event, resolve }) => {
+  const bot = katmanBot(event.request.headers.get("user-agent"));
+  const response = await resolve(event);
+  if (bot) await record({ day: new Date().toISOString().slice(0, 10), bot, path: event.url.pathname, status: response.status });
+  return response;
+};
+
+/** Storage adapter: replace with your store (a DB upsert, Redis HINCRBY, …). */
+async function record(hit: { day: string; bot: string; path: string; status: number }): Promise<void> {
+  console.log(JSON.stringify({ katman_bot: hit }));
+}
+`,
+            };
+    }
+}

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

@@ -0,0 +1,277 @@
+import { logEvent, saveConfig, saveResearch } from "../../../state.js";
+import { domainOf, mdTable, normalizeSiteUrl } from "../../../util.js";
+import { PANEL_COST_TEXT, calls, fmtCallBlock } from "../lib/calls.js";
+import { keySituationQuestionIds } from "./questions.js";
+import { fwLabel } from "../lib/framework.js";
+import { hasKatmanDir, katmanMtime, loadConfigSafe, loadLatestAudit, loadResearchSafe, loadRuns, loadScan, runDate } from "../lib/state.js";
+import { addDays, isoDay } from "../lib/text.js";
+import { methodSummaryMd } from "../data/render.js";
+import { API_PROXY_NOTE } from "../data/measurement.js";
+import { t } from "../lib/l10n.js";
+import { researchCompleteness } from "./research.js";
+import { loadPlanState, openTasks, taskCall } from "./plan.js";
+import { siteUrlOf } from "./prompt.js";
+const REMEASURE_DAYS = 14;
+export function firstRunText(root) {
+    return [
+        "**First run in this project. What happens next:**",
+        `1. Katman keeps its notes in \`${root}/.katman/\` (safe to commit, never secrets). It writes nowhere else unless you call katman_generate or katman_setup_monitoring with write: true, and it never overwrites without overwrite: true.`,
+        "2. It reads your code (skipping node_modules, .git and build output; never .env*, keys or secrets) and, when you run the audit tools, your own live site.",
+        "3. Network only when a tool needs it: your site, openrouter.ai with YOUR key after a cost estimate (dry run first), api.indexnow.org on request, and katman.pro only to check KATMAN_KEY (at most once a day, only when it is set) or when you call katman_sync. No telemetry.",
+        "4. The order: research (who you are, your customers' own sentences) → plan → build with prompts P0–P14 → verify, then re-measure every 14 days.",
+        "5. It never invents facts: unknowns stay [FILL] and you'll be asked.",
+    ].join("\n");
+}
+export async function runStart(root, opts) {
+    const now = opts.now ?? new Date();
+    const firstRun = !hasKatmanDir(root);
+    const notes = [];
+    let config = await loadConfigSafe(root);
+    let research = await loadResearchSafe(root);
+    const lang = opts.lang ?? config.lang ?? "en";
+    if (opts.siteUrl) {
+        let url;
+        try {
+            url = normalizeSiteUrl(opts.siteUrl);
+        }
+        catch {
+            return { text: `"${opts.siteUrl}" isn't a valid site URL. Pass the live address, e.g. https://example.com.`, isError: true };
+        }
+        config = { ...config, siteUrl: url };
+        await saveConfig(root, config);
+        if (research) {
+            research.site = { ...research.site, url, domain: domainOf(url) };
+            await saveResearch(root, research);
+        }
+        await logEvent(root, `katman_start: site URL set to ${url}`);
+        notes.push(`Saved the site URL ${url} to .katman/config.json${research ? " and research.json" : ""}.`);
+    }
+    const [scan, loaded, runs, planState] = await Promise.all([loadScan(root), loadLatestAudit(root), loadRuns(root), loadPlanState(root)]);
+    const audit = loaded?.audit;
+    const siteUrl = siteUrlOf(research, config);
+    const completeness = researchCompleteness(research);
+    const plan = planState.plan;
+    const planMtime = await katmanMtime(root, "plan.md");
+    const open = plan ? openTasks(plan) : [];
+    const doneCount = plan ? plan.tasks.length - open.length : 0;
+    const lastRun = runs.length ? runs[runs.length - 1] : undefined;
+    const lastRunDate = lastRun ? runDate(lastRun) : undefined;
+    const dueDate = lastRunDate ? addDays(lastRunDate, REMEASURE_DAYS) : undefined;
+    const remeasureDue = !!dueDate && dueDate.getTime() <= now.getTime();
+    const auditDate = audit?.ts ? new Date(audit.ts) : undefined;
+    const auditStale = !!(auditDate && planMtime && doneCount > 0 && auditDate.getTime() < planMtime.getTime());
+    // ------------------------------------------------------------ status table
+    const steps = [];
+    steps.push({
+        step: "1 Research",
+        state: research ? `${completeness.percent}%` : "not started",
+        detail: research ? (completeness.gaps.length ? `missing: ${completeness.gaps.slice(0, 4).join("; ")}` : "complete") : "no .katman/research.json",
+    });
+    steps.push({
+        step: "2 Plan",
+        state: [`scan ${scan ? "yes" : "no"}`, `audit ${audit ? "yes" : "no"}`, `plan ${plan ? "yes" : "no"}`].join(" · "),
+        detail: [
+            scan ? `${fwLabel(scan)}` : "no scan",
+            audit ? `audit ${isoDay(audit.ts)} (${audit.pages.length} pages)` : siteUrl ? "no audit yet" : "no site URL → no audit",
+            plan ? `plan ${isoDay(plan.generatedAt)}` : "",
+        ].filter(Boolean).join(" · "),
+    });
+    steps.push({
+        step: "3 Build",
+        state: plan ? `${doneCount}/${plan.tasks.length} tasks (${plan.tasks.length ? Math.round((doneCount / plan.tasks.length) * 100) : 0}%)` : "–",
+        detail: plan ? (open[0] ? `next: ${open[0].title}` : "all tasks done") : "no plan yet",
+    });
+    steps.push({
+        step: "4 Verify",
+        state: audit ? `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}` : "–",
+        detail: audit ? (auditStale ? "plan changed after the last audit → re-verify" : `last audit ${isoDay(audit.ts)}`) : "no audit yet",
+    });
+    steps.push({
+        step: "Measure",
+        state: runs.length ? `${runs.length} run(s), last ${isoDay(lastRunDate ?? lastRun.ts)}` : "no runs",
+        detail: runs.length
+            ? `mentioned ${Math.round(lastRun.summary.mentionRate * 100)}% · recommended first ${Math.round(lastRun.summary.recommendedFirstRate * 100)}% · cited ${Math.round(lastRun.summary.citationRate * 100)}% · re-run ${remeasureDue ? "DUE now" : `due ${isoDay(dueDate)}`}`
+            : "baseline needed (question set × assistants)",
+    });
+    // ------------------------------------------------------------ next step
+    const also = [];
+    let next;
+    const orKey = opts.hasOpenRouterKey;
+    const measureCall = orKey ? calls.visibilityDryRun(root) : calls.manualCheck(root);
+    if (!research) {
+        next = {
+            call: calls.researchTemplate(root),
+            title: "Create the research file (step 1)",
+            why: "Research comes first: the customer's own sentences decide which pages get built (book ch. 7).",
+            then: [
+                "Fill it from the codebase: README, landing-page copy, the pricing page, legal pages/footer (brand name, category, pricing, company, a first draft of the one sentence).",
+                "Ask the user for 10–12 customer sentences (what customers type into ChatGPT, no brand name), what the brand gets confused with, and the competitors assistants name today.",
+                "Save it with katman_research mode \"update\"; never invent numbers, reviews or competitor facts.",
+            ],
+        };
+    }
+    else if (completeness.blocking.length) {
+        const onlyQuestions = completeness.blocking.length === 1 && completeness.blocking[0] === "question set";
+        next = onlyQuestions
+            ? {
+                call: calls.generateQuestions(root),
+                title: "Build the question set (12 unbranded + 2 diagnostic)",
+                why: "Measurement and the plan need a fixed question set (book ch. 15).",
+                then: ["Show the questions to the user once; after the first run keep them fixed."],
+            }
+            : {
+                call: calls.researchUpdate(root, gapSkeleton(completeness.blocking)),
+                title: `Finish research: ${completeness.blocking.join(", ")}`,
+                why: "The plan and every prompt are filled from research; missing parts would become [FILL].",
+                then: [
+                    "Take what you can from the codebase; ask the user for the customer sentences and anything you'd otherwise have to guess.",
+                    research.situations.length >= 3 ? "Add \"generate_questions\": true in the same call to build the question set." : "Once there are ≥3 situations, add \"generate_questions\": true.",
+                ],
+            };
+    }
+    else if (!scan) {
+        next = {
+            call: calls.scan(root),
+            title: "Scan the codebase",
+            why: "The scan finds the framework, how pages render (text only in JavaScript is trap 1), the routes and head tags — it decides P2 and where every file goes.",
+            then: ["Then call katman_start again."],
+        };
+    }
+    else if (!audit && siteUrl) {
+        next = {
+            call: calls.audit(root, siteUrl),
+            title: "Audit the live site the way AI crawlers see it",
+            why: "What bots actually get: robots.txt, CDN/firewall blocks (403), text with JavaScript off, soft 404s, canonicals, sitemap.",
+            then: ["Report only (P1); don't fix anything yet. Then call katman_start again."],
+        };
+    }
+    else if (!runs.length) {
+        next = {
+            call: measureCall,
+            title: "Take the baseline measurement",
+            why: "Whether assistants name, recommend and cite the site today — the before picture to compare against in 14 days.",
+            then: orKey
+                ? [`Show the user the dry-run estimate and wait for their OK before running for real (${PANEL_COST_TEXT}).`, t(API_PROXY_NOTE, lang)]
+                : ["No OpenRouter key is set (OPENROUTER_API_KEY), so use the manual check (no API cost): the user asks the questions in the consumer apps, logged out, web search on, and pastes the answers.", "To measure through APIs later, the user sets OPENROUTER_API_KEY in the MCP config."],
+        };
+        if (!siteUrl)
+            also.push(domainHint(scan?.domains));
+    }
+    else if (!plan) {
+        next = {
+            call: calls.plan(root),
+            title: "Build the plan",
+            why: "Turns research + scan + audit + the baseline into the page plan and a 30-day task list, each task with an acceptance criterion.",
+            then: ["Show the plan to the user and get approval before changing any code (P0)."],
+        };
+    }
+    else if (open.length) {
+        const task = open[0];
+        const call = taskCall(root, task, siteUrl);
+        next = {
+            ...(call ? { call } : {}),
+            title: `Next task: ${task.title}`,
+            why: `Week ${task.week} of the 30-day plan. Accept: ${task.accept}`,
+            then: [call ? "Do the task, run its check, and tick it in .katman/plan.md only when the check passes." : "This task is done by hand; tick it in .katman/plan.md when it's done.", `Verify with: ${task.verifiedBy}`],
+        };
+        if (auditStale && siteUrl)
+            also.push(`Pages changed since the last audit: re-verify with katman_audit_site ${JSON.stringify({ urls: [`${siteUrl}/`] })} (quick mode) or a full audit.`);
+    }
+    else {
+        next = {
+            call: siteUrl ? calls.audit(root, siteUrl) : calls.scan(root),
+            title: "Verify, notify, re-measure",
+            why: "Every task is ticked: prove it on the live site, tell the search engines about changed URLs, and re-measure on schedule.",
+            then: [
+                "katman_indexnow (dry run first) for new or changed URLs only; then Search Console, Bing URL Submission and Brave submit-url by hand.",
+                `Re-measure ${dueDate ? `on ${isoDay(dueDate)}` : "14 days after the last run"} with the same questions, models and temperature.`,
+                "katman_report for a shareable summary.",
+            ],
+        };
+    }
+    const keyIds = keySituationQuestionIds(research);
+    if (remeasureDue && runs.length) {
+        also.push(`The re-measurement is due (last run ${isoDay(lastRunDate)}), same questions as before: ${orKey
+            ? `katman_visibility_run ${JSON.stringify({ dry_run: true })} for the full set, plus ${JSON.stringify({ dry_run: true, question_ids: keyIds, samples: 3 })} to read how often you're named on the key situation questions (${PANEL_COST_TEXT})`
+            : "katman_manual_check (the key situation questions, in the real apps)"}.`);
+    }
+    if (!siteUrl && scan && next.call?.tool !== "katman_visibility_run" && next.call?.tool !== "katman_manual_check" && !also.some((a) => a.includes("site_url")))
+        also.push(domainHint(scan.domains));
+    if (runs.length && orKey)
+        also.push(`Confirm the key questions in the real apps too: katman_manual_check (${t(API_PROXY_NOTE, lang).split(":")[0]}).`);
+    if (plan) {
+        const planAt = new Date(plan.generatedAt).getTime();
+        const newer = [
+            research?.updatedAt && new Date(research.updatedAt).getTime() > planAt ? "research" : "",
+            scan?.ts && new Date(scan.ts).getTime() > planAt ? "the scan" : "",
+            audit?.ts && new Date(audit.ts).getTime() > planAt ? "the audit" : "",
+        ].filter(Boolean);
+        if (newer.length && Number.isFinite(planAt))
+            also.push(`${newer.join(", ")} changed after the plan was built: run katman_plan again to fold in new situations and findings (your ticks are kept).`);
+    }
+    if (research && completeness.percent < 100 && !completeness.blocking.length)
+        also.push(`Research is ${completeness.percent}%: close the gaps this week (${completeness.gaps.slice(0, 3).join("; ")}).`);
+    // ------------------------------------------------------------ output
+    const parts = [];
+    if (opts.warning)
+        parts.push(`**Warning:** ${opts.warning}`);
+    parts.push(`# Katman — ${research?.brand.name && !/\[FILL/i.test(research.brand.name) ? research.brand.name : "project"} (${root})`);
+    if (firstRun)
+        parts.push(firstRunText(root));
+    if (opts.license?.line)
+        parts.push(opts.license.line);
+    if (notes.length)
+        parts.push(notes.join("\n"));
+    // Full method overview only while research hasn't started; afterwards one line keeps the agent's context lean.
+    if (firstRun || !research)
+        parts.push(methodSummaryMd(lang));
+    else
+        parts.push(lang === "tr"
+            ? "Yöntem: 3 kapı (Okunmak · Alıntılanmak · Soruya uymak) · 4 adım (Araştır → Planla → Yaptır → Doğrula) · tamamı: kaynak `katman://method`."
+            : "Method: 3 gates (Read · Quote · Fit) · 4 steps (Research → Plan → Build → Verify) · full overview: resource `katman://method`.");
+    parts.push(`## Status\n${mdTable(["Step", "State", "Detail"], steps.map((s) => [s.step, s.state, s.detail]))}`);
+    parts.push(`## Next step: ${next.title}\n${next.call ? fmtCallBlock(next.call) : "_(by hand)_"}\n**Why:** ${next.why}${next.then.length ? `\n\n${next.then.map((x) => `- ${x}`).join("\n")}` : ""}`);
+    const proNote = next.call ? opts.license?.notice?.(next.call.tool) : undefined;
+    if (proNote)
+        parts.push(proNote);
+    if (also.length)
+        parts.push(`## Also\n${also.map((x) => `- ${x}`).join("\n")}`);
+    parts.push("Call katman_start again after each step. Never invent facts; write [FILL] and ask the user.");
+    return {
+        text: parts.join("\n\n"),
+        structured: {
+            root,
+            firstRun,
+            siteUrl: siteUrl ?? null,
+            research: { exists: !!research, percent: completeness.percent, gaps: completeness.gaps, blocking: completeness.blocking },
+            scan: scan ? { framework: scan.framework.name, rendering: scan.rendering.verdict, ts: scan.ts } : null,
+            audit: audit ? { ts: audit.ts, gates: audit.gates } : null,
+            plan: plan ? { tasks: plan.tasks.length, done: doneCount, nextTask: open[0]?.id ?? null } : null,
+            measure: { runs: runs.length, lastRun: lastRunDate ? lastRunDate.toISOString() : null, due: dueDate ? dueDate.toISOString() : null, dueNow: remeasureDue, openRouterKey: orKey },
+            steps,
+            next: { tool: next.call?.tool ?? null, args: next.call?.args ?? null, title: next.title, why: next.why, ...(opts.license ? { needsPro: !!proNote } : {}) },
+            ...(opts.license?.structured ? { license: opts.license.structured } : {}),
+        },
+    };
+}
+function domainHint(domains) {
+    return domains?.length
+        ? `No site URL yet. The hosting config names ${domains.map((d) => `https://${d}`).join(", ")}: confirm the live address with the user, then call katman_start with site_url (and katman_audit_site).`
+        : "No site URL yet: ask the user for the live address and call katman_start with site_url, then katman_audit_site.";
+}
+/** A data skeleton for exactly the blocking gaps (the agent fills it). */
+function gapSkeleton(blocking) {
+    const data = {};
+    const brand = {};
+    if (blocking.includes("brand name"))
+        brand.name = "<one distinctive name>";
+    if (blocking.includes("category"))
+        brand.category = "<category>";
+    if (blocking.includes("one sentence (4 parts)"))
+        brand.oneLiner = { brings: "<what the customer brings>", weDo: "<what we do>", gets: "<what they get>", fear: "<which fear is unnecessary>" };
+    if (Object.keys(brand).length)
+        data.brand = brand;
+    if (blocking.includes("at least 3 situations"))
+        data.situations = [{ sentence: "<the customer's own sentence, no brand name>" }];
+    return data;
+}