katman-mcp 0.1.0 → 0.2.0

package/dist/tools/account/upsell.js

@@ -1,13 +1,24 @@
-// 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_PRICE_NOTE, BILLING_URL, KEYS_URL, KEY_DOCS_URL, PRICING_URL, PRO_PRICE_NOTE } 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). Audit Week — $3 for 7 days: audit, research, plan and AI-visibility checks; it doesn't build pages. Katman Pro — $29/month founding price ($290/year): everything, including 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}).`;
+const AUDIT_COVERS = `Your Audit Week covers audit and recommendations; Pro builds the pages. Upgrade: ${BILLING_URL}`;
+/** Audit Week 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 +56,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 +104,135 @@ 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)
+/** 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 planı yok (Denetim Haftası ya da Katman Pro)." : "This account has no active plan yet (no Audit Week or Katman Pro).";
+            }
+            if (s.plan === "audit" && o.feature && isProOnly(o.feature))
+                return proToolText(o.name ?? "This tool", o.surface === "cli" ? "command" : "tool");
+            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)}`;
+                return `**Katman plan:** Katman Pro · every tool on${who}${offlineText(s)}`;
+            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)}`;
             }
-            return `**Katman plan:** free${s.trialEnded ? ` (trial ended ${day(s.trialEndsAt)})` : ""} · Pro tools are off: upgrade at ${BILLING_URL}${who}`;
+            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" : "Audit Week ($3 for 7 days) or Katman Pro";
+            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 onlyPro(s) || (feature && isProOnly(feature))
+                    ? `${s.endedPlan === "pro" ? "Renew" : "Upgrade to"} Katman Pro at ${BILLING_URL}: ${PRO_PRICE_NOTE}. Then call katman_account with refresh: true.`
+                    : `Choose the Audit Week ($3 for 7 days) or Katman Pro at ${BILLING_URL}, 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).";
     }
-    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.`;
+}
+/** 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> Katman Pro: ${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 `> **Not in your plan:** \`${tool}\` won't run: ${reasonText(s, { feature, name: tool })} ${nextStepLine(s, feature)} Tell the user.`;
 }
 // ---------------------------------------------------------------------------------------------------------------
 // Snippets
@@ -177,7 +243,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 +253,226 @@ 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 (kurucu fiyatıyla ayda 29 $ ya da yılda 290 $). Yeniden abone oldunuz mu? ${refresh}`
+                    : `### Renew Katman Pro\nThe key stays the same: resubscribe at ${BILLING_URL}. Katman Pro: ${PRO_PRICE_NOTE}. Already renewed? ${Refresh}`;
+            }
+            if (s.plan === "none" && (onlyPro(s) || (o.feature && isProOnly(o.feature)))) {
+                const why = onlyPro(s)
+                    ? tr ? "Her hesabın tek bir Denetim Haftası var; devam etmek için Katman Pro" : "Each account gets one Audit Week, so Katman Pro is the way to continue"
+                    : tr ? "Bu araç Katman Pro’da; Denetim Haftası yalnızca denetim araçlarını kapsar" : "This tool is in Katman Pro; the Audit Week covers only the audit tools";
+                return tr
+                    ? `### Katman Pro’ya geçin\n${why}: kurucu fiyatıyla ayda 29 $ (ilk 100 müşteri; abonelik sürdükçe değişmez, sonrasında 49 $) ya da yılda 290 $, ${BILLING_URL}. Anahtar aynı kalır. Geçtiniz mi? ${refresh}`
+                    : `### Upgrade to Katman Pro\n${why}: ${PRO_PRICE_NOTE}, 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\nKatman Pro: ${PRO_PRICE_NOTE}; the key stays the same. Your Audit Week tools keep working${s.planEndsAt ? ` until ${day(s.planEndsAt)}` : ""}. Already upgraded? ${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"
+        ? [
+            "- **Denetim Haftası**: 7 gün için 3 $, tek seferlik (kendiliğinden yenilenmez, hesap başına bir kez). Denetim, araştırma, plan ve yapay zekâ görünürlük ölçümleri; sayfa yapmaz, site dosyası yazmaz.",
+            "- **Katman Pro**: kurucu fiyatıyla ayda 29 $ (ilk 100 müşteri; abonelik sürdükçe değişmez, sonrasında 49 $) ya da yılda 290 $. Her şey: P0–P14 prompt’ları, sayfa brief’leri ve dosya üretimi dâhil.",
+        ].join("\n")
+        : [
+            `- **Audit Week**: ${AUDIT_PRICE_NOTE}. Audit, research, plan and AI-visibility checks; it doesn't build pages or write site files.`,
+            `- **Katman Pro**: ${PRO_PRICE_NOTE}. Everything, including the P0–P14 prompts, page briefs and file generation.`,
+        ].join("\n");
+}
+/** The two plans as a table (katman_start without a plan). */
+function plansTable(lang) {
+    return lang === "tr"
+        ? mdTable(["Plan", "Fiyat", "Kapsadığı"], [
+            ["**Denetim Haftası**", "7 gün için 3 $, tek seferlik (kendiliğinden yenilenmez, hesap başına bir kez)", "Denetim ve öneriler: katman_start, araştırma, kod taraması, canlı site denetimi, anahtar kelimeler, plan, içerik kontrolü, yapay zekâ görünürlük ölçümleri, elle kontroller ve rapor. Sayfa yapmaz, site dosyası yazmaz."],
+            ["**Katman Pro**", "Kurucu fiyatıyla ayda 29 $ (ilk 100 müşteri; abonelik sürdükçe değişmez, sonrasında 49 $) ya da yılda 290 $", "Her şey: P0–P14 prompt’ları, sayfa brief’leri, dosya üretimi (robots.txt, llms.txt, JSON-LD), IndexNow, zamanlanmış izleme ve katman.pro paneli dâhil."],
+        ])
+        : mdTable(["Plan", "Price", "What it covers"], [
+            ["**Audit Week**", AUDIT_PRICE_NOTE, "Audit and recommendations: katman_start, research, code scan, live audit, keywords, plan, content lint, AI-visibility runs, manual checks and the report. It doesn't build pages or write site files."],
+            ["**Katman Pro**", PRO_PRICE_NOTE, "Everything, including the P0–P14 prompts, page briefs, file generation (robots.txt, llms.txt, JSON-LD), IndexNow, scheduled monitoring and the katman.pro dashboard."],
+        ]);
+}
+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);
+    const proOnly = isProOnly(o.feature) ? ` ${o.tool} is in Katman Pro; the Audit Week doesn't include it.` : "";
     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 + proOnly] : []),
