katman-mcp 0.1.0 → 0.3.0

package/dist/tools/account/upsell.js

@@ -1,13 +1,25 @@
-// 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).
+// Katman plan texts: what a tool returns without the plan it needs (MCP and CLI), katman_start without a plan, the
+// one-line plan status, the notice katman_start adds when the next tool isn't in the plan, the paywall of a gated
+// resource and the MCP config snippets with KATMAN_KEY.
+// Only type imports from license.ts (license.ts imports this module); the plans come from plans.ts.
 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 { AUDIT_COUNT_NOTE, AUDIT_COUNT_NOTE_TR, BILLING_URL, BUY_PRO_1_URL, BUY_PRO_3_URL, KEYS_URL, KEY_DOCS_URL, PRICING_URL, PRO_3_NOTE, PRO_PRICE_NOTE, PRO_PRICE_NOTE_TR, VERSION, } from "../../meta.js";
+import { isProOnly } from "../../plans.js";
 import { listFiles } from "../../state.js";
-import { domainOf, sortFindings, truncate } from "../../util.js";
+import { domainOf, mdTable, sortFindings, truncate } from "../../util.js";
+import { GATES, STEPS } from "../method/data/method.js";
+import { t } from "../method/lib/l10n.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";
+/** Without a key: the two plans, where to get a key and where it goes. */
+export const NO_KEY_TEXT = `Katman needs a licence key (KATMAN_KEY). ${PRO_PRICE_NOTE}: audit, research, plan and AI-visibility checks, the P0–P14 prompts, page briefs and file generation. Get a key at ${PRICING_URL}, then add KATMAN_KEY to your MCP config (${KEY_DOCS_URL}).`;
+/** For an account that bought an Audit Week earlier (no longer sold): what it covers and the way up. */
+const AUDIT_COVERS = `Your Audit Week covers audit and recommendations; Pro builds the pages. Upgrade: ${BILLING_URL}`;
+/** An Audit Week (bought earlier) calling a Pro-only tool or command. */
+function proToolText(name, kind) {
+    return `${name} is a Katman Pro ${kind}. ${AUDIT_COVERS}`;
+}
+const upperFirst = (x) => x.replace(/^./, (c) => c.toUpperCase());
 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())
