katman-mcp 0.1.0

package/dist/tools/visibility/models.js

@@ -0,0 +1,277 @@
+export const MODELS_VERIFIED_ON = "2026-09-30";
+export const VENDORS = ["openai", "anthropic", "google", "perplexity", "x-ai"];
+export const FAMILY_LABEL = {
+    openai: "ChatGPT (OpenAI)",
+    anthropic: "Claude",
+    google: "Gemini",
+    perplexity: "Perplexity",
+    "x-ai": "Grok",
+};
+/** Gemini answered with Exa search instead of Google grounding (the default, see above). */
+export const GEMINI_EXA_LABEL = "Gemini (Exa search, proxy)";
+/** "full" panel (flagship models): the first slug in each chain that is live on OpenRouter is used. The default panel is "economy" (see resolvePanel). */
+export const DEFAULT_CHAINS = {
+    openai: ["openai/gpt-6.1-sol", "openai/gpt-6-sol", "openai/gpt-5.6-sol", "openai/gpt-6-luna"],
+    anthropic: ["anthropic/claude-sonnet-5.5", "anthropic/claude-sonnet-5", "anthropic/claude-haiku-4.5"],
+    google: ["google/gemini-3.8-flash", "google/gemini-3.7-flash", "google/gemini-3.5-flash-lite"],
+    perplexity: ["perplexity/sonar", "perplexity/sonar-pro"],
+    "x-ai": ["x-ai/grok-4.7", "x-ai/grok-4.6", "x-ai/grok-4.3", "x-ai/grok-4.20"],
+};
+/**
+ * "economy" preset: the same five families and the same native indexes, smaller models.
+ * Roughly half the cost of "full"; retrieval (what the headline "named" rate depends on) is unchanged.
+ */
+export const ECONOMY_CHAINS = {
+    openai: ["openai/gpt-6-luna", "openai/gpt-5.6-luna", "openai/gpt-6.1-sol"],
+    anthropic: ["anthropic/claude-haiku-4.5", "anthropic/claude-sonnet-5.5"],
+    google: ["google/gemini-3.8-flash", "google/gemini-3.5-flash-lite", "google/gemini-3.7-flash"],
+    perplexity: ["perplexity/sonar", "perplexity/sonar-pro"],
+    "x-ai": ["x-ai/grok-4.20", "x-ai/grok-4.3", "x-ai/grok-4.7"],
+};
+/** Cheap model with structured outputs that extracts the recommended products from an answer. */
+export const JUDGE_CHAIN = ["openai/gpt-6-luna", "google/gemini-3.1-flash-lite", "openai/gpt-5.4-nano"];
+/** "probe": the two families that carry the outcome (ChatGPT sends the traffic, Perplexity returns the most sources). */
+export const PROBE_VENDORS = ["openai", "perplexity"];
+export const PRESETS = ["full", "economy", "probe"];
+/** Built-in prices (USD per token / per search) used only when the live catalog is unreachable. Verified 2026-09-30. */
+export const FALLBACK_PRICES = {
+    "openai/gpt-6.1-sol": { prompt: 2e-6, completion: 10e-6, webSearch: 0.01 },
+    "openai/gpt-6-sol": { prompt: 2e-6, completion: 10e-6, webSearch: 0.01 },
+    "openai/gpt-5.6-sol": { prompt: 2e-6, completion: 10e-6, webSearch: 0.01 },
+    "openai/gpt-6-luna": { prompt: 0.1e-6, completion: 0.5e-6, webSearch: 0.01 },
+    "openai/gpt-5.6-luna": { prompt: 0.2e-6, completion: 1.2e-6, webSearch: 0.01 },
+    "openai/gpt-5.4-nano": { prompt: 0.2e-6, completion: 1.25e-6, webSearch: 0.01 },
+    "openai/gpt-chat-latest": { prompt: 5e-6, completion: 30e-6, webSearch: 0.01 },
+    "anthropic/claude-sonnet-5.5": { prompt: 2e-6, completion: 10e-6, webSearch: 0.01 },
+    "anthropic/claude-sonnet-5": { prompt: 2e-6, completion: 10e-6, webSearch: 0.01 },
+    "anthropic/claude-haiku-4.5": { prompt: 1e-6, completion: 5e-6, webSearch: 0.01 },
+    "google/gemini-3.8-flash": { prompt: 0.75e-6, completion: 3.75e-6, webSearch: 0.014 },
+    "google/gemini-3.7-flash": { prompt: 0.75e-6, completion: 3.75e-6, webSearch: 0.014 },
+    "google/gemini-3.5-flash-lite": { prompt: 0.3e-6, completion: 2.5e-6, webSearch: 0.014 },
+    "google/gemini-3.1-flash-lite": { prompt: 0.25e-6, completion: 1.5e-6, webSearch: 0.014 },
+    "perplexity/sonar": { prompt: 1e-6, completion: 1e-6, webSearch: 0.005 },
+    "perplexity/sonar-pro": { prompt: 3e-6, completion: 15e-6, webSearch: 0.005 },
+    "x-ai/grok-4.7": { prompt: 2e-6, completion: 6e-6, webSearch: 0.005 },
+    "x-ai/grok-4.6": { prompt: 2e-6, completion: 6e-6, webSearch: 0.005 },
+    "x-ai/grok-4.3": { prompt: 1.25e-6, completion: 2.5e-6, webSearch: 0.005 },
+    "x-ai/grok-4.20": { prompt: 1.25e-6, completion: 2.5e-6, webSearch: 0.005 },
+};
+/** Exa via OpenRouter: $0.007 per search request (auto mode, up to 10 results), docs 2026-09-30. */
+export const EXA_PRICE_PER_SEARCH = 0.007;
+/** Server-tool search budget per answer. Honoured natively by Anthropic and by OpenRouter-run engines (Exa). */
+export const MAX_SEARCHES_PER_ANSWER = 2;
+export const COST_PROFILES = {
+    "openai:native": {
+        inputTokens: [15000, 60000], outputTokens: [500, 2400], searches: [1, 5],
+        basis: "OpenAI native search, measured 5 Sep 2026: 30–61k input tokens (search content) and 2–6 searches per answer",
+    },
+    "anthropic:native": {
+        inputTokens: [10000, 25000], outputTokens: [500, 2200], searches: [1, 2],
+        basis: "Claude native search, measured 5 Sep 2026: ~22k input tokens, ~2 searches per answer (capped at 2)",
+    },
+    "google:native": {
+        inputTokens: [100, 1000], outputTokens: [600, 2400], searches: [1, 3],
+        basis: "Gemini grounding, measured 5 Sep 2026: ~80 input tokens, ~2 grounded queries per answer",
+    },
+    "perplexity:native": {
+        inputTokens: [50, 200], outputTokens: [300, 1200], searches: [1, 1],
+        basis: "Perplexity built-in search, measured 5 Sep 2026: ~60 input, 500–900 output tokens, one request fee",
+    },
+    "x-ai:native": {
+        inputTokens: [30000, 70000], outputTokens: [500, 2400], searches: [1, 3],
+        basis: "Grok native search, measured 5 Sep 2026: 57–69k input tokens per answer",
+    },
+    exa: {
+        inputTokens: [300, 12000], outputTokens: [500, 2200], searches: [0, 2],
+        basis: "Exa via the server tool: 0–2 searches of 5 results (~1k tokens each), $0.007 per search",
+    },
+    none: {
+        inputTokens: [50, 200], outputTokens: [400, 1500], searches: [0, 0],
+        basis: "no web search",
+    },
+};
+export function vendorOf(slug) {
+    const v = slug.split("/")[0]?.toLowerCase();
+    return VENDORS.includes(v) ? v : undefined;
+}
+/** Family label for an arbitrary slug: our labels for the five vendors, else the vendor prefix. */
+export function familyOf(slug, search = "native") {
+    const v = vendorOf(slug);
+    if (v === "google")
+        return search === "native" ? FAMILY_LABEL.google : GEMINI_EXA_LABEL;
+    if (v)
+        return FAMILY_LABEL[v];
+    return slug.split("/")[0] || slug;
+}
+/** Which search engine an answer from this spec uses: provider-native, Exa (OpenRouter-run) or none. */
+export function engineOf(spec) {
+    if (spec.search === "none")
+        return "none";
+    if (spec.search === "plugin")
+        return "exa";
+    return vendorOf(spec.id) ? "native" : "exa";
+}
+export function profileFor(spec) {
+    const engine = engineOf(spec);
+    if (engine === "native") {
+        const key = `${vendorOf(spec.id)}:native`;
+        return { key, profile: COST_PROFILES[key] };
+    }
+    return { key: engine, profile: COST_PROFILES[engine] };
+}
+const FAMILY_ALIASES = {
+    chatgpt: "openai", openai: "openai", gpt: "openai",
+    claude: "anthropic", anthropic: "anthropic",
+    gemini: "google", google: "google",
+    perplexity: "perplexity", sonar: "perplexity",
+    grok: "x-ai", xai: "x-ai", "x-ai": "x-ai",
+};
+export function specFor(slug, opts = {}) {
+    const v = vendorOf(slug);
+    const search = !v ? "plugin" : v === "google" && !opts.googleGrounding ? "plugin" : "native";
+    return { id: slug, family: familyOf(slug, search), search };
+}
+function pickFromChain(chain, isAvailable) {
+    const skipped = [];
+    for (const slug of chain) {
+        const ok = isAvailable ? isAvailable(slug) : undefined;
+        if (ok === false) {
+            skipped.push(slug);
+            continue;
+        }
+        return { slug, skipped };
+    }
+    return { skipped };
+}
+function chainPanel(chains, vendors, o, notes) {
+    const out = [];
+    for (const v of vendors) {
+        const { slug, skipped } = pickFromChain(chains[v], o.isAvailable);
+        if (!slug) {
+            notes.push(`${FAMILY_LABEL[v]} skipped: none of ${chains[v].join(", ")} is available on OpenRouter right now.`);
+            continue;
+        }
+        if (skipped.length)
+            notes.push(`${FAMILY_LABEL[v]}: ${skipped.join(", ")} not in the OpenRouter catalog; using ${slug}.`);
+        out.push(specFor(slug, { googleGrounding: o.googleGrounding }));
+    }
+    return out;
+}
+/** Apply the Google-grounding rule to a configured spec (native Google search needs the explicit opt-in). */
+function normalizeSpec(spec, o, notes) {
+    const v = vendorOf(spec.id);
+    if (v === "google" && spec.search === "native" && !o.googleGrounding) {
+        notes.push(`${spec.id}: Google grounding needs allow_google_grounding: true (Google's grounding terms); using Exa search instead.`);
+        return { ...spec, search: "plugin", family: GEMINI_EXA_LABEL };
+    }
+    if (v === "google" && o.googleGrounding && spec.search !== "none") {
+        return { ...spec, search: "native", family: spec.family === GEMINI_EXA_LABEL ? FAMILY_LABEL.google : spec.family };
+    }
+    if (!spec.family)
+        return { ...spec, family: familyOf(spec.id, spec.search) };
+    return spec;
+}
+/**
+ * Resolve the `models` argument into a panel. Base panel = `.katman/config.json` models when set,
+ * else the default chains. Tokens: presets (full, economy, probe), family names (chatgpt, claude,
+ * gemini, perplexity, grok) and OpenRouter slugs.
+ */
+export function resolvePanel(o) {
+    const notes = [];
+    const errors = [];
+    const configured = (o.config?.models ?? []).filter((m) => m && typeof m.id === "string" && m.id.includes("/"));
+    const base = configured.length
+        ? configured.map((m) => normalizeSpec({ ...m, search: m.search ?? "native" }, o, notes))
+        : chainPanel(DEFAULT_CHAINS, VENDORS, o, notes);
+    if (configured.length) {
+        for (const m of base) {
+            if (o.isAvailable && o.isAvailable(m.id) === false)
+                notes.push(`${m.id} (from .katman/config.json) is not in the OpenRouter catalog; its calls will fail.`);
+        }
+    }
+    const tokens = (Array.isArray(o.input) ? o.input : o.input ? [o.input] : [])
+        .flatMap((t) => String(t).split(","))
+        .map((t) => t.trim())
+        .filter(Boolean);
+    if (!tokens.length) {
+        if (configured.length)
+            return { models: base, notes, errors, preset: "config" };
+        // Default panel = "economy": same five assistants and native indexes, smaller models (≈ half the cost of "full").
+        const economyNotes = [];
+        return { models: chainPanel(ECONOMY_CHAINS, VENDORS, o, economyNotes), notes: economyNotes, errors, preset: "economy" };
+    }
+    const out = [];
+    const add = (m) => {
+        if (!out.some((x) => x.id === m.id && x.search === m.search))
+            out.push(m);
+    };
+    let preset = "custom";
+    for (const raw of tokens) {
+        const t = raw.toLowerCase();
+        if (t === "full" || t === "all" || t === "default") {
+            base.forEach(add);
+            if (tokens.length === 1)
+                preset = configured.length ? "config" : "full";
+        }
+        else if (t === "probe") {
+            const picked = base.filter((m) => PROBE_VENDORS.includes(vendorOf(m.id)));
+            if (!picked.length)
+                errors.push(`"probe" needs an OpenAI or Perplexity model in the panel.`);
+            picked.forEach(add);
+            if (tokens.length === 1)
+                preset = "probe";
+        }
+        else if (t === "economy") {
+            chainPanel(ECONOMY_CHAINS, VENDORS, o, notes).forEach(add);
+            if (tokens.length === 1)
+                preset = "economy";
+        }
+        else if (FAMILY_ALIASES[t]) {
+            const v = FAMILY_ALIASES[t];
+            const fromBase = base.filter((m) => vendorOf(m.id) === v);
+            if (fromBase.length)
+                fromBase.forEach(add);
+            else {
+                const { slug } = pickFromChain(DEFAULT_CHAINS[v], o.isAvailable);
+                if (slug)
+                    add(specFor(slug, { googleGrounding: o.googleGrounding }));
+                else
+                    errors.push(`No ${FAMILY_LABEL[v]} model is available on OpenRouter right now.`);
+            }
+        }
+        else if (raw.includes("/")) {
+            const known = base.find((m) => m.id.toLowerCase() === t);
+            const spec = known ?? specFor(raw, { googleGrounding: o.googleGrounding });
+            if (!known && o.isAvailable && o.isAvailable(raw) === false) {
+                errors.push(`${raw} is not in the OpenRouter catalog (check the slug at https://openrouter.ai/models).`);
+                continue;
+            }
+            add(normalizeSpec(spec, o, notes));
+        }
+        else {
+            errors.push(`Unknown model "${raw}". Use a preset (full, economy, probe), a family (chatgpt, claude, gemini, perplexity, grok) or an OpenRouter slug like openai/gpt-6.1-sol.`);
+        }
+    }
+    return { models: out, notes, errors, preset };
+}
+/** First judge model that is live, or the configured one. */
+export function resolveJudge(config, isAvailable) {
+    if (config?.judgeModel && config.judgeModel.includes("/"))
+        return config.judgeModel;
+    return pickFromChain(JUDGE_CHAIN, isAvailable).slug ?? JUDGE_CHAIN[0];
+}
+/** Language → approximate user location for native search (unset for English: no single market). */
+const LANG_COUNTRY = {
+    tr: "TR", de: "DE", fr: "FR", es: "ES", it: "IT", pt: "BR", nl: "NL", pl: "PL", ja: "JP", ko: "KR",
+    sv: "SE", da: "DK", fi: "FI", nb: "NO", no: "NO", cs: "CZ", ro: "RO", hu: "HU", el: "GR", id: "ID",
+    vi: "VN", th: "TH", uk: "UA", ru: "RU", he: "IL", ar: "SA",
+};
+export function countryForLang(lang) {
+    if (!lang)
+        return undefined;
+    const l = lang.toLowerCase().trim();
+    const [base, region] = l.split(/[-_]/);
+    if (region && /^[a-z]{2}$/.test(region))
+        return region.toUpperCase();
+    return LANG_COUNTRY[base];
+}