+        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(`Katman Pro: ${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" && (onlyPro(s) || isProOnly(o.feature))) {
+            L.push(`Upgrade to Katman Pro at ${BILLING_URL}: ${PRO_PRICE_NOTE}${onlyPro(s) ? " (each account gets one Audit Week)" : ""}. The key stays the same. Already upgraded? Run: katman-mcp account --refresh`);
+        }
+        else if (s.plan === "none") {
+            L.push(`Choose a plan at ${BILLING_URL}. Audit Week: ${AUDIT_PRICE_NOTE}. Katman Pro: ${PRO_PRICE_NOTE}. The key stays the same. Already 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). */
+/** 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 cheapest plan that includes the feature. */
+        requiredPlan: isProOnly(feature) ? "pro" : "audit",
+        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)]),
+        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}`;
+}
 export { when as fmtWhen, day as fmtDay };

package/dist/tools/crawl/cli.js

@@ -100,7 +100,7 @@ export const help = [
     "  katman-mcp audit <url> [--max 50] [--root .] [--urls u1,u2] [--preview u1] [--no-bots] [--strict] [--no-save]",
     "                                              audit the live site like AI crawlers see it (--strict: exit 2 on critical)",
     "  katman-mcp indexnow [--root .] [--site url] [--urls u1,u2] [--submit]",
-    "                                              IndexNow key check + new/changed URLs (dry run unless --submit)",
+    "                                              IndexNow key check + new/changed URLs (dry run unless --submit; Katman Pro)",
     '  katman-mcp keywords "<seed>" [--lang en] [--country us] [--no-expand] [--save]',
     "                                              Google autocomplete ideas (≤40 requests)",
 ];