@@ -45,21 +57,33 @@ 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) {
+/** "the code scan (…) and the live audit (…)", or "" when neither exists yet. */
+function foundParts(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 ")}` : "";
+    return parts.join(" and ");
 }
-/** One sentence: what this Pro tool would do for this project. */
+/** One sentence: what this 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);
+    const found = foundParts(f);
     switch (tool) {
+        case "katman_start":
+            return `show where ${brand} stands in the Katman method (research, scan, audit, plan, measurements) and the exact next tool call.`;
+        case "katman_research":
+            return `build ${brand}'s research: the one sentence in 4 parts, the not-X note, 10–12 customer situations in the customers' own words, competitors with sources, proof and the 12 + 2 question set.`;
+        case "katman_scan_code":
+            return `scan ${f?.framework ? `this ${f.framework} project` : "this project"}'s code: whether pages render on the server or only in JavaScript, public vs app routes, robots/sitemap/llms.txt, head tags, JSON-LD and links, each finding with its gate and fix.`;
+        case "katman_audit_site":
+            return `audit ${str("site_url") ?? f?.domain ?? "the live site"} the way AI crawlers see it: robots.txt and CDN/firewall blocks for GPTBot, ClaudeBot and PerplexityBot, text with JavaScript off, soft 404s, canonicals, sitemap, JSON-LD and internal links, with the top 10 issues ranked.`;
+        case "katman_keywords":
+            return `expand ${str("seed") ? `“${str("seed")}”` : "a seed phrase"} with Google autocomplete into the phrases customers really type, grouped into situation, single-question and comparison page ideas.`;
         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.`;
+            return `turn what Katman found${found ? ` in ${found}` : ""} 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":
@@ -81,92 +105,162 @@ export function pitch(tool, args, f) {
         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.";
+            return "run this step of the Katman 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.`;
+/** What .katman/ already holds from an earlier plan, so the pitch can build on it. */
+function doneText(f) {
+    const found = foundParts(f);
+    if (!found)
+        return undefined;
+    const top = f.topIssues.length ? ` Top issues: ${f.topIssues.map((x) => `“${x}”`).join("; ")}.` : "";
+    return `**Already in .katman/:** ${found}.${top}`;
 }
 // ---------------------------------------------------------------------------------------------------------------
 // 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)
+/** "Katman Pro, 1 site" / "Katman Pro, 3 sites" from the plan's limits; "Katman Pro" when there are none (older plans). */
+export function proPlanName(limits) {
+    if (limits?.sites === 1 && limits.auditsPerMonth === 5)
+        return "Katman Pro, 1 site";
+    if (limits?.sites === 3 && limits.auditsPerMonth === 30)
+        return "Katman Pro, 3 sites";
+    return "Katman Pro";
+}
+const countOf = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+/** "3 of 5 audits, 1 of 1 site used this month (counts start again 2026-11-01)"; without counts: "5 audits and 1 site a month". */
+export function usageText(limits, usage) {
+    if (!usage)
+        return `${countOf(limits.auditsPerMonth, "audit", "audits")} and ${countOf(limits.sites, "site", "sites")} a month`;
+    return `${usage.audits} of ${countOf(limits.auditsPerMonth, "audit", "audits")}, ${usage.sites} of ${countOf(limits.sites, "site", "sites")} used this month (counts start again ${day(usage.resetsAt)})`;
+}
+/** The update notice for a katman-mcp too old to be counted (katman.pro's updateMcpTo). */
+function updateText(s) {
+    return `This katman-mcp (${VERSION}) can't count audits against your plan, so the audit is off until you update to ${s.updateMcpTo} or newer: run npx -y katman-mcp@latest, restart the MCP server (or reload the editor window), then call katman_account with refresh: true.`;
+}
+/** Days left in a running Audit Week (7 right after it starts, 1 on its last day). */
+export function planDaysLeft(s, now = new Date()) {
+    if (s.plan !== "audit" || !s.planEndsAt)
         return undefined;
-    return Math.max(0, Math.ceil((Date.parse(s.trialEndsAt) - now.getTime()) / 86_400_000));
+    return Math.max(0, Math.ceil((Date.parse(s.planEndsAt) - 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) {
+/** "Audit Week ended 2026-10-01" (for a table cell or a status line). */
+export function endedPhrase(s) {
+    const what = s.endedPlan === "pro" ? "Katman Pro ended" : s.endedPlan === "audit" ? "Audit Week ended" : "plan ended";
+    return `${what}${s.planEndsAt ? ` ${day(s.planEndsAt)}` : ""}`;
+}
+/** "Your Audit Week ended on 2026-10-01." */
+function endedText(s, lang = "en") {
+    const on = s.planEndsAt ? day(s.planEndsAt) : undefined;
+    if (lang === "tr") {
+        const what = s.endedPlan === "pro" ? "Katman Pro aboneliğiniz" : s.endedPlan === "audit" ? "Denetim Haftanız" : "Planınız";
+        return `${what} ${on ? `${on} tarihinde ` : ""}bitti.`;
+    }
+    const what = s.endedPlan === "pro" ? "Your Katman Pro subscription" : s.endedPlan === "audit" ? "Your Audit Week" : "Your Katman plan";
+    return `${what} ${on ? `ended on ${on}` : "has ended"}.`;
+}
+/** The only way on after an Audit Week (each account gets one), or after Pro ended. */
+const onlyPro = (s) => !!s.planEnded || !!s.auditWeekUsed;
+/** Why a tool didn't run (one or two sentences). `name` is the tool, or the CLI command. */
+export function reasonText(s, o = {}) {
+    const tr = o.lang === "tr";
     switch (s.state) {
         case "no_key":
-            return s.hint ?? "No KATMAN_KEY is set in this MCP server's configuration.";
+            if (s.hint)
+                return s.hint;
+            if (tr)
+                return "Bu MCP sunucusunun yapılandırmasında KATMAN_KEY yok.";
+            return o.surface === "cli" ? "No KATMAN_KEY is set in the environment." : "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_…"}).`;
+            if (s.source === "local") {
+                return tr
+                    ? "KATMAN_KEY bir Katman anahtarına benzemiyor: anahtarlar km_live_ ile başlar, ardından harfler ve rakamlar gelir (tırnak, boşluk ya da satır sonu olmadan). Hiçbir yere gönderilmedi."
+                    : s.hint ?? "KATMAN_KEY doesn't look like a Katman key.";
+            }
+            return tr ? `katman.pro bu KATMAN_KEY’i tanımıyor (${s.keyHint ?? "km_…"}).` : `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.`;
+            return tr ? `Bu KATMAN_KEY (${s.keyHint ?? "km_…"}) katman.pro’da iptal edilmiş.` : `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` : ""}.`;
+            return tr
+                ? `Katman, KATMAN_KEY’i kontrol etmek için katman.pro’ya ulaşamadı (${s.error ?? "ağ hatası"})${s.checkedAt ? `; son başarılı kontrol (${day(s.checkedAt)}) 7 günden eski` : ""}.`
+                : `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.`;
+            if (s.plan === "none") {
+                if (s.planEnded)
+                    return endedText(s, o.lang);
+                if (s.auditWeekUsed)
+                    return tr ? "Bu hesabın etkin bir planı yok: tek Denetim Haftası kullanıldı." : "This account has no active plan: its one Audit Week has been used.";
+                return tr ? "Bu hesabın henüz etkin bir Katman Pro planı yok." : "This account has no active Katman Pro plan yet.";
+            }
+            if (s.plan === "audit" && o.feature && isProOnly(o.feature))
+                return proToolText(o.name ?? "This tool", o.surface === "cli" ? "command" : "tool");
+            if (s.updateMcpTo) {
+                return tr
+                    ? `Bu katman-mcp (${VERSION}) planınızdaki denetimleri sayamıyor; ${s.updateMcpTo} ya da daha yeni bir sürüme güncelleyene kadar denetim kapalı: npx -y katman-mcp@latest çalıştırın, MCP sunucusunu yeniden başlatın, sonra katman_account aracını refresh: true ile çağırın.`
+                    : updateText(s);
+            }
+            return tr
+                ? `Planınız katman.pro’ya göre “${o.feature ?? "bu özellik"}” özelliğini içermiyor.`
+                : `Your ${s.plan === "pro" ? "Katman Pro" : "Audit Week"} plan doesn't include "${o.feature ?? "this feature"}" according to katman.pro.`;
     }
 }
-/** One line for katman_start / katman_account. */
+/** One line for katman_start. */
 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}`;
+            return s.hint ? `**Katman plan:** none · ${s.hint}` : `**Katman plan:** none (no KATMAN_KEY) · get a key at ${PRICING_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}`;
+            return `**Katman plan:** none · 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}`;
+            return `**Katman plan:** none · 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`;
+            return `**Katman plan:** not verified · couldn't reach katman.pro to check KATMAN_KEY (${s.error ?? "network error"}) · Katman's 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)}`;
+            if (s.plan === "pro") {
+                const used = s.limits ? ` · ${usageText(s.limits, s.usage)}` : "";
+                const update = s.updateMcpTo ? ` · update katman-mcp to ${s.updateMcpTo} (npx -y katman-mcp@latest): audits are off until then` : "";
+                return `**Katman plan:** ${proPlanName(s.limits)} · every tool on${used}${update}${who}${offlineText(s)}`;
             }
-            return `**Katman plan:** free${s.trialEnded ? ` (trial ended ${day(s.trialEndsAt)})` : ""} · Pro tools are off: upgrade at ${BILLING_URL}${who}`;
+            if (s.plan === "audit") {
+                const left = planDaysLeft(s, now);
+                return `**Katman plan:** Audit Week · ${left === undefined ? "" : `${left} day${left === 1 ? "" : "s"} left (until ${day(s.planEndsAt)}) · `}audit and recommendation tools on; the page-building tools need Katman Pro (${BILLING_URL})${who}${offlineText(s)}`;
+            }
+            const note = s.planEnded ? ` (${endedPhrase(s)})` : s.auditWeekUsed ? " (Audit Week used)" : "";
+            const next = s.endedPlan === "pro" ? "renew Katman Pro" : onlyPro(s) ? "upgrade to Katman Pro" : "choose Katman Pro (1 site $49/month, 3 sites $88/month)";
+            return `**Katman plan:** none${note} · ${next} 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;
+/** One line: what to do next, by license state (resources, notices). */
+function nextStepLine(s, feature) {
     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;
+            return `Get a key at ${PRICING_URL}, then add KATMAN_KEY to the MCP config (${KEY_DOCS_URL}).`;
         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;
+            return `Create a new key at ${KEYS_URL} and replace KATMAN_KEY in the MCP config.`;
         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;
+            return "Check the internet connection, then call katman_account with refresh: true.";
         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;
+            if (s.plan === "none") {
+                return `${s.endedPlan === "pro" ? "Renew" : onlyPro(s) ? "Upgrade to" : "Choose"} Katman Pro at ${BILLING_URL}: ${PRO_PRICE_NOTE}. Then call katman_account with refresh: true.`;
+            }
+            if (s.updateMcpTo)
+                return "Run the latest katman-mcp (npx -y katman-mcp@latest), restart the MCP server, then call katman_account with refresh: true.";
+            return "Call katman_account with refresh: true; if it persists, run the latest Katman (npx -y katman-mcp@latest).";
+    }
+}
+/** katman_start: the recommended next tool isn't in the plan. */
+export function planNotice(tool, feature, s) {
+    if (s.state === "valid" && s.plan === "audit" && isProOnly(feature)) {
+        return `> **Needs Katman Pro:** ${proToolText(`\`${tool}\``, "tool")}\n> ${PRO_PRICE_NOTE}. The key stays the same. After upgrading, call katman_account with refresh: true. Tell the user; the Audit Week tools keep working${s.planEndsAt ? ` until ${day(s.planEndsAt)}` : ""}.`;
     }
-    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.`;
+    return `> **Not in your plan:** \`${tool}\` won't run: ${reasonText(s, { feature, name: tool })} ${nextStepLine(s, feature)} Tell the user.`;
 }
 // ---------------------------------------------------------------------------------------------------------------
 // Snippets
