katman-mcp 0.1.0

package/dist/state.js

@@ -0,0 +1,81 @@
+// All Katman state lives in <project>/.katman/. Writes never leave that folder.
+import path from "node:path";
+import { promises as fs } from "node:fs";
+export const KATMAN_DIR = ".katman";
+export function katmanPath(root, ...parts) {
+    const base = path.resolve(root, KATMAN_DIR);
+    const p = path.resolve(base, ...parts);
+    if (p !== base && !p.startsWith(base + path.sep)) {
+        throw new Error(`Refusing to access ${p}: outside ${base}`);
+    }
+    return p;
+}
+export async function ensureDir(root, rel = "") {
+    const dir = katmanPath(root, rel);
+    await fs.mkdir(dir, { recursive: true });
+    return dir;
+}
+export async function readText(root, rel) {
+    try {
+        return await fs.readFile(katmanPath(root, rel), "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function writeText(root, rel, text) {
+    const p = katmanPath(root, rel);
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    await fs.writeFile(p, text, "utf8");
+    return p;
+}
+export async function readJson(root, rel) {
+    const t = await readText(root, rel);
+    if (t === undefined)
+        return undefined;
+    try {
+        return JSON.parse(t);
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function writeJson(root, rel, data) {
+    return writeText(root, rel, JSON.stringify(data, null, 2) + "\n");
+}
+/** List file names (not paths) in a .katman subfolder, sorted ascending. */
+export async function listFiles(root, relDir) {
+    try {
+        const names = await fs.readdir(katmanPath(root, relDir));
+        return names.sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** Filesystem-safe UTC timestamp: 2026-09-30T14-05-09Z */
+export function stamp(d = new Date()) {
+    return d.toISOString().replace(/\.\d{3}Z$/, "Z").replace(/:/g, "-");
+}
+export function today(d = new Date()) {
+    return d.toISOString().slice(0, 10);
+}
+export async function loadResearch(root) {
+    return readJson(root, "research.json");
+}
+export async function saveResearch(root, r) {
+    r.updatedAt = new Date().toISOString();
+    return writeJson(root, "research.json", r);
+}
+export async function loadConfig(root) {
+    return (await readJson(root, "config.json")) ?? {};
+}
+export async function saveConfig(root, c) {
+    return writeJson(root, "config.json", c);
+}
+/** Append a line to .katman/log.md so the project keeps a dated history of what Katman did. */
+export async function logEvent(root, line) {
+    const p = katmanPath(root, "log.md");
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    await fs.appendFile(p, `- ${new Date().toISOString()} ${line}\n`, "utf8");
+}

package/dist/tools/account/account.js

@@ -0,0 +1,64 @@
+// katman_account (free): the Katman plan behind KATMAN_KEY, trial days left, Pro features, masked account
+// email, last check, and how to connect or upgrade. Never shows the key.
+import { FREE_TOOLS, PRO_TOOLS, allows } from "../../license.js";
+import { APP_URL, BILLING_URL, PRO_PRICE_NOTE } from "../../meta.js";
+import { fmtDay, fmtWhen, howToText, reasonText, trialDaysLeft } from "./upsell.js";
+export async function runAccount(provider, opts = {}) {
+    const now = opts.now ?? new Date();
+    const s = await provider.status({ refresh: opts.refresh });
+    const left = trialDaysLeft(s, now);
+    const proTools = Object.keys(PRO_TOOLS);
+    const on = proTools.filter((t) => allows(s, PRO_TOOLS[t]));
+    const planCell = s.state === "no_key"
+        ? "Free (no KATMAN_KEY)"
+        : s.state !== "valid"
+            ? `Free (key ${s.state === "unreachable" ? "not verified" : s.state})`
+            : s.plan === "trial"
+                ? `Trial: ${left ?? "?"} day${left === 1 ? "" : "s"} left (ends ${fmtDay(s.trialEndsAt)})`
+                : s.plan === "pro"
+                    ? "Katman Pro"
+                    : `Free${s.trialEnded ? ` (trial ended ${fmtDay(s.trialEndsAt)})` : ""}`;
+    const source = s.source === "cache" ? "cached answer" : s.source === "network" ? "just checked" : s.source === "offline-grace" ? `offline grace until ${fmtWhen(s.graceUntil)}` : s.source === "local" ? "not sent: malformed key" : "no key";
+    const rows = [
+        ["Plan", planCell],
+        ["Account", s.emailMasked ?? "–"],
+        ["Key", s.state === "no_key" ? (s.hint ? "placeholder, not filled" : "not set (KATMAN_KEY)") : `${s.keyHint ?? "km_…"} (from KATMAN_KEY)`],
+        ["Pro features", s.features.length ? s.features.join(", ") : "none"],
+        ["Last check", s.checkedAt ? `${fmtWhen(s.checkedAt)} (${source}${s.nextCheckAt && s.source !== "offline-grace" ? `; next check after ${fmtWhen(s.nextCheckAt)}` : ""})` : `– (${source})`],
+    ];
+    if (s.error)
+        rows.push(["Connection", `couldn't reach katman.pro: ${s.error}`]);
+    const L = ["# Katman account", rows.map(([k, v]) => `- **${k}:** ${v}`).join("\n")];
+    L.push(`**Free tools** (no key): ${FREE_TOOLS.join(", ")}.`, `**Pro tools** (${on.length === proTools.length ? "on" : on.length ? `${on.length} of ${proTools.length} on` : "off"}): ${proTools.join(", ")}.`);
+    if (s.state === "valid" && s.plan === "pro") {
+        L.push(`Manage the subscription and invoices at ${BILLING_URL}.`);
+    }
+    else if (s.state === "valid" && s.plan === "trial") {
+        L.push(`Keep Pro after the trial: ${BILLING_URL} (${PRO_PRICE_NOTE}). The key stays the same.`);
+    }
+    else {
+        if (s.state !== "no_key" || s.hint)
+            L.push(`**Why Pro tools are off:** ${reasonText(s)}`);
+        L.push(howToText(s));
+    }
+    L.push(`Network: Katman contacts katman.pro only to check this key (at most once a day, only when KATMAN_KEY is set) and when you call katman_sync. The key is never shown or written to disk; the cache (~/.katman/license.json) stores its SHA-256 hash. Account and keys: ${APP_URL}.`);
+    return {
+        text: L.join("\n\n"),
+        structured: {
+            state: s.state,
+            plan: s.plan,
+            trialEndsAt: s.trialEndsAt ?? null,
+            trialDaysLeft: left ?? null,
+            trialEnded: !!s.trialEnded,
+            features: s.features,
+            account: { emailMasked: s.emailMasked ?? null },
+            checkedAt: s.checkedAt ?? null,
+            nextCheckAt: s.nextCheckAt ?? null,
+            source: s.source,
+            graceUntil: s.graceUntil ?? null,
+            freeTools: [...FREE_TOOLS],
+            proTools,
+            proToolsOn: on,
+        },
+    };
+}

package/dist/tools/account/cli.js

@@ -0,0 +1,21 @@
+import { parseArgs } from "../../cli.js";
+import { defaultLicense } from "../../license.js";
+import { runAccount } from "./account.js";
+export const commands = {
+    account: async (args, deps) => {
+        const { flags } = parseArgs(args);
+        try {
+            const out = await runAccount(deps?.license ?? defaultLicense(), { refresh: flags.refresh === true || flags.refresh === "true" });
+            console.log(out.text);
+            return 0;
+        }
+        catch (e) {
+            console.error(`katman account: ${e instanceof Error ? e.message : String(e)}`);
+            return 1;
+        }
+    },
+};
+export const help = [
+    "  katman-mcp account [--refresh]  Katman plan behind KATMAN_KEY (free / trial / Pro) and how to connect or upgrade",
+    "                             Pro commands (plan, report, check, indexnow --submit) need KATMAN_KEY; exit code 4 without it",
+];

package/dist/tools/account/index.js

@@ -0,0 +1,48 @@
+// Account module: katman_account (free: plan, trial days, features, how to connect/upgrade) and katman_sync
+// (Pro: sends aggregates to the katman.pro dashboard; dry run first).
+import { z } from "zod";
+import { resolveRoot, rootWarning } from "../../context.js";
+import { PRO_NOTE, licenseOf, withPro } from "../../license.js";
+import { fail, ok } from "../../util.js";
+import { runAccount } from "./account.js";
+import { runSync } from "./sync.js";
+export function registerAccountTools(server, ctx) {
+    server.registerTool("katman_account", {
+        title: "Katman account and plan",
+        description: "Free. Shows the Katman plan behind KATMAN_KEY (free, trial with the days left, or Pro), the Pro features it unlocks, the account email (masked), when the key was last checked, and how to connect or upgrade (7-day free trial at katman.pro/app, with the exact MCP config snippet per editor). Checks the key with katman.pro at most once a day; refresh: true re-checks now (e.g. right after upgrading). Never shows the key.",
+        inputSchema: {
+            refresh: z.boolean().optional().describe("Re-check the key with katman.pro now instead of using today's cached answer (e.g. right after upgrading)."),
+        },
+        annotations: { title: "Katman account", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async ({ refresh }) => {
+        try {
+            const out = await runAccount(licenseOf(ctx), { refresh });
+            return ok(out.text, out.structured);
+        }
+        catch (e) {
+            return fail(`katman_account failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    });
+    server.registerTool("katman_sync", {
+        title: "Sync progress to the katman.pro dashboard",
+        description: "Sends this project's progress to the user's katman.pro dashboard: name and domain, gate pass counts from the latest audit, visibility rates by assistant and language from the latest run, plan progress, the top 10 issue titles, dates and the Katman version. Never code, file contents, AI answers, questions or prompts. dry_run (default true) shows the exact JSON and sends nothing; dry_run: false sends it and returns the dashboard link." +
+            PRO_NOTE,
+        inputSchema: {
+            project_root: z.string().optional().describe("Absolute path of the project (where .katman/ lives)."),
+            dry_run: z.boolean().optional().describe("Default true: show the exact payload, send nothing. false = send it to katman.pro."),
+        },
+        annotations: { title: "Sync to katman.pro", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, withPro(ctx, "sync", async ({ project_root, dry_run }) => {
+        try {
+            const root = await resolveRoot(ctx, project_root);
+            const out = await runSync(root, licenseOf(ctx), { dry_run }, { version: ctx.version });
+            if (!out.isError)
+                return ok(out.text, out.structured);
+            const warn = rootWarning(root);
+            return fail(warn ? `${warn}\n\n${out.text}` : out.text);
+        }
+        catch (e) {
+            return fail(`katman_sync failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }));
+}

package/dist/tools/account/sync.js

@@ -0,0 +1,142 @@
+import { logEvent } from "../../state.js";
+import { domainOf, sortFindings, truncate } from "../../util.js";
+import { katmanMtime, loadConfigSafe, loadLatestAudit, loadResearchSafe, loadRuns, loadScan, runDate } from "../method/lib/state.js";
+import { loadPlanState, openTasks } from "../method/core/plan.js";
+import { BILLING_URL, KEYS_URL } from "../../meta.js";
+const REMEASURE_DAYS = 14;
+const num = (x) => (typeof x === "number" && Number.isFinite(x) ? x : 0);
+const rate = (x) => Math.round(Math.min(1, Math.max(0, num(x))) * 1000) / 1000;
+const iso = (s) => {
+    const t = Date.parse(s ?? "");
+    return Number.isFinite(t) ? new Date(t).toISOString() : undefined;
+};
+const filled = (s) => !!s && !!s.trim() && !/\[(FILL|DOLDUR)\]/i.test(s);
+function counts(rec) {
+    const out = {};
+    for (const [k, v] of Object.entries(rec ?? {}).slice(0, 20)) {
+        if (!v || typeof v !== "object")
+            continue;
+        const c = v;
+        out[truncate(String(k), 60)] = { answered: num(c.answered), mentioned: num(c.mentioned), recommendedFirst: num(c.recommendedFirst), cited: num(c.cited) };
+    }
+    return out;
+}
+const isManual = (r) => r.id.startsWith("manual") || (r.answers.length > 0 && r.answers.every((a) => a.source === "manual"));
+/** Build the exact body for /api/web/mcp/sync (without the key). */
+export async function buildSyncPayload(root, opts) {
+    const now = opts.now ?? new Date();
+    const [research, config, scan, loaded, runs, planState] = await Promise.all([
+        loadResearchSafe(root), loadConfigSafe(root), loadScan(root), loadLatestAudit(root), loadRuns(root), loadPlanState(root),
+    ]);
+    let domain = research?.site.domain || "";
+    const url = config.siteUrl || research?.site.url;
+    if (!domain && url)
+        domain = domainOf(url);
+    if (!domain || !domain.includes(".")) {
+        return { problem: "No site domain yet: call katman_start with site_url (e.g. https://example.com) first, so the dashboard knows which site this is." };
+    }
+    const name = filled(research?.brand.name) ? truncate(research.brand.name.trim(), 80) : domain;
+    const audit = loaded?.audit;
+    const gate = (g) => ({ pass: num(g.pass), total: num(g.total) });
+    const measured = runs.filter((r) => num(r.summary.answered) > 0);
+    const api = measured.filter((r) => !isManual(r));
+    const last = api[api.length - 1] ?? measured[measured.length - 1];
+    const lastDate = last ? runDate(last) : undefined;
+    const plan = planState.plan;
+    const tasks = Array.isArray(plan?.tasks) ? plan.tasks : [];
+    const findings = new Map();
+    for (const f of scan?.findings ?? [])
+        findings.set(f.id, f);
+    for (const f of audit?.findings ?? [])
+        findings.set(f.id, f);
+    const topIssues = sortFindings([...findings.values()].filter((f) => f.severity !== "info"))
+        .slice(0, 10)
+        .map((f) => truncate(f.title.replace(/\s+/g, " ").trim(), 160));
+    const reportAt = await katmanMtime(root, "report.md");
+    const dates = {};
+    const setDate = (k, v) => {
+        const d = iso(v);
+        if (d)
+            dates[k] = d;
+    };
+    setDate("research", research?.updatedAt);
+    setDate("scan", scan?.ts);
+    setDate("audit", audit?.ts);
+    setDate("visibilityRun", lastDate?.toISOString());
+    setDate("plan", plan?.generatedAt);
+    setDate("report", reportAt?.toISOString());
+    if (lastDate)
+        setDate("nextMeasure", new Date(lastDate.getTime() + REMEASURE_DAYS * 86_400_000).toISOString());
+    const summary = {
+        katmanVersion: opts.version,
+        generatedAt: now.toISOString(),
+        gates: audit ? { read: gate(audit.gates.read), quote: gate(audit.gates.quote), fit: gate(audit.gates.fit) } : null,
+        visibility: last && lastDate
+            ? {
+                runAt: lastDate.toISOString(),
+                answered: num(last.summary.answered),
+                mentionRate: rate(last.summary.mentionRate),
+                recommendedFirstRate: rate(last.summary.recommendedFirstRate),
+                citationRate: rate(last.summary.citationRate),
+                byFamily: counts(last.summary.byFamily),
+                byLanguage: counts(last.summary.byLanguage),
+            }
+            : null,
+        plan: plan && tasks.length ? { done: tasks.length - openTasks(plan).length, total: tasks.length } : null,
+        topIssues,
+        dates,
+    };
+    return { payload: { project: { name, domain }, summary } };
+}
+export async function runSync(root, provider, args, opts) {
+    const { payload, problem } = await buildSyncPayload(root, opts);
+    if (!payload)
+        return { text: problem ?? "Nothing to sync.", isError: true };
+    const endpoint = `${provider.baseUrl()}/api/web/mcp/sync`;
+    const shown = JSON.stringify({ key: "<KATMAN_KEY>", ...payload }, null, 2);
+    const s = payload.summary;
+    const contents = [
+        s.gates ? `gate pass counts from the audit of ${(s.dates.audit ?? "").slice(0, 10)}` : "no audit yet",
+        s.visibility ? `visibility rates from the measurement of ${s.visibility.runAt.slice(0, 10)} (${Object.keys(s.visibility.byFamily).length} assistant${Object.keys(s.visibility.byFamily).length === 1 ? "" : "s"})` : "no measurement yet",
+        s.plan ? `plan progress ${s.plan.done}/${s.plan.total}` : "no plan yet",
+        `${s.topIssues.length} issue title${s.topIssues.length === 1 ? "" : "s"}`,
+    ].join(" · ");
+    if (args.dry_run !== false) {
+        return {
+            text: [
+                "# katman_sync: dry run (nothing was sent)",
+                `Katman would POST this JSON to ${endpoint}. \`key\` is your KATMAN_KEY (never shown or stored); everything else is exactly what would be sent:`,
+                "```json\n" + shown + "\n```",
+                `Contents: ${contents}. Only aggregates: never code, file contents, AI answers, questions or prompts.`,
+                `Show this to the user. To send it: \`katman_sync\` \`${JSON.stringify({ project_root: root, dry_run: false })}\`, then open ${provider.baseUrl()}/app/projects.`,
+            ].join("\n\n"),
+            structured: { sent: false, dryRun: true, endpoint, payload },
+        };
+    }
+    const res = await provider.sync(payload);
+    if (res.ok) {
+        await logEvent(root, `katman_sync: sent the project summary for ${payload.project.domain} to ${provider.baseUrl()} (${contents})`);
+        return {
+            text: [
+                "# katman_sync: sent",
+                `Synced **${payload.project.name}** (${payload.project.domain}) to the Katman dashboard: ${res.dashboardUrl}`,
+                `Sent: ${contents}. Run katman_sync again after the next audit or measurement to add a point to the history.`,
+            ].join("\n\n"),
+            structured: { sent: true, dashboardUrl: res.dashboardUrl, projectId: res.projectId ?? null, payload },
+        };
+    }
+    const why = res.error === "invalid_key" || res.error === "revoked" || res.error === "no_key"
+        ? `katman.pro did not accept KATMAN_KEY (${res.error}). Create a key at ${KEYS_URL}, put it in the MCP config as KATMAN_KEY and restart the server.`
+        : res.error === "not_pro" || res.status === 402 || res.status === 403
+            ? `katman.pro says this account has no active Katman Pro plan or trial (${res.error}). Upgrade at ${BILLING_URL}, then call katman_account with refresh: true.`
+            : res.status === 0
+                ? `Couldn't reach katman.pro (${res.message ?? res.error ?? "network error"}). Nothing was sent; try again later.`
+                : res.status === 429
+                    ? "Too many syncs in the last hour (rate_limited). Nothing was saved; try again later."
+                    : res.error === "too_many_projects"
+                        ? "This account already has the maximum number of projects on the dashboard (too_many_projects). Nothing was saved."
+                        : res.error === "invalid_project"
+                            ? "katman.pro didn't accept the project's domain (invalid_project): check siteUrl in .katman/config.json (katman_start with site_url)."
+                            : `katman.pro answered HTTP ${res.status}${res.error && !res.error.startsWith("HTTP") ? ` (${res.error})` : ""}${res.message ? `: ${res.message}` : ""}. Nothing was saved on the dashboard; try again later.`;
+    return { text: `katman_sync: not sent. ${why}`, isError: true, structured: { sent: false, error: res.error ?? null, status: res.status } };
+}

package/dist/tools/account/upsell.js

@@ -0,0 +1,290 @@
+// Katman Pro texts: the upsell a Pro tool returns without a license (MCP and CLI), the one-line plan status,
+// the "needs Pro" notice for katman_start and the MCP config snippets with KATMAN_KEY.
+// Only type imports from license.ts (license.ts imports this module).
+import os from "node:os";
+import path from "node:path";
+import { APP_URL, BILLING_URL, KEYS_URL, PRO_PRICE_NOTE, TRIAL_DAYS } from "../../meta.js";
+import { listFiles } from "../../state.js";
+import { domainOf, sortFindings, truncate } from "../../util.js";
+import { loadConfigSafe, loadLatestAudit, loadResearchSafe, loadScan } from "../method/lib/state.js";
+const FREE_LIST = "katman_start, katman_research, katman_scan_code, katman_audit_site, katman_keywords";
+const filled = (s) => !!s && !!s.trim() && !/\[(FILL|DOLDUR)\]/i.test(s);
+export async function projectFacts(root) {
+    if (root === path.parse(root).root || root === os.homedir())
+        return undefined;
+    const [research, config, scan, loaded, runFiles] = await Promise.all([
+        loadResearchSafe(root), loadConfigSafe(root), loadScan(root), loadLatestAudit(root), listFiles(root, "runs"),
+    ]);
+    const audit = loaded?.audit;
+    if (!research && !scan && !audit && !config.siteUrl)
+        return undefined;
+    let domain = research?.site.domain || undefined;
+    if (!domain && (config.siteUrl || research?.site.url))
+        domain = domainOf(config.siteUrl || research.site.url);
+    const findings = new Map();
+    for (const f of scan?.findings ?? [])
+        findings.set(f.id, f);
+    for (const f of audit?.findings ?? [])
+        findings.set(f.id, f);
+    const issues = sortFindings([...findings.values()].filter((f) => f.severity !== "info"));
+    return {
+        ...(filled(research?.brand.name) ? { brand: research.brand.name } : {}),
+        ...(domain ? { domain } : {}),
+        ...(scan && scan.framework.name !== "unknown" ? { framework: scan.framework.name } : {}),
+        situations: research?.situations.length ?? 0,
+        questions: research?.questions.length ?? 0,
+        ...(scan ? { scan: { findings: scan.findings.filter((f) => f.severity !== "info").length, critical: scan.findings.filter((f) => f.severity === "critical").length } } : {}),
+        ...(audit
+            ? { audit: { date: audit.ts.slice(0, 10), gates: { read: pick(audit.gates.read), quote: pick(audit.gates.quote), fit: pick(audit.gates.fit) } } }
+            : {}),
+        topIssues: issues.slice(0, 3).map((f) => truncate(f.title, 110)),
+        runs: runFiles.filter((n) => n.endsWith(".json")).length,
+    };
+}
+const pick = (g) => ({ pass: g.pass, total: g.total });
+function gatesText(a) {
+    return `Read ${a.gates.read.pass}/${a.gates.read.total} · Quote ${a.gates.quote.pass}/${a.gates.quote.total} · Fit ${a.gates.fit.pass}/${a.gates.fit.total} pages pass`;
+}
+function foundText(f) {
+    const parts = [];
+    if (f?.scan)
+        parts.push(`the code scan (${f.scan.findings} issue${f.scan.findings === 1 ? "" : "s"}${f.scan.critical ? `, ${f.scan.critical} critical` : ""})`);
+    if (f?.audit)
+        parts.push(`the live audit (${gatesText(f.audit)})`);
+    return parts.length ? ` in ${parts.join(" and ")}` : "";
+}
+/** One sentence: what this Pro tool would do for this project. */
+export function pitch(tool, args, f) {
+    const brand = f?.brand ?? f?.domain ?? "this site";
+    const str = (k) => (typeof args[k] === "string" && args[k] ? String(args[k]) : undefined);
+    switch (tool) {
+        case "katman_plan":
+            return `turn what Katman found${foundText(f)} into ${brand}'s page plan (which situation, comparison, pricing and FAQ pages are missing) and a 30-day task list, each task with a prompt code and an acceptance check.`;
+        case "katman_prompt":
+            return `give your AI prompt ${str("id") ?? "P0–P14"} filled with ${brand}'s research (one sentence, not-X note, competitors${f?.situations ? `, ${f.situations} customer situations` : ""}), with the acceptance criterion and the exact Katman check that proves the task is done.`;
+        case "katman_page_brief":
+            return `write the brief for ${brand}'s ${str("type") ?? "next"} page: URL, title, first sentence, proof, not-for, alternatives, FAQ, the JSON-LD to include and where the file goes${f?.framework ? ` in this ${f.framework} project` : ""}.`;
+        case "katman_generate":
+            return `generate ${str("artifact") ?? "robots.txt, llms.txt, JSON-LD and the AI-channel analytics snippet"} for ${brand} from the research (one source of truth), ready to write into the project.`;
+        case "katman_lint_content":
+            return "check the page against the content rules before it ships: an answer in the first 1–3 sentences, the same one sentence as everywhere else, no hype or unsourced numbers, an FAQ, a not-for section and internal links.";
+        case "katman_visibility_run":
+            return `ask ${f?.questions ? `your ${f.questions} questions` : "your question set"} to ChatGPT, Claude, Gemini, Perplexity and Grok with live web search (on your own OpenRouter key, after a cost estimate) and record whether ${brand} is named, recommended first and cited, and who is recommended instead.`;
+        case "katman_manual_check":
+            return `turn answers pasted from the ChatGPT, Claude, Gemini or Perplexity apps into a measurement: whether ${brand} is named, in which position, who is recommended instead and which pages are cited.`;
+        case "katman_indexnow":
+            return `tell Bing (and through it Copilot and ChatGPT search), Yandex and the other IndexNow engines about only the new or changed pages of ${f?.domain ?? "your site"}, with the Search Console, Bing and Brave checklist.`;
+        case "katman_report":
+            return `write a shareable report for ${brand}: gate pass rates, AI-visibility changes, the competitors assistants name instead, the sites they cite, plan progress and the next 7 days.`;
+        case "katman_setup_monitoring":
+            return `set up a GitHub Actions workflow that re-measures ${brand}'s AI visibility on a schedule with your own OpenRouter key and opens an issue when mentions drop.`;
+        case "katman_sync":
+            return `send ${brand}'s progress (gate pass counts, visibility rates, plan progress, top issue titles; never code or content) to your katman.pro dashboard.`;
+        default:
+            return "run the Katman Pro step of the method for this project.";
+    }
+}
+function freeDoneText(f) {
+    if (f?.scan || f?.audit) {
+        const top = f.topIssues.length ? ` Top issues: ${f.topIssues.map((t) => `“${t}”`).join("; ")}.` : "";
+        return `**Already done for free:** the diagnosis${foundText(f)}.${top} The free tools (${FREE_LIST}) keep working without a key.`;
+    }
+    return `**Free, no key needed:** the diagnosis. katman_scan_code (your code) and katman_audit_site (your live site, as AI crawlers see it) find what keeps assistants from reading, quoting and recommending the site; katman_research and katman_keywords build the research.`;
+}
+// ---------------------------------------------------------------------------------------------------------------
+// Status texts
+const day = (iso) => (iso ? iso.slice(0, 10) : "?");
+const when = (iso) => (iso ? `${iso.slice(0, 10)} ${iso.slice(11, 16)} UTC` : "–");
+export function trialDaysLeft(s, now = new Date()) {
+    if (s.plan !== "trial" || !s.trialEndsAt)
+        return undefined;
+    return Math.max(0, Math.ceil((Date.parse(s.trialEndsAt) - now.getTime()) / 86_400_000));
+}
+function offlineText(s) {
+    return s.source === "offline-grace" ? ` · offline: using the check from ${day(s.checkedAt)}, works until ${day(s.graceUntil)}` : "";
+}
+/** Why a Pro tool didn't run (one or two sentences). */
+export function reasonText(s, feature) {
+    switch (s.state) {
+        case "no_key":
+            return s.hint ?? "No KATMAN_KEY is set in this MCP server's configuration.";
+        case "invalid":
+            return s.source === "local" ? s.hint ?? "KATMAN_KEY doesn't look like a Katman key." : `katman.pro doesn't recognise this KATMAN_KEY (${s.keyHint ?? "km_…"}).`;
+        case "revoked":
+            return `This KATMAN_KEY (${s.keyHint ?? "km_…"}) was revoked on katman.pro.`;
+        case "unreachable":
+            return `Katman couldn't reach katman.pro to check KATMAN_KEY (${s.error ?? "network error"})${s.checkedAt ? `, and the last successful check (${day(s.checkedAt)}) is more than 7 days old` : ""}.`;
+        case "valid":
+            if (s.plan === "free")
+                return s.trialEnded ? `The ${TRIAL_DAYS}-day trial on this account ended on ${day(s.trialEndsAt)}.` : "This account is on the free plan (no active trial or Katman Pro subscription).";
+            return `Your ${s.plan} plan doesn't include "${feature ?? "this feature"}" according to katman.pro.`;
+    }
+}
+/** One line for katman_start / katman_account. */
+export function statusLine(s, now = new Date()) {
+    switch (s.state) {
+        case "no_key":
+            return s.hint ? `**Katman plan:** free · ${s.hint}` : `**Katman plan:** free (no KATMAN_KEY) · Pro tools: ${TRIAL_DAYS}-day free trial at ${APP_URL}`;
+        case "invalid":
+            return `**Katman plan:** free · KATMAN_KEY ${s.source === "local" ? "doesn't look like a Katman key" : "isn't recognised by katman.pro"} · get a key at ${KEYS_URL}`;
+        case "revoked":
+            return `**Katman plan:** free · this KATMAN_KEY was revoked · create a new one at ${KEYS_URL}`;
+        case "unreachable":
+            return `**Katman plan:** not verified · couldn't reach katman.pro to check KATMAN_KEY (${s.error ?? "network error"}) · Pro tools are off until a check succeeds`;
+        case "valid": {
+            const who = s.emailMasked ? ` · ${s.emailMasked}` : "";
+            if (s.plan === "pro")
+                return `**Katman plan:** Pro · all Pro tools on${who}${offlineText(s)}`;
+            if (s.plan === "trial") {
+                const left = trialDaysLeft(s, now);
+                return `**Katman plan:** trial · ${left === undefined ? "" : `${left} day${left === 1 ? "" : "s"} left (until ${day(s.trialEndsAt)}) · `}all Pro tools on${who}${offlineText(s)}`;
+            }
+            return `**Katman plan:** free${s.trialEnded ? ` (trial ended ${day(s.trialEndsAt)})` : ""} · Pro tools are off: upgrade at ${BILLING_URL}${who}`;
+        }
+    }
+}
+/** katman_start: the next step is a Pro tool and the license doesn't cover it. */
+export function proNotice(tool, s) {
+    let why;
+    let action;
+    switch (s.state) {
+        case "no_key":
+            why = "this Katman server has no KATMAN_KEY";
+            action = `Start the ${TRIAL_DAYS}-day free trial (no card): ${APP_URL} → create a key → add it to the MCP config as KATMAN_KEY (katman_account shows the exact snippet for each editor)`;
+            break;
+        case "invalid":
+        case "revoked":
+            why = `KATMAN_KEY was ${s.state === "revoked" ? "revoked" : "not accepted"}`;
+            action = `Create a new key at ${KEYS_URL} and replace KATMAN_KEY in the MCP config`;
+            break;
+        case "unreachable":
+            why = "katman.pro couldn't be reached to check KATMAN_KEY";
+            action = "Check the internet connection, then call katman_account with refresh: true";
+            break;
+        case "valid":
+            why = s.plan === "free" ? (s.trialEnded ? "the trial on this account has ended" : "this account is on the free plan") : "this plan doesn't include it";
+            action = `Upgrade at ${BILLING_URL} (${PRO_PRICE_NOTE}), then call katman_account with refresh: true`;
+            break;
+    }
+    return `> **Needs Katman Pro:** \`${tool}\` is a Katman Pro tool and ${why}. ${action}. Tell the user; the free diagnosis (katman_research, katman_scan_code, katman_audit_site, katman_keywords) keeps working.`;
+}
+// ---------------------------------------------------------------------------------------------------------------
+// Snippets
+export function installSnippets() {
+    return [
+        "**Claude Code**",
+        "```bash",
+        "claude mcp remove katman --scope user   # only if Katman is already added",
+        "claude mcp add katman --scope user -e KATMAN_KEY=km_live_… -e OPENROUTER_API_KEY=sk-or-… -- npx -y katman-mcp",
+        "```",
+        "OPENROUTER_API_KEY is optional (only for API visibility runs). With the Katman Claude Code plugin, set its `katman_key` option instead.",
+        "",
+        "**Cursor**: in `~/.cursor/mcp.json` (your user file, not a committed project file); keep any other env entries you have:",
+        "```json",
+        '{ "mcpServers": { "katman": { "command": "npx", "args": ["-y", "katman-mcp"], "env": { "KATMAN_KEY": "km_live_…" } } } }',
+        "```",
+        "",
+        "**VS Code**: in `.vscode/mcp.json`; VS Code asks for the key once and keeps it in its secret storage:",
+        "```json",
+        "{",
+        '  "inputs": [{ "type": "promptString", "id": "katman_key", "description": "Katman key (katman.pro/app)", "password": true }],',
+        '  "servers": { "katman": { "type": "stdio", "command": "npx", "args": ["-y", "katman-mcp"], "env": { "KATMAN_KEY": "${input:katman_key}" } } }',
+        "}",
+        "```",
+    ].join("\n");
+}
+const RESTART = "Restart the Katman MCP server (or reload the editor window) so it reads the key, then call katman_account to confirm.";
+/** What to do next, by license state. */
+export function howToText(s, rerun) {
+    const again = rerun ? ` and run ${rerun} again` : "";
+    switch (s.state) {
+        case "no_key":
+            return [
+                `### Start the ${TRIAL_DAYS}-day free trial (no card)`,
+                `1. Open ${APP_URL}, sign in with your email, then **MCP → Create key** and copy the key (km_live_…; it's shown once).`,
+                "2. Add it to the MCP config as `KATMAN_KEY`:",
+                "",
+                installSnippets(),
+                "",
+                `3. ${RESTART.replace(/\.$/, "")}${again}.`,
+                "",
+                `After the trial: Katman Pro, ${PRO_PRICE_NOTE}.`,
+            ].join("\n");
+        case "invalid":
+        case "revoked":
+            return [
+                "### Use a valid key",
+                `1. Open ${KEYS_URL}. ${s.state === "revoked" ? "Create a new key" : "Copy the key again (the whole km_live_… string, no quotes or spaces), or create a new one if you no longer have it"}.`,
+                "2. Replace `KATMAN_KEY` in the MCP config:",
+                "",
+                installSnippets(),
+                "",
+                `3. ${RESTART.replace(/\.$/, "")}${again}.`,
+            ].join("\n");
+        case "unreachable":
+            return [
+                "### Check the connection",
+                "Pro tools keep working offline for 7 days after a successful check with katman.pro. Make sure katman.pro is reachable from this machine (internet connection, proxy or firewall" +
+                    `${/KATMAN_API_URL/.test(s.error ?? "") ? ", KATMAN_API_URL" : ""}), then call katman_account with refresh: true${again}.`,
+            ].join("\n");
+        case "valid":
+            if (s.plan === "free") {
+                return [
+                    "### Upgrade to Katman Pro",
+                    `Katman Pro is ${PRO_PRICE_NOTE}: ${BILLING_URL}. The key stays the same.`,
+                    `Already upgraded? Call katman_account with refresh: true${again}.`,
+                ].join("\n");
+            }
+            return [
+                "### Update Katman",
+                `Run the latest version (npx -y katman-mcp@latest), call katman_account with refresh: true${again}. If it persists, write to hello@katman.pro.`,
+            ].join("\n");
+    }
+}
+export function renderUpsell(o) {
+    if (o.surface === "cli")
+        return renderCliUpsell(o);
+    const where = o.facts?.brand ?? o.facts?.domain;
+    return [
+        `## ${o.tool} is part of Katman Pro`,
+        `**What it would do${where ? ` for ${where}` : ""}:** ${pitch(o.tool, o.args ?? {}, o.facts).replace(/^./, (c) => c.toUpperCase())}`,
+        freeDoneText(o.facts),
+        `**Why it didn't run:** ${reasonText(o.status, o.feature)}`,
+        howToText(o.status, o.tool),
+        `Tell the user this in your own words. Don't try to work around it; the free tools (${FREE_LIST}) keep working.`,
+    ].join("\n\n");
+}
+function renderCliUpsell(o) {
+    const cmd = o.command ?? o.tool;
+    const L = [
+        `${cmd} is part of Katman Pro: it would ${pitch(o.tool, o.args ?? {}, o.facts)}`,
+        `Why it didn't run: ${reasonText(o.status, o.feature)}`,
+        "",
+    ];
+    if (o.status.state === "valid" && o.status.plan === "free") {
+        L.push(`Upgrade: ${BILLING_URL} (${PRO_PRICE_NOTE}); the key stays the same. Already upgraded? Run: katman-mcp account --refresh`);
+    }
+    else if (o.status.state === "unreachable") {
+        L.push("Pro commands keep working offline for 7 days after a successful check. Make sure katman.pro is reachable, then run: katman-mcp account --refresh");
+    }
+    else {
+        L.push(`1. ${o.status.state === "no_key" ? `Start the ${TRIAL_DAYS}-day free trial (no card): ${APP_URL} → MCP → Create key` : `Get a valid key: ${KEYS_URL}`}`, "2. Run with the key in the environment:", `     KATMAN_KEY=km_live_… npx -y ${cmd} --root .`, "   GitHub Actions: add the repository secret KATMAN_KEY (gh secret set KATMAN_KEY) and pass it as env.");
+        if (o.status.state === "no_key")
+            L.push(`After the trial: Katman Pro, ${PRO_PRICE_NOTE}.`);
+    }
+    L.push("", "Free without a key: katman-mcp scan, audit, keywords, models, indexnow (dry run), account.");
+    return L.join("\n");
+}
+/** structuredContent of an upsell (no secrets). */
+export function upsellStructured(tool, feature, s) {
+    return {
+        licensed: false,
+        tool,
+        feature,
+        license: { state: s.state, plan: s.plan, ...(s.trialEnded ? { trialEnded: true, trialEndsAt: s.trialEndsAt } : {}) },
+        trialUrl: APP_URL,
+        keysUrl: KEYS_URL,
+        upgradeUrl: BILLING_URL,
+    };
+}
+export { when as fmtWhen, day as fmtDay };