katman-mcp 0.1.0

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

@@ -0,0 +1,504 @@
+// katman_generate: artifacts built from research (the single source of truth). write:true writes static
+// artifacts into the project's static dir (never overwriting unless overwrite:true); code snippets and JSON-LD
+// go to .katman/generated/ because they must be merged into the codebase by hand.
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import { existsSync, promises as fs } from "node:fs";
+import { ROBOTS_TOKENS } from "../../../crawlers.js";
+import { logEvent, saveConfig, writeText } from "../../../state.js";
+import { domainOf } from "../../../util.js";
+import { fwKind, suggestBotPlatform } from "../lib/framework.js";
+import { appPrefixes, findPage, knownPublicPaths, noindexRoutes } from "../lib/routes.js";
+import { insideRoot, joinRel, loadConfigSafe, loadLatestAudit, loadResearchSafe, loadScan, staticDirFor } from "../lib/state.js";
+import { FILL, brandSentence, codeBlock, firstSentence, hasNotX, hasPlaceholder, isFilled, normPath } from "../lib/text.js";
+import { analyticsChannelSnippet, botCounterSnippet } from "./snippets.js";
+import { siteUrlOf, situationUrl } from "./prompt.js";
+export const ARTIFACTS = [
+    "robots.txt", "llms.txt", "organization-jsonld", "website-jsonld", "software-jsonld", "faq-jsonld", "breadcrumb-jsonld",
+    "analytics-channel-snippet", "bot-counter-snippet", "indexnow-key",
+];
+const GEN_DIR = "generated";
+function jsonLd(obj) {
+    return JSON.stringify(obj, null, 2);
+}
+function scriptTag(json) {
+    return `<script type="application/ld+json">\n${json}\n</script>`;
+}
+function abs(siteUrl, p) {
+    if (/^https?:\/\//i.test(p))
+        return p;
+    return `${siteUrl ?? `https://${FILL}`}${p.startsWith("/") ? "" : "/"}${p}`;
+}
+/** Prices in a free-text pricing line: "$9/month", "€12", "99 TL". */
+export function parsePrices(text) {
+    const out = [];
+    const sym = { $: "USD", "€": "EUR", "£": "GBP", "₺": "TRY" };
+    const codes = "USD|EUR|GBP|TRY|TL|CAD|AUD|CHF|JPY|INR|BRL";
+    const re = new RegExp(`([$€£₺])\\s?(\\d+(?:[.,]\\d{1,2})?)|(\\d+(?:[.,]\\d{1,2})?)\\s?([$€£₺]|${codes})\\b|\\b(${codes})\\s?(\\d+(?:[.,]\\d{1,2})?)`, "gi");
+    for (const m of text.matchAll(re)) {
+        const [, s1, n1, n2, s2, c3, n3] = m;
+        const n = n1 ?? n2 ?? n3;
+        const cur = s1 ? sym[s1] : s2 ? sym[s2] ?? s2.toUpperCase() : c3?.toUpperCase();
+        if (!n || !cur)
+            continue;
+        out.push({ price: Number(n.replace(",", ".")), currency: cur === "TL" ? "TRY" : cur });
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// robots.txt (appendix A)
+function sitemapUrl(ctx, o, siteUrl) {
+    if (o.sitemap_url)
+        return o.sitemap_url;
+    const fromAudit = ctx.audit?.site.robots.sitemaps.find((u) => /^https?:\/\//.test(u));
+    if (fromAudit)
+        return fromAudit;
+    const sm = ctx.scan?.files.sitemap;
+    if (sm?.exists && sm.path) {
+        const base = path.basename(sm.path);
+        if (/\.xml$/i.test(base))
+            return abs(siteUrl, `/${base}`);
+        if (fwKind(ctx.scan) === "astro")
+            return abs(siteUrl, "/sitemap-index.xml");
+    }
+    return abs(siteUrl, "/sitemap.xml");
+}
+export function genRobots(ctx, o) {
+    const siteUrl = siteUrlOf(ctx.research, ctx.config);
+    const ap = appPrefixes(ctx.scan, o.app_paths ?? []);
+    const training = o.training ?? "allow";
+    const blockTraining = training === "block";
+    const trainingOnly = new Set(["GPTBot", "ClaudeBot", "CCBot", "Bytespider", "Applebot-Extended", "meta-externalagent"]);
+    const rules = ["Allow: /"];
+    for (const p of ap.prefixes) {
+        if (p.startsWith("/*/"))
+            rules.push(`Disallow: ${p}/`);
+        else
+            rules.push(`Disallow: ${p}$`, `Disallow: ${p}/`);
+    }
+    const domain = siteUrl ? domainOf(siteUrl) : FILL;
+    const lines = [
+        `# robots.txt for ${domain} — generated by Katman (katman_generate) from .katman/research.json and scan.json.`,
+        blockTraining ? "# Open to search engines and AI assistants; AI training crawlers are not allowed." : "# Open to search engines, AI assistants and crawlers.",
+        `# Content signals: search=yes, ai-input=yes, ai-train=${blockTraining ? "no" : "yes"}`,
+        "# (Written as a comment: as a rule line, Lighthouse reports \"robots.txt is not valid\".)",
+        "# A bot that has its own group ignores the * group, so every group repeats the same rules.",
+        "# Login, sign-up and checkout pages aren't closed here: they carry <meta name=\"robots\" content=\"noindex,follow\"> instead.",
+        "",
+        "User-agent: *",
+        ...rules,
+        "",
+    ];
+    const tokens = [...ROBOTS_TOKENS, ...(blockTraining ? ["CCBot", "Bytespider"] : [])];
+    for (const tok of tokens) {
+        lines.push(`User-agent: ${tok}`);
+        if (blockTraining && trainingOnly.has(tok))
+            lines.push("Disallow: /");
+        else
+            lines.push(...rules);
+        lines.push("");
+    }
+    lines.push(`Sitemap: ${sitemapUrl(ctx, o, siteUrl)}`);
+    const llmsKnown = !!(ctx.scan?.files.llms.exists || ctx.audit?.site.llmsTxt.exists);
+    lines.push(`# For AI assistants: ${abs(siteUrl, "/llms.txt")}`);
+    const notes = [];
+    const missing = [];
+    if (!siteUrl)
+        missing.push("site URL (katman_start with site_url) for the Sitemap line");
+    if (ap.defaulted)
+        notes.push("No scan yet, so the book's default app paths are closed (/app, /admin, /api, /dashboard). Run katman_scan_code, or pass options.app_paths.");
+    if (!ap.prefixes.length)
+        notes.push("The scan found no app or API routes, so only the site-wide Allow is written. Pass options.app_paths if the app lives under a path.");
+    if (ap.conflicts.length)
+        notes.push(`Not closed because public pages live under them: ${ap.conflicts.join(", ")} — close the specific app paths by hand (never a bare prefix).`);
+    const noindex = noindexRoutes(ctx.scan, ap.prefixes);
+    if (noindex.length)
+        notes.push(`Give these routes <meta name="robots" content="noindex,follow"> (and keep them out of the sitemap) instead of closing them here: ${noindex.join(", ")}.`);
+    notes.push("Each app path is closed twice (`/app$` and `/app/`): `/app/` alone leaves `/app` open, and a bare `/app` would also close `/apple`.");
+    if (blockTraining)
+        notes.push("Training bots are blocked by name; Google-Extended stays allowed because blocking it also removes you from Gemini's grounded answers (not from Search). Make the CDN say the same thing (ch. 6).");
+    if (!llmsKnown)
+        notes.push("The last comment points at /llms.txt: create it with katman_generate {\"artifact\":\"llms.txt\"} or remove the line.");
+    notes.push("robots.txt is a request; the CDN/firewall decides at the door. After deploying, katman_audit_site checks that every AI bot gets 200.");
+    let conflict;
+    if (ctx.scan?.files.robots.generated && ctx.scan.files.robots.path) {
+        conflict = `robots.txt is generated by ${ctx.scan.files.robots.path}; port these rules there instead of adding a static file (both would conflict).`;
+    }
+    return {
+        artifact: "robots.txt",
+        content: lines.join("\n") + "\n",
+        target: joinRel(ctx.staticDir, "robots.txt"),
+        targetKind: "static",
+        fence: "text",
+        notes,
+        missing,
+        ...(conflict ? { conflict } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// llms.txt (appendix B)
+export function genLlms(ctx) {
+    const r = ctx.research;
+    const siteUrl = siteUrlOf(r, ctx.config);
+    const tr = (r?.site.languages[0] ?? "en").toLowerCase().startsWith("tr");
+    const L = (en, trs) => (tr ? trs : en);
+    const missing = [];
+    const brand = isFilled(r?.brand.name) ? r.brand.name.trim() : (missing.push("brand.name"), FILL);
+    const sentence = brandSentence(r) ?? (missing.push("the one sentence (brand.oneLiner or brand.sentence)"), FILL);
+    const pricing = isFilled(r?.brand.pricing) ? r.brand.pricing.trim() : (missing.push("brand.pricing"), FILL);
+    const known = knownPublicPaths(ctx.scan, ctx.audit);
+    const pages = new Map((ctx.audit?.pages ?? []).map((p) => [normPath(p.url), p]));
+    const lines = [`# ${brand}`, "", `> ${sentence}`];
+    if (isFilled(r?.brand.company))
+        lines.push(`> ${L("Operated by", "İşleten")} ${r.brand.company}${isFilled(r?.brand.country) ? ` (${r.brand.country})` : ""}.`);
+    lines.push("");
+    lines.push(`${L("Key facts", "Temel bilgiler")}: ${pricing}${/[.!?]$/.test(pricing) ? "" : "."}`);
+    if (hasNotX(r?.brand.notX))
+        lines.push(`${L("Not to be confused with", "Karıştırılmasın")}: ${r.brand.notX.trim()}`);
+    const proof = (r?.proof ?? []).filter((p) => isFilled(p.source));
+    if (proof.length)
+        lines.push(`${L("Evidence (and its limits)", "Kanıt (ve sınırı)")}: ${proof.map((p) => `${p.claim}${p.value ? `: ${p.value}` : ""} (${p.source}${p.date ? `, ${p.date}` : ""})`).join("; ")}.`);
+    if ((r?.site.languages.length ?? 0) > 1)
+        lines.push(`${L("Languages", "Diller")}: ${r.site.languages.join(", ")}`);
+    lines.push("", `## ${L("Product", "Ürün")}`);
+    lines.push(`- [${L("Home", "Ana sayfa")}](${abs(siteUrl, "/")}): ${isFilled(r?.brand.category) ? r.brand.category : L("what it is", "ne olduğu")}`);
+    const pricingPage = findPage(known, "pricing");
+    if (pricingPage)
+        lines.push(`- [${L("Pricing", "Fiyatlar")}](${abs(siteUrl, pricingPage.path)}): ${L("plans and prices", "planlar ve fiyatlar")}`);
+    let liveSituations = 0;
+    for (const s of r?.situations ?? []) {
+        const url = situationUrl(s, r?.site.languages);
+        const live = s.status === "live" || known.get(normPath(url)) === "live";
+        if (!live)
+            continue;
+        const p = pages.get(normPath(url)) ?? pages.get(normPath(abs(siteUrl, url)));
+        const desc = p?.firstParagraph ? firstSentence(p.firstParagraph) : undefined;
+        lines.push(`- [${s.sentence.replace(/[[\]]/g, "")}](${abs(siteUrl, url)})${desc ? `: ${desc}` : ""}`);
+        liveSituations++;
+        if (liveSituations >= 20)
+            break;
+    }
+    const section = (title, key) => {
+        const items = [];
+        for (const [p, src] of known) {
+            if (src !== "live" && src !== "scan")
+                continue;
+            const re = key === "guide" ? /\/(guides?|rehber\w*|blog|learn|resources)\/[^/]+/ : /(\/(compare|alternatives?|vs|karsilastirma|alternatif\w*)\/[^/]+)|-vs-/;
+            if (!re.test(p) || /[[:*$]/.test(p))
+                continue;
+            const title2 = pages.get(p)?.title ?? p;
+            items.push(`- [${title2.replace(/[[\]]/g, "")}](${abs(siteUrl, p)})`);
+            if (items.length >= 10)
+                break;
+        }
+        if (items.length)
+            lines.push("", `## ${title}`, ...items);
+    };
+    section(L("Guides", "Rehberler"), "guide");
+    section(L("Comparisons", "Karşılaştırmalar"), "comparison");
+    const legal = [findPage(known, "terms"), findPage(known, "privacy"), findPage(known, "about"), findPage(known, "faq")].filter(Boolean);
+    if (legal.length) {
+        lines.push("", "## Optional");
+        for (const l of legal)
+            lines.push(`- [${l.path}](${abs(siteUrl, l.path)})`);
+    }
+    const notes = [];
+    if (!siteUrl)
+        missing.push("site URL (katman_start with site_url)");
+    if (!liveSituations)
+        notes.push("No live situation pages yet (research status \"live\" or a 200 in the latest audit): add each one here after it ships (P6).");
+    notes.push("Every price and claim here must match the pages word for word (P8). Keep it short: the sample site's llms.txt grew to 65 KB and had to be trimmed.");
+    notes.push("llms.txt is hygiene, not a lever (no citation effect across 300k domains): ship it after rendering (P2) is fixed.");
+    if (!tr && (r?.site.languages[0] ?? "en").toLowerCase().split("-")[0] !== "en")
+        notes.push("Link labels are in English; translate them to the site's language.");
+    let conflict;
+    if (ctx.scan?.files.llms.generated && ctx.scan.files.llms.path)
+        conflict = `llms.txt is generated by ${ctx.scan.files.llms.path}; update that generator instead.`;
+    return {
+        artifact: "llms.txt",
+        content: lines.join("\n") + "\n",
+        target: joinRel(ctx.staticDir, "llms.txt"),
+        targetKind: "static",
+        fence: "md",
+        notes,
+        missing,
+        ...(conflict ? { conflict } : {}),
+    };
+}
+// ---------------------------------------------------------------------------
+// JSON-LD (appendix C)
+function genOrganization(ctx, o) {
+    const r = ctx.research;
+    const siteUrl = siteUrlOf(r, ctx.config);
+    const missing = [];
+    const notes = [];
+    const name = isFilled(r?.brand.name) ? r.brand.name.trim() : (missing.push("brand.name"), FILL);
+    const obj = {
+        "@context": "https://schema.org",
+        "@type": "Organization",
+        "@id": `${siteUrl ?? `https://${FILL}`}/#org`,
+        name,
+    };
+    if (r?.brand.alternateNames?.length)
+        obj.alternateName = r.brand.alternateNames;
+    const sentence = brandSentence(r);
+    if (sentence)
+        obj.description = sentence;
+    if (hasNotX(r?.brand.notX))
+        obj.disambiguatingDescription = r.brand.notX.trim();
+    obj.url = siteUrl ?? (missing.push("site URL"), `https://${FILL}`);
+    obj.logo = o.logo ? abs(siteUrl, o.logo) : (missing.push("logo (options.logo: an absolute or root-relative URL of a square logo)"), `${siteUrl ?? `https://${FILL}`}/${FILL}-logo-512.png`);
+    if (r?.brand.socials?.length)
+        obj.sameAs = r.brand.socials;
+    if (isFilled(r?.brand.company) && r.brand.company.trim().toLowerCase() !== name.toLowerCase())
+        obj.parentOrganization = { "@type": "Organization", name: r.brand.company.trim() };
+    if (isFilled(r?.brand.country))
+        obj.address = { "@type": "PostalAddress", addressCountry: r.brand.country.trim() };
+    if (!hasNotX(r?.brand.notX))
+        notes.push("No not-X note in research, so there's no disambiguatingDescription. Add brand.notX if assistants confuse the brand with something (ask \"What is <brand>?\").");
+    if (name !== FILL && !/\s/.test(name) && hasNotX(r?.brand.notX))
+        notes.push("The book used a distinctive two-word name (\"[Brand] [Category]\") with the short name in alternateName to end the confusion.");
+    notes.push("Put it in the site-wide layout (every page). Everything here must also be visible on the site.");
+    const json = jsonLd(obj);
+    return { artifact: "organization-jsonld", content: json, embed: scriptTag(json), target: `.katman/${GEN_DIR}/organization.jsonld.json`, targetKind: "katman", fence: "json", notes, missing };
+}
+function genWebsite(ctx) {
+    const r = ctx.research;
+    const siteUrl = siteUrlOf(r, ctx.config);
+    const missing = [];
+    const obj = {
+        "@context": "https://schema.org",
+        "@type": "WebSite",
+        "@id": `${siteUrl ?? `https://${FILL}`}/#website`,
+        url: siteUrl ?? (missing.push("site URL"), `https://${FILL}`),
+        name: isFilled(r?.brand.name) ? r.brand.name.trim() : (missing.push("brand.name"), FILL),
+        publisher: { "@id": `${siteUrl ?? `https://${FILL}`}/#org` },
+    };
+    if (r?.site.languages.length)
+        obj.inLanguage = r.site.languages.length === 1 ? r.site.languages[0] : r.site.languages;
+    const json = jsonLd(obj);
+    return { artifact: "website-jsonld", content: json, embed: scriptTag(json), target: `.katman/${GEN_DIR}/website.jsonld.json`, targetKind: "katman", fence: "json", notes: ["Site-wide, next to Organization (publisher points at its @id)."], missing };
+}
+function genSoftware(ctx, o) {
+    const r = ctx.research;
+    const siteUrl = siteUrlOf(r, ctx.config);
+    const missing = [];
+    const notes = [];
+    const obj = {
+        "@context": "https://schema.org",
+        "@type": o.type ?? "WebApplication",
+        name: isFilled(r?.brand.name) ? r.brand.name.trim() : (missing.push("brand.name"), FILL),
+        url: o.page_url ? abs(siteUrl, o.page_url) : siteUrl ?? (missing.push("site URL"), `https://${FILL}`),
+    };
+    const sentence = brandSentence(r);
+    if (sentence)
+        obj.description = sentence;
+    if (o.application_category)
+        obj.applicationCategory = o.application_category;
+    else
+        notes.push("No applicationCategory: pass options.application_category (e.g. \"MultimediaApplication\", \"BusinessApplication\") if you want it.");
+    obj.publisher = { "@id": `${siteUrl ?? `https://${FILL}`}/#org` };
+    const pricing = isFilled(r?.brand.pricing) ? r.brand.pricing : undefined;
+    if (pricing) {
+        const prices = parsePrices(pricing);
+        const free = /\bfree\b|ücretsiz|gratis/i.test(pricing);
+        const currency = prices[0]?.currency;
+        const sameCurrency = prices.every((p) => p.currency === currency);
+        if (prices.length === 1)
+            obj.offers = { "@type": "Offer", price: String(prices[0].price), priceCurrency: prices[0].currency };
+        else if (prices.length > 1 && sameCurrency) {
+            const vals = prices.map((p) => p.price).concat(free ? [0] : []);
+            obj.offers = { "@type": "AggregateOffer", lowPrice: String(Math.min(...vals)), highPrice: String(Math.max(...vals)), priceCurrency: currency, offerCount: String(vals.length) };
+        }
+        else if (!prices.length && free)
+            obj.offers = { "@type": "Offer", price: "0", priceCurrency: "USD" };
+        if (obj.offers)
+            notes.push(`offers come from research pricing ("${pricing}") and must match the pricing page exactly; fix research if they don't.`);
+        else
+            notes.push(`Couldn't read prices from research pricing ("${pricing}"), so there are no offers. Add them by hand exactly as the pricing page shows them.`);
+    }
+    else
+        notes.push("No pricing in research, so no offers (never invent a price). Fill brand.pricing, then regenerate.");
+    notes.push("Use it on the product/pricing page; only information visible on that page.");
+    const json = jsonLd(obj);
+    return { artifact: "software-jsonld", content: json, embed: scriptTag(json), target: `.katman/${GEN_DIR}/software.jsonld.json`, targetKind: "katman", fence: "json", notes, missing };
+}
+function genFaq(ctx, o) {
+    const missing = [];
+    const faq = o.faq?.filter((x) => isFilled(x.q) && isFilled(x.a)) ?? [];
+    if (!faq.length)
+        missing.push("options.faq: [{q, a}] — the exact questions and answers visible on the page");
+    const items = faq.length ? faq : [{ q: `${FILL} question as shown on the page`, a: `${FILL} answer as shown on the page` }];
+    const obj = {
+        "@context": "https://schema.org",
+        "@type": "FAQPage",
+        mainEntity: items.map((x) => ({ "@type": "Question", name: x.q.trim(), acceptedAnswer: { "@type": "Answer", text: x.a.trim() } })),
+    };
+    const notes = ["The questions and answers must be word for word the ones visible on the page. Google retired the FAQ rich result in May 2026: this is for assistants."];
+    if (faq.length && (faq.length < 5 || faq.length > 8))
+        notes.push(`${faq.length} questions: the book's situation pages use 5–8.`);
+    const json = jsonLd(obj);
+    return { artifact: "faq-jsonld", content: json, embed: scriptTag(json), target: `.katman/${GEN_DIR}/faq.jsonld.json`, targetKind: "katman", fence: "json", notes, missing };
+}
+function genBreadcrumb(ctx, o) {
+    const siteUrl = siteUrlOf(ctx.research, ctx.config);
+    const missing = [];
+    const items = o.items?.filter((x) => isFilled(x.name) && isFilled(x.url)) ?? [];
+    if (!items.length)
+        missing.push("options.items: [{name, url}] from Home to the current page");
+    if (!siteUrl)
+        missing.push("site URL");
+    const list = items.length ? items : [{ name: "Home", url: "/" }, { name: `${FILL} page name`, url: `/${FILL}` }];
+    const obj = {
+        "@context": "https://schema.org",
+        "@type": "BreadcrumbList",
+        itemListElement: list.map((x, i) => ({ "@type": "ListItem", position: i + 1, name: x.name, item: abs(siteUrl, x.url) })),
+    };
+    const json = jsonLd(obj);
+    return { artifact: "breadcrumb-jsonld", content: json, embed: scriptTag(json), target: `.katman/${GEN_DIR}/breadcrumb.jsonld.json`, targetKind: "katman", fence: "json", notes: ["Generate it per page from the same route data as the visible breadcrumb."], missing };
+}
+// ---------------------------------------------------------------------------
+// snippets + IndexNow key
+function detectTarget(scan) {
+    const p = (scan?.analytics.providers ?? []).map((x) => x.toLowerCase()).join(" ");
+    if (/gtm|tag ?manager/.test(p))
+        return "gtm";
+    if (/ga4|gtag|google/.test(p))
+        return "gtag";
+    if (/plausible/.test(p))
+        return "plausible";
+    if (/posthog/.test(p))
+        return "posthog";
+    return "auto";
+}
+function genAnalytics(ctx, o) {
+    const target = o.target ?? detectTarget(ctx.scan);
+    const notes = [
+        `Push target: ${target}${o.target ? "" : " (from the scan; pass options.target to change)"}. Events: katman_session (once per session, with katman_channel/katman_source/katman_landing) and katman_human (once the session passes the human filter).`,
+        `Add <script src="/katman-channel.js" defer></script> to the shared layout of every public page. Call window.katmanChannel.convert("signup") (or "payment", "quiz_finished") on real conversions.`,
+        "In GA4 register katman_channel as an event-scoped custom dimension; report only sessions with katman_human = true.",
+        "Trust the utm_source=chatgpt.com tag, not the referrer: 79% of the sample site's ChatGPT visitors sent no referrer.",
+        "Bots don't run this script: count them on the server with the bot-counter-snippet.",
+    ];
+    return {
+        artifact: "analytics-channel-snippet",
+        content: analyticsChannelSnippet(target),
+        target: joinRel(ctx.staticDir, "katman-channel.js"),
+        targetKind: "static",
+        fence: "js",
+        notes,
+        missing: [],
+    };
+}
+function genBotCounter(ctx, o) {
+    const platform = o.platform ?? suggestBotPlatform(ctx.scan);
+    const s = botCounterSnippet(platform);
+    return {
+        artifact: "bot-counter-snippet",
+        content: s.code,
+        target: `.katman/${GEN_DIR}/${s.fileName}`,
+        targetKind: "katman",
+        fence: "ts",
+        notes: [`Platform: ${platform}${o.platform ? "" : " (suggested from the scan; options.platform: cloudflare-worker | nextjs-middleware | express | astro-middleware | sveltekit-hooks)"}. Put it in ${s.placeAt}.`, ...s.notes],
+        missing: [],
+    };
+}
+function genIndexNowKey(ctx) {
+    const existing = ctx.config?.indexnowKey;
+    const key = existing && /^[a-zA-Z0-9-]{8,128}$/.test(existing) ? existing : (ctx.newKey ?? (() => randomBytes(16).toString("hex")))();
+    const siteUrl = siteUrlOf(ctx.research, ctx.config);
+    return {
+        artifact: "indexnow-key",
+        content: key + "\n",
+        target: joinRel(ctx.staticDir, `${key}.txt`),
+        targetKind: "static",
+        fence: "text",
+        notes: [
+            existing === key ? "Reusing the key saved in .katman/config.json." : "New key saved to .katman/config.json (indexnowKey) so katman_indexnow uses the same one.",
+            `The file must be served at ${abs(siteUrl, `/${key}.txt`)} with the key as its only content. katman_indexnow checks it before submitting.`,
+            "Submit only new or changed URLs (the sample site once sent all 173 URLs on every release).",
+        ],
+        missing: [],
+        ...(existing === key ? {} : { configUpdate: { indexnowKey: key } }),
+    };
+}
+export function generateArtifact(ctx, artifact, o = {}) {
+    switch (artifact) {
+        case "robots.txt": return genRobots(ctx, o);
+        case "llms.txt": return genLlms(ctx);
+        case "organization-jsonld": return genOrganization(ctx, o);
+        case "website-jsonld": return genWebsite(ctx);
+        case "software-jsonld": return genSoftware(ctx, o);
+        case "faq-jsonld": return genFaq(ctx, o);
+        case "breadcrumb-jsonld": return genBreadcrumb(ctx, o);
+        case "analytics-channel-snippet": return genAnalytics(ctx, o);
+        case "bot-counter-snippet": return genBotCounter(ctx, o);
+        case "indexnow-key": return genIndexNowKey(ctx);
+    }
+}
+/** Write a generated artifact. Static files: inside the project root only, never over an existing file unless overwrite. */
+export async function writeGenerated(root, g, overwrite = false) {
+    if (g.missing.length || hasPlaceholder(g.content)) {
+        return { written: false, path: g.target, reason: `still has [FILL] values (${g.missing.join("; ") || "see content"}); fill research/options and generate again.` };
+    }
+    if (g.targetKind === "katman") {
+        const rel = g.target.replace(/^\.katman\//, "");
+        const p = await writeText(root, rel, g.content);
+        return { written: true, path: p };
+    }
+    if (g.conflict && !overwrite)
+        return { written: false, path: g.target, reason: g.conflict + " Pass overwrite: true to write the static file anyway." };
+    const absPath = insideRoot(root, g.target);
+    if (!absPath)
+        return { written: false, path: g.target, reason: "target is outside the project root" };
+    if (existsSync(absPath) && !overwrite)
+        return { written: false, path: absPath, reason: "the file already exists; review the diff and pass overwrite: true to replace it" };
+    await fs.mkdir(path.dirname(absPath), { recursive: true });
+    await fs.writeFile(absPath, g.content, "utf8");
+    return { written: true, path: absPath };
+}
+export async function runGenerate(root, args) {
+    const [research, config, scan, loaded] = await Promise.all([loadResearchSafe(root), loadConfigSafe(root), loadScan(root), loadLatestAudit(root)]);
+    const sd = staticDirFor(root, scan);
+    const ctx = { root, research, config, scan, audit: loaded?.audit, staticDir: sd.dir };
+    const g = generateArtifact(ctx, args.artifact, args.options ?? {});
+    if (g.configUpdate)
+        await saveConfig(root, { ...config, ...g.configUpdate });
+    let wr;
+    if (args.write) {
+        wr = await writeGenerated(root, g, !!args.overwrite);
+        if (wr.written)
+            await logEvent(root, `katman_generate: wrote ${args.artifact} to ${wr.path}`);
+    }
+    const where = g.targetKind === "static" ? `\`${g.target}\` (static dir: ${sd.dir || "project root"}, ${sd.source})` : `\`${g.target}\` (merge it into the codebase by hand)`;
+    const parts = [`# ${g.artifact}`];
+    parts.push(`**Target:** ${where}`);
+    if (wr)
+        parts.push(wr.written ? `**Written:** ${wr.path}` : `**Not written:** ${wr.reason}`);
+    else
+        parts.push(g.targetKind === "static" ? "Not written (pass write: true to write it; existing files are never overwritten without overwrite: true)." : "Not written (pass write: true to save it under .katman/generated/).");
+    if (!research && ["llms.txt", "organization-jsonld", "website-jsonld", "software-jsonld"].includes(g.artifact))
+        parts.push("No research yet: values are [FILL]. Run katman_research first.");
+    if (g.missing.length)
+        parts.push(`**[FILL] to resolve:** ${g.missing.join("; ")}`);
+    if (g.conflict)
+        parts.push(`**Conflict:** ${g.conflict}`);
+    parts.push(codeBlock(g.content, g.fence));
+    if (g.embed)
+        parts.push(`**Embed (in the page's HTML, rendered on the server):**\n${codeBlock(g.embed, "html")}`);
+    if (g.notes.length)
+        parts.push(`**Notes:**\n${g.notes.map((n) => `- ${n}`).join("\n")}`);
+    return {
+        text: parts.join("\n\n"),
+        structured: {
+            artifact: g.artifact,
+            target: g.target,
+            targetKind: g.targetKind,
+            written: wr?.written ?? false,
+            ...(wr?.path ? { path: wr.path } : {}),
+            ...(wr && !wr.written ? { reason: wr.reason } : {}),
+            missing: g.missing,
+            content: g.content,
+        },
+    };
+}