@@ -177,7 +271,7 @@ export function installSnippets() {
         "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.",
+        "OPENROUTER_API_KEY is optional (only for API visibility runs). With the Katman Claude Code plugin, set its `katman_key` option instead (`/plugin configure katman@katman`).",
         "",
         "**Cursor**: in `~/.cursor/mcp.json` (your user file, not a committed project file); keep any other env entries you have:",
         "```json",
@@ -187,104 +281,315 @@ export function installSnippets() {
         "**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 }],',
+        '  "inputs": [{ "type": "promptString", "id": "katman_key", "description": "Katman key (katman.pro/app/mcp)", "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` : "";
+/** What to do next, by license state. `rerun` is the tool to call again afterwards. */
+export function howToText(s, o = {}) {
+    const tr = o.lang === "tr";
+    const again = o.rerun ? (tr ? `, sonra ${o.rerun} aracını yeniden çağırın` : ` and run ${o.rerun} again`) : "";
+    const restart = tr
+        ? `Anahtarı okuması için Katman MCP sunucusunu yeniden başlatın (ya da editör penceresini yeniden yükleyin), katman_account ile kontrol edin${again}.`
+        : `Restart the Katman MCP server (or reload the editor window) so it reads the key, then call katman_account to confirm${again}.`;
+    const refresh = tr ? `katman_account aracını refresh: true ile çağırın${again}.` : `call katman_account with refresh: true${again}.`;
+    const Refresh = upperFirst(refresh);
     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");
+            return (tr
+                ? [
+                    "### Anahtar alın",
+                    `1. ${PRICING_URL} adresinden bir plan seçin, sonra ${KEYS_URL} → **Anahtar oluştur** ile anahtarınızı oluşturup kopyalayın (km_live_…; yalnızca bir kez gösterilir).`,
+                    `2. Anahtarı MCP yapılandırmasına \`KATMAN_KEY\` olarak ekleyin (her editör için adım adım: ${KEY_DOCS_URL}):`,
+                ]
+                : [
+                    "### Get a key",
+                    `1. Choose a plan at ${PRICING_URL}, then open ${KEYS_URL} → **Create key** and copy the key (km_live_…; it's shown once).`,
+                    `2. Add it to the MCP config as \`KATMAN_KEY\` (step by step for each editor: ${KEY_DOCS_URL}):`,
+                ]).concat(["", installSnippets(), "", `3. ${restart}`]).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");
+            return (tr
+                ? [
+                    "### Geçerli bir anahtar kullanın",
+                    `1. ${KEYS_URL} adresini açın. ${s.state === "revoked" ? "Yeni bir anahtar oluşturun" : "Anahtarı yeniden kopyalayın (km_live_… dizesinin tamamı, tırnak ya da boşluk olmadan) ya da elinizde yoksa yeni bir tane oluşturun"}.`,
+                    "2. MCP yapılandırmasındaki `KATMAN_KEY` değerini değiştirin:",
+                ]
+                : [
+                    "### 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:",
+                ]).concat(["", installSnippets(), "", `3. ${restart}`]).join("\n");
+        case "unreachable": {
+            const api = /KATMAN_API_URL/.test(s.error ?? "") ? ", KATMAN_API_URL" : "";
+            return tr
+                ? `### Bağlantıyı kontrol edin\nKatman, katman.pro ile başarılı bir kontrolden sonra 7 gün çevrimdışı çalışır (bir Denetim Haftasının bitişini aşmadan). Bu bilgisayardan katman.pro’ya ulaşılabildiğinden emin olun (internet bağlantısı, proxy ya da güvenlik duvarı${api}), sonra ${refresh}`
+                : `### Check the connection\nKatman keeps working offline for 7 days after a successful check with katman.pro (never past the end of an Audit Week). Make sure katman.pro is reachable from this machine (internet connection, proxy or firewall${api}), then ${refresh}`;
+        }
         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");
+            if (s.plan === "none" && s.endedPlan === "pro") {
+                return tr
+                    ? `### Katman Pro’yu yenileyin\nAnahtarınız aynı kalır: ${BILLING_URL} adresinden yeniden abone olun (${PRO_PRICE_NOTE_TR}). Yeniden abone oldunuz mu? ${refresh}`
+                    : `### Renew Katman Pro\nThe key stays the same: resubscribe at ${BILLING_URL}. ${PRO_PRICE_NOTE}. Already renewed? ${Refresh}`;
+            }
+            if (s.plan === "none" && onlyPro(s)) {
+                return tr
+                    ? `### Katman Pro’ya geçin\n${PRO_PRICE_NOTE_TR}: ${BILLING_URL}. Anahtar aynı kalır. Geçtiniz mi? ${refresh}`
+                    : `### Upgrade to Katman Pro\n${PRO_PRICE_NOTE}. Upgrade at ${BILLING_URL}; the key stays the same. Already upgraded? ${Refresh}`;
             }
-            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");
+            if (s.plan === "none") {
+                return tr
+                    ? `### Bir plan seçin\n${plansList("tr")}\n\nSatın alma: ${BILLING_URL}; anahtar aynı kalır. Satın aldıktan sonra ${refresh}`
+                    : `### Choose a plan\n${plansList("en")}\n\nBuy at ${BILLING_URL}; the key stays the same. Then ${refresh}`;
+            }
+            if (s.plan === "audit" && o.feature && isProOnly(o.feature)) {
+                return `### Upgrade to Katman Pro\n${PRO_PRICE_NOTE}. Upgrade at ${BILLING_URL}; the key stays the same. Your Audit Week tools keep working${s.planEndsAt ? ` until ${day(s.planEndsAt)}` : ""}. Already upgraded? ${Refresh}`;
+            }
+            if (s.updateMcpTo) {
+                return tr
+                    ? `### Katman’ı güncelleyin\nBu sürüm planınızdaki denetimleri sayamıyor. En son sürümü çalıştırın (npx -y katman-mcp@latest), MCP sunucusunu yeniden başlatın ve ${refresh}`
+                    : `### Update Katman\nThis version can't count audits against your plan. Run the latest version (npx -y katman-mcp@latest), restart the MCP server (or reload the editor window), then ${refresh}`;
+            }
+            return tr
+                ? `### Katman’ı güncelleyin\nEn son sürümü çalıştırın (npx -y katman-mcp@latest) ve ${refresh} Sorun sürerse hello@katman.pro adresine yazın.`
+                : `### Update Katman\nRun the latest version (npx -y katman-mcp@latest) and ${refresh} If it persists, write to hello@katman.pro.`;
+    }
+}
+/** The two plans as a short list. */
+function plansList(lang) {
+    return lang === "tr"
+        ? [
+            "- **Katman Pro, 1 site**: ayda 49 $. 1 site, ayda 5 denetim. Tüm araçlar: P0–P14 prompt’ları, sayfa brief’leri ve dosya üretimi dâhil.",
+            "- **Katman Pro, 3 site**: ayda 88 $. 3 site, ayda 30 denetim. Tüm araçlar, 1 siteli plandakiyle aynı.",
+            "",
+            AUDIT_COUNT_NOTE_TR,
+        ].join("\n")
+        : [
+            "- **Katman Pro, 1 site**: $49/month. 1 site, 5 audits a month. Every tool, including the P0–P14 prompts, page briefs and file generation.",
+            "- **Katman Pro, 3 sites**: $88/month. 3 sites, 30 audits a month. Every tool, the same as the 1-site plan.",
+            "",
+            AUDIT_COUNT_NOTE,
+        ].join("\n");
+}
+/** The two plans as a table (katman_start without a plan). */
+function plansTable(lang) {
+    return lang === "tr"
+        ? mdTable(["Plan", "Fiyat", "Kapsadığı"], [
+            ["**Katman Pro, 1 site**", "Ayda 49 $", "1 site, ayda 5 denetim. Tüm araçlar: P0–P14 prompt’ları, sayfa brief’leri, dosya üretimi (robots.txt, llms.txt, JSON-LD), IndexNow, zamanlanmış izleme ve katman.pro paneli dâhil."],
+            ["**Katman Pro, 3 site**", "Ayda 88 $", "3 site, ayda 30 denetim. Tüm araçlar, 1 siteli plandakiyle aynı."],
+        ])
+        : mdTable(["Plan", "Price", "What it covers"], [
+            ["**Katman Pro, 1 site**", "$49/month", "1 site, 5 audits a month. Every tool, including the P0–P14 prompts, page briefs, file generation (robots.txt, llms.txt, JSON-LD), IndexNow, scheduled monitoring and the katman.pro dashboard."],
+            ["**Katman Pro, 3 sites**", "$88/month", "3 sites, 30 audits a month. Every tool, the same as the 1-site plan."],
+        ]);
+}
+function headline(name, feature, s) {
+    switch (s.state) {
+        case "no_key":
+            return `${name} needs a Katman licence key`;
+        case "invalid":
+        case "revoked":
+            return `${name} needs a valid Katman key`;
+        case "unreachable":
+            return `${name} couldn't check the Katman licence`;
+        case "valid":
+            if (s.plan === "none")
+                return `${name} needs an active Katman plan`;
+            return s.plan === "audit" && isProOnly(feature) ? `${name} needs Katman Pro` : `${name} isn't in your Katman plan`;
     }
 }
 export function renderUpsell(o) {
     if (o.surface === "cli")
         return renderCliUpsell(o);
     const where = o.facts?.brand ?? o.facts?.domain;
+    const done = doneText(o.facts);
     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.`,
+        `## ${headline(o.tool, o.feature, o.status)}`,
+        `**What it would do${where ? ` for ${where}` : ""}:** ${upperFirst(pitch(o.tool, o.args ?? {}, o.facts))}`,
+        ...(done ? [done] : []),
+        `**Why it didn't run:** ${reasonText(o.status, { feature: o.feature, name: o.tool })}`,
+        ...(o.status.state === "no_key" ? [NO_KEY_TEXT] : []),
+        howToText(o.status, { rerun: o.tool, feature: o.feature }),
+        "Tell the user this in your own words. Don't try to work around it (no editing Katman's code or cache, no made-up keys); katman_account always works.",
     ].join("\n\n");
 }
 function renderCliUpsell(o) {
     const cmd = o.command ?? o.tool;
+    const s = o.status;
     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)}`,
+        `${headline(cmd, o.feature, s)}: it would ${pitch(o.tool, o.args ?? {}, o.facts)}`,
+        `Why it didn't run: ${reasonText(s, { feature: o.feature, name: cmd, surface: "cli" })}`,
         "",
     ];
-    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`);
+    if (s.state === "valid") {
+        if (s.plan === "audit" && isProOnly(o.feature)) {
+            L.push(`Upgrade to Katman Pro at ${BILLING_URL}: ${PRO_PRICE_NOTE}. The key stays the same. Already upgraded? Run: katman-mcp account --refresh`);
+        }
+        else if (s.plan === "none" && s.endedPlan === "pro") {
+            L.push(`Renew Katman Pro at ${BILLING_URL}: ${PRO_PRICE_NOTE}. The key stays the same. Already renewed? Run: katman-mcp account --refresh`);
+        }
+        else if (s.plan === "none") {
+            L.push(`${onlyPro(s) ? "Upgrade to" : "Choose"} Katman Pro at ${BILLING_URL}: ${PRO_PRICE_NOTE}. The key stays the same. Already ${onlyPro(s) ? "upgraded" : "bought"}? Run: katman-mcp account --refresh`);
+        }
+        else {
+            L.push("Run the latest version (npx -y katman-mcp@latest), then: katman-mcp account --refresh. If it persists, write to hello@katman.pro.");
+        }
     }
-    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 if (s.state === "unreachable") {
+        L.push("Katman keeps working offline for 7 days after a successful check (never past the end of an Audit Week). 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}.`);
+        if (s.state === "no_key")
+            L.push(NO_KEY_TEXT, "");
+        L.push(`1. ${s.state === "no_key" ? `Get a key: ${PRICING_URL}, then ${KEYS_URL} → Create key` : `Get a valid key: ${KEYS_URL}`}`, "2. Run with the key in the environment:", `     KATMAN_KEY=km_live_… npx -y ${o.example ?? cmd}`, "   GitHub Actions: add the repository secret KATMAN_KEY (gh secret set KATMAN_KEY) and pass it as env.");
     }
-    L.push("", "Free without a key: katman-mcp scan, audit, keywords, models, indexnow (dry run), account.");
+    L.push("", "Without a key: katman-mcp account, --help and --version.");
     return L.join("\n");
 }
-/** structuredContent of an upsell (no secrets). */
+/** The two plans on sale, for structuredContent (no secrets). */
+const PLANS_STRUCTURED = [
+    { id: "pro_1", name: "Katman Pro, 1 site", price: "$49/month", sites: 1, auditsPerMonth: 5, url: BUY_PRO_1_URL },
+    { id: "pro_3", name: "Katman Pro, 3 sites", price: "$88/month", sites: 3, auditsPerMonth: 30, url: BUY_PRO_3_URL },
+];
+/** structuredContent of a tool that didn't run for lack of a plan (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,
+        /** The plan to buy: every tool is in both Katman Pro plans (the Audit Week is no longer sold). */
+        requiredPlan: "pro",
+        plans: PLANS_STRUCTURED,
+        license: {
+            state: s.state,
+            plan: s.plan,
+            ...(s.planEndsAt ? { planEndsAt: s.planEndsAt } : {}),
+            ...(s.planEnded ? { planEnded: true } : {}),
+            ...(s.auditWeekUsed ? { auditWeekUsed: true } : {}),
+        },
+        pricingUrl: PRICING_URL,
         keysUrl: KEYS_URL,
         upgradeUrl: BILLING_URL,