package/dist/tools/visibility/monitoring.js

@@ -0,0 +1,165 @@
+// katman_setup_monitoring: a GitHub Actions workflow that re-runs the visibility check (and the live
+// audit) on a schedule with the user's own OPENROUTER_API_KEY secret, commits .katman/ and opens an
+// issue when the mention rate drops. Zero cost to Katman. Writes only .github/workflows/katman.yml,
+// only with write: true, and never overwrites without overwrite: true.
+import path from "node:path";
+import { existsSync, promises as fs } from "node:fs";
+import { loadConfig, loadResearch, logEvent } from "../../state.js";
+import { normalizeSiteUrl } from "../../util.js";
+import { money, suggestCap } from "./estimate.js";
+import { buildPlan } from "./run.js";
+export const WORKFLOW_PATH = ".github/workflows/katman.yml";
+export const DEFAULT_SCHEDULE = "0 6 * * 1";
+/** Open an issue when the mention rate falls by at least this many percentage points between two runs. */
+export const DROP_POINTS = 10;
+export function validCron(s) {
+    const parts = s.trim().split(/\s+/);
+    return parts.length === 5 && parts.every((p) => /^[\d*/,\-A-Za-z?#LW]+$/.test(p));
+}
+/** Runs per month for simple schedules (weekly on one day, fixed days of month, daily). */
+export function runsPerMonth(cron) {
+    const [, , dom, , dow] = cron.trim().split(/\s+/);
+    if (dom === "*" && /^\d$/.test(dow ?? ""))
+        return 4.33;
+    if (dom === "*" && dow === "*")
+        return 30;
+    if (/^[\d,]+$/.test(dom ?? "") && dow === "*")
+        return dom.split(",").length;
+    return undefined;
+}
+export function buildWorkflowYaml(o) {
+    const models = o.models && /^[\w.,/:-]+$/.test(o.models) ? ` --models ${o.models}` : "";
+    const check = `npx -y katman-mcp check --root . --yes --max-cost ${o.maxCost}${models}`;
+    const site = o.siteUrl && /^https?:\/\/[^\s'"]+$/.test(o.siteUrl) ? o.siteUrl : undefined;
+    const y = [
+        "# Katman AI visibility monitoring (generated by katman-mcp; safe to edit).",
+        "# Re-asks your question set through OpenRouter with YOUR key (capped per run), commits .katman/",
+        `# and opens an issue when the share of answers that name you drops by ${DROP_POINTS}+ points.`,
+        "# `katman-mcp check` is a Katman Pro command: it needs the KATMAN_KEY repository secret (katman.pro/app).",
+        "name: Katman AI visibility",
+        "",
+        "on:",
+        "  schedule:",
+        `    - cron: "${o.schedule}"`,
+        "  workflow_dispatch: {}",
+        "",
+        "permissions:",
+        "  contents: write",
+        "  issues: write",
+        "",
+        "concurrency:",
+        "  group: katman-visibility",
+        "  cancel-in-progress: false",
+        "",
+        "jobs:",
+        "  katman:",
+        "    runs-on: ubuntu-latest",
+        "    timeout-minutes: 45",
+        "    steps:",
+        "      - uses: actions/checkout@v4",
+        "      - uses: actions/setup-node@v4",
+        "        with:",
+        "          node-version: 20",
+        "",
+        `      - name: AI visibility check (spends at most $${o.maxCost} of your OpenRouter credit)`,
+        "        continue-on-error: true",
+        "        env:",
+        "          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}",
+        "          KATMAN_KEY: ${{ secrets.KATMAN_KEY }}",
+        `        run: ${check}`,
+    ];
+    if (o.includeAudit) {
+        y.push("", "      - name: Live site audit (as AI crawlers see it)");
+        if (!site)
+            y.push("        if: ${{ vars.KATMAN_SITE_URL != '' }}");
+        y.push("        continue-on-error: true", "        env:", site ? `          KATMAN_SITE_URL: \${{ vars.KATMAN_SITE_URL || '${site}' }}` : "          KATMAN_SITE_URL: ${{ vars.KATMAN_SITE_URL }}", '        run: npx -y katman-mcp audit "$KATMAN_SITE_URL" --root .');
+    }
+    y.push("", "      - name: Commit .katman changes", "        run: |", '          git config user.name "katman-bot"', '          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"', "          git add -A .katman ':(exclude).katman/cache'", "          if git diff --cached --quiet; then", '            echo "No .katman changes."', "          else", '            git commit -m "katman: AI visibility check $(date -u +%F)"', "            git pull --rebase --autostash", "            git push", "          fi", "", "      - name: Compare the last two runs", "        if: always()", "        id: drop", "        run: |", "          node <<'EOF'", "          const fs = require('fs');", "          const path = require('path');", "          const dir = '.katman/runs';", "          const out = (k, v) => fs.appendFileSync(process.env.GITHUB_OUTPUT, `${k}=${v}\\n`);", "          let files = [];", "          try { files = fs.readdirSync(dir).filter((f) => f.endsWith('.json') && !f.startsWith('manual-')).sort(); } catch {}", "          const runs = files", "            .map((f) => { try { return JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8')); } catch { return null; } })", "            .filter((r) => r && r.summary && r.summary.answered >= 5);", "          if (runs.length < 2) { out('dropped', 'false'); process.exit(0); }", "          const [prev, cur] = runs.slice(-2);", "          const before = Math.round(prev.summary.mentionRate * 100);", "          const after = Math.round(cur.summary.mentionRate * 100);", "          out('before', before);", "          out('after', after);", "          out('run', cur.id);", "          // Only a run made by this workflow run counts; otherwise the same drop would open an issue every week.", "          const fresh = Date.now() - Date.parse(cur.ts) < 36 * 3600 * 1000;", `          out('dropped', String(fresh && before - after >= ${DROP_POINTS}));`, "          EOF", "", "      - name: Open an issue when the mention rate dropped", "        if: always() && steps.drop.outputs.dropped == 'true'", "        env:", "          GH_TOKEN: ${{ github.token }}", "          BEFORE: ${{ steps.drop.outputs.before }}", "          AFTER: ${{ steps.drop.outputs.after }}", "          RUN_ID: ${{ steps.drop.outputs.run }}", "        run: |", "          cat > katman-issue.md <<EOF", "          AI assistants named you in ${AFTER}% of the unbranded answers in run ${RUN_ID}, down from ${BEFORE}% in the run before.", "", "          - Who was recommended instead and which sources the assistants used: .katman/measurements.md", "          - One run is a small sample; check whether the drop holds in the next run before changing course.", "          - Confirm key questions by hand with katman_manual_check (logged out, web search on).", "          EOF", '          gh issue create --title "Katman: AI assistants name you less often (${BEFORE}% → ${AFTER}%)" --body-file katman-issue.md');
+    return y.join("\n") + "\n";
+}
+export async function setupMonitoring(root, args) {
+    const schedule = (args.schedule ?? DEFAULT_SCHEDULE).trim();
+    if (!validCron(schedule)) {
+        return { text: `"${schedule}" is not a 5-field cron expression (minute hour day-of-month month day-of-week), e.g. "${DEFAULT_SCHEDULE}" (Mondays 06:00 UTC) or "0 6 1,15 * *" (twice a month).`, isError: true };
+    }
+    const includeAudit = args.include_audit !== false;
+    const research = await loadResearch(root);
+    const config = await loadConfig(root);
+    const notes = [];
+    // Estimate offline (cached catalog or built-in prices): setting up monitoring makes no network calls.
+    const { plan, error } = await buildPlan(root, { models: args.models, dry_run: true }, { offline: true });
+    let maxCost = args.max_cost_usd;
+    let costLine = "Cost per run: unknown until the research question set exists.";
+    if (plan) {
+        const e = plan.estimate;
+        maxCost ??= Math.max(2, suggestCap(e.total.high));
+        const perMonth = runsPerMonth(schedule);
+        costLine = `Cost per run: about ${money(e.total.expected)} (${money(e.total.low)}–${money(e.total.high)}, ${e.answers} answers), capped at ${money(maxCost)}${perMonth ? `; ≈ ${money(e.total.expected * perMonth)} a month on this schedule` : ""}. Paid from your OpenRouter credit; Katman costs nothing.`;
+        if (e.total.expected > maxCost)
+            notes.push(`The expected cost is above --max-cost ${maxCost}: every scheduled run would refuse to start. Raise max_cost_usd or use models: "economy" / "probe".`);
+    }
+    else {
+        maxCost ??= 2;
+        notes.push(error?.text.includes("question set") || !research ? "Create the research question set first (katman_research with generate_questions: true) and commit .katman/research.json; the scheduled check needs it." : "Could not estimate the cost: " + (error?.text.split("\n").find((l) => l.startsWith("- ")) ?? "see katman_visibility_run with dry_run: true."));
+    }
+    let siteUrl;
+    try {
+        const raw = config.siteUrl || research?.site?.url;
+        siteUrl = raw ? normalizeSiteUrl(raw) : undefined;
+    }
+    catch {
+        siteUrl = undefined;
+    }
+    const yaml = buildWorkflowYaml({ schedule, includeAudit, maxCost, models: args.models, siteUrl });
+    let writeLine;
+    const target = path.join(root, WORKFLOW_PATH);
+    let isError = false;
+    if (args.write) {
+        if (existsSync(target) && !args.overwrite) {
+            writeLine = `**Not written:** ${WORKFLOW_PATH} already exists. Compare it with the YAML below, then pass overwrite: true to replace it.`;
+            isError = true;
+        }
+        else {
+            await fs.mkdir(path.dirname(target), { recursive: true });
+            await fs.writeFile(target, yaml, "utf8");
+            await logEvent(root, `katman_setup_monitoring wrote ${WORKFLOW_PATH} (schedule "${schedule}", max cost ${maxCost})`);
+            writeLine = `Written to ${WORKFLOW_PATH}.`;
+        }
+    }
+    else {
+        writeLine = `Not written (pass write: true to create ${WORKFLOW_PATH}).`;
+    }
+    const L = [
+        "# Scheduled AI visibility monitoring (GitHub Actions)",
+        "",
+        `Schedule \`${schedule}\` (UTC)${schedule === DEFAULT_SCHEDULE ? ": every Monday 06:00" : ""}. Each run: re-asks the question set (\`katman-mcp check\`)${includeAudit ? ", audits the live site as AI crawlers see it" : ""}, commits .katman/ changes, and opens an issue if the share of answers naming you drops by ${DROP_POINTS}+ points.`,
+        costLine,
+        "",
+        writeLine,
+        "",
+        "```yaml",
+        yaml.trimEnd(),
+        "```",
+        "",
+        "## Setup steps",
+        "",
+        "1. Add your keys as repository secrets: GitHub → Settings → Secrets and variables → Actions → New repository secret, name `OPENROUTER_API_KEY` (or `gh secret set OPENROUTER_API_KEY`), and `KATMAN_KEY` with your Katman Pro key from https://katman.pro/app → MCP (`gh secret set KATMAN_KEY`; `katman-mcp check` is a Pro command and stops without it). Give the OpenRouter key its own credit limit at https://openrouter.ai/keys, e.g. your monthly budget.",
+        includeAudit
+            ? `2. Add a repository variable \`KATMAN_SITE_URL\` = your live URL (Variables tab, or \`gh variable set KATMAN_SITE_URL --body https://…\`)${siteUrl ? `; without it the workflow audits ${siteUrl}` : "; without it the audit step is skipped"}.`
+            : "2. (Audit step off.)",
+        "3. Commit `.github/workflows/katman.yml` and `.katman/research.json` (the check needs the question set).",
+        "4. If your organisation restricts the default token: Settings → Actions → General → Workflow permissions → Read and write (the workflow asks for contents: write and issues: write).",
+        "5. Test it: Actions → \"Katman AI visibility\" → Run workflow.",
+        "",
+        "Notes:",
+        "- The book re-measures every 14 days; for that cadence use schedule `0 6 1,15 * *`. Weekly runs show the trend sooner at twice the cost.",
+        "- A run whose estimate is above the cap refuses to start (nothing spent). A run that hits 402 (no credit) saves its partial results.",
+        "- .katman/cache/ is never committed; .katman/ never contains either key.",
+        ...notes.map((n) => `- ${n}`),
+    ];
+    return {
+        text: L.join("\n"),
+        isError,
+        structured: { status: args.write ? (isError ? "exists" : "written") : "preview", path: WORKFLOW_PATH, schedule, maxCostUsd: maxCost, includeAudit },
+    };
+}