+        docsUrl: KEY_DOCS_URL,
+    };
+}
+// ---------------------------------------------------------------------------------------------------------------
+// katman_start without a plan, gated resources
+/** katman_start without a plan: what Katman does, the two plans and how to set the key. No method walk-through. */
+export function startIntro(s, lang = "en") {
+    const L = (en, tr) => (lang === "tr" ? tr : en);
+    const gates = GATES.map((g) => `- **${t(g.name, lang)}**: ${t(g.summary, lang)}`).join("\n");
+    const steps = STEPS.map((x) => `${x.n} ${t(x.name, lang)}`).join(" → ");
+    const heading = s.state === "no_key"
+        ? L("Katman needs a licence key", "Katman bir lisans anahtarı ister")
+        : s.state === "invalid" || s.state === "revoked"
+            ? L("Katman needs a valid key", "Katman geçerli bir anahtar ister")
+            : s.state === "unreachable"
+                ? L("Katman couldn't check your licence", "Katman lisansınızı kontrol edemedi")
+                : L("Katman needs an active plan", "Katman etkin bir plan ister");
+    const why = s.state === "no_key" && !s.hint ? undefined : reasonText(s, { feature: "start", name: "katman_start", lang });
+    return [
+        "# Katman",
+        L("Katman makes your public website readable, quotable and recommendable by AI assistants (ChatGPT, Claude, Gemini, Perplexity, Copilot) and findable in Google, Bing and Brave. It reads your code and your live site the way AI crawlers do, tells your coding agent what to fix and which pages to write, and checks that it was done.", "Katman, herkese açık web sitenizi yapay zekâ asistanlarının (ChatGPT, Claude, Gemini, Perplexity, Copilot) okuyabileceği, alıntılayabileceği ve önerebileceği hâle getirir; Google, Bing ve Brave’de de bulunur kılar. Kodunuzu ve yayındaki sitenizi yapay zekâ tarayıcılarının gördüğü gibi okur, kod aracınıza neyi düzelteceğini ve hangi sayfaları yazacağını söyler, yapılıp yapılmadığını kontrol eder."),
+        `${L("**3 gates** every public page must pass:", "Her herkese açık sayfanın geçmesi gereken **3 kapı**:")}\n${gates}`,
+        L(`**4 steps:** ${steps}, then re-measure every 14 days.`, `**4 adım:** ${steps}; sonra 14 günde bir yeniden ölçüm.`),
+        `## ${heading}`,
+        ...(why ? [`**${L("Why nothing ran", "Neden çalışmadı")}:** ${why}`] : []),
+        ...(s.state === "unreachable" ? [] : [plansTable(lang), lang === "tr" ? AUDIT_COUNT_NOTE_TR : AUDIT_COUNT_NOTE]),
+        howToText(s, { rerun: "katman_start", feature: "start", lang }),
+        "Tell the user this in your own words, then stop: nothing else in Katman runs until KATMAN_KEY has an active plan. katman_account shows the plan at any time.",
+    ].join("\n\n");
+}
+/** A gated resource without the plan: its title, why, and what to do. */
+export function resourcePaywall(title, feature, s, then) {
+    const why = s.state === "no_key" && !s.hint
+        ? NO_KEY_TEXT
+        : s.state === "valid" && s.plan === "audit" && isProOnly(feature)
+            ? `This is part of Katman Pro. ${AUDIT_COVERS}`
+            : `${reasonText(s, { feature })} ${nextStepLine(s, feature)}`;
+    return `# ${title}\n\n${why}\n\n${then}`;
+}
+/** The status the no-plan / rejected-key answer of the audit check stands for, so the usual upsell can explain it. */
+function refusedStatus(o) {
+    const { use, status } = o;
+    if (use.reason === "invalid_key" || use.reason === "revoked") {
+        return { state: use.reason === "revoked" ? "revoked" : "invalid", plan: "none", features: [], source: "network", ...(status.keyHint ? { keyHint: status.keyHint } : {}) };
+    }
+    return { ...status, state: "valid", plan: "none", features: [] };
+}
+const onePro = (l) => l?.auditsPerMonth === 5;
+/** Why this month's allowance doesn't cover the audit (audit_limit / site_limit): one text for the MCP tool and the CLI. */
+function limitLines(o) {
+    const { use, domain } = o;
+    const lim = use.limits ?? undefined;
+    const usage = use.usage;
+    const resets = usage ? `Counts start again on ${day(usage.resetsAt)}.` : "Counts start again on the 1st of next month (UTC).";
+    const plan = proPlanName(lim);
+    const lines = [];
+    if (use.reason === "audit_limit") {
+        lines.push(lim
+            ? `All ${lim.auditsPerMonth} audits of this month are used (${plan}), so Katman didn't audit ${domain}. ${resets}`
+            : `This month's audits are used, so Katman didn't audit ${domain}. ${resets}`);
+    }
+    else {
+        const left = lim && usage ? Math.max(0, lim.auditsPerMonth - usage.audits) : undefined;
+        lines.push(lim
+            ? `${plan} covers ${countOf(lim.sites, "site", "sites")} a month and you already audited ${usage ? usage.sites : lim.sites} this month, so Katman didn't audit ${domain}, a new site. ${resets}`
+            : `This plan's sites for this month are used, so Katman didn't audit ${domain}. ${resets}`);
+        lines.push(`Audits of a site you already audited this month still work${left !== undefined ? ` (${countOf(left, "audit", "audits")} left)` : ""}.`);
+    }
+    if (onePro(lim))
+        lines.push(`To audit more now: upgrade to ${PRO_3_NOTE} at ${BUY_PRO_3_URL}; the key stays the same. Already upgraded? Call katman_account with refresh: true.`);
+    lines.push("Re-reading earlier results doesn't use an audit: the last audit of this project is in .katman/audit.md. Every other tool keeps working.");
+    return lines;
+}
+/** An audit that didn't run: this month's audits or sites are used up (explained), or the plan or key isn't valid (the usual upsell). */
+export function renderAuditRefusal(o) {
+    const { use } = o;
+    if (use.reason !== "audit_limit" && use.reason !== "site_limit") {
+        return renderUpsell({ tool: "katman_audit_site", feature: "audit", status: refusedStatus(o), facts: o.facts, args: { site_url: o.domain }, surface: o.surface, command: o.command, example: o.example });
+    }
+    const lines = limitLines(o);
+    if (o.surface === "cli") {
+        return [`${o.command ?? "katman-mcp audit"} didn't run: ${use.reason === "audit_limit" ? "this month's audits are used" : "this month's sites are used"}.`, "", ...lines, "", "This month's counts: katman-mcp account"].join("\n");
+    }
+    return [
+        `## katman_audit_site didn't run: ${use.reason === "audit_limit" ? "this month's audits are used" : "this month's sites are used"}`,
+        lines.join("\n\n"),
+        "Tell the user this in your own words. Don't try to work around it (no editing Katman's code or cache, no made-up keys); katman_account shows this month's counts.",
+    ].join("\n\n");
+}
+/** structuredContent of an audit that didn't run for lack of audits or sites this month (no secrets). */
+export function auditRefusalStructured(o) {
+    const { use } = o;
+    if (use.reason !== "audit_limit" && use.reason !== "site_limit")
+        return upsellStructured("katman_audit_site", "audit", refusedStatus(o));
+    return {
+        ran: false,
+        tool: "katman_audit_site",
+        reason: use.reason,
+        domain: o.domain,
+        ...(use.plan ? { plan: use.plan } : {}),
+        ...(use.limits ? { limits: use.limits } : {}),
+        ...(use.usage ? { usage: use.usage } : {}),
+        upgradeUrl: onePro(use.limits) ? BUY_PRO_3_URL : BILLING_URL,
+    };
+}
+/** After an audit that ran: this month's count on a plan with limits, or the note that the count couldn't be checked. */
+export function auditCountLine(use) {
+    if (use.unchecked)
+        return `> **Audit count not checked:** couldn't reach katman.pro (${use.error ?? "no answer"}), so this audit ran without being counted.`;
+    return use.limits ? `**${proPlanName(use.limits)}:** ${usageText(use.limits, use.usage)}.` : undefined;
+}
+/** structuredContent.auditCount of an audit that ran. */
+export function auditCountStructured(use) {
+    return {
+        counted: !use.unchecked,
+        ...(use.unchecked ? { error: use.error ?? "no answer" } : {}),
+        ...(use.limits ? { limits: use.limits } : {}),
+        ...(use.usage ? { usage: use.usage } : {}),
     };
 }
 export { when as fmtWhen, day as fmtDay };