katman-mcp 0.1.0 → 0.3.0

package/dist/license.js

@@ -1,12 +1,20 @@
-// Katman Pro licensing (docs/07-APP-SPEC.md §6).
+// Katman licensing (docs/07-APP-SPEC.md §6). Nothing is free: every tool except katman_account needs KATMAN_KEY
+// with an active plan: Katman Pro, 1 site or 3 sites (every tool; 5 or 30 audits a month), or an Audit Week bought
+// earlier (audit and recommendations, 7 days); the plans, features and the tool → feature map live in plans.ts.
 //
 // - KATMAN_KEY comes from the environment (the MCP config). It is sent only to KATMAN_API_URL (default
-//   https://katman.pro), in the JSON body of POST /api/web/mcp/verify and /api/web/mcp/sync, and is never
-//   printed, logged or written anywhere.
-// - Verification runs at most once per `checkAgainAfter` (default 24 h). The answer is cached in
-//   ~/.katman/license.json under the key's SHA-256 hash (never the key).
-// - Offline grace: when katman.pro can't be reached, the last good answer keeps working for 7 days.
-// - Free tools never call into this module's network path; Pro tools go through withPro() at registration.
+//   https://katman.pro), in the JSON body of POST /api/web/mcp/verify, /api/web/mcp/usage and /api/web/mcp/sync,
+//   and is never printed, logged or written anywhere.
+// - Verification runs at most once per `checkAgainAfter` (≤ 24 h), and again as soon as the plan's end date
+//   (planEndsAt) has passed. The answer is cached in ~/.katman/license.json under the key's SHA-256 hash (never the key).
+// - Offline grace: when katman.pro can't be reached, the last good answer keeps working for 7 days, never past the
+//   end of an Audit Week.
+// - Audits are counted by katman.pro, not here: the audit runs on this machine, so katman_audit_site and the CLI
+//   `audit` ask first (useAudit → POST /api/web/mcp/usage, once the plan check has passed). A refusal (audit or site
+//   limit) explains and runs nothing; when katman.pro can't be reached or answers 5xx the audit runs anyway (fail
+//   open) and the result says the count wasn't checked.
+// - Every tool goes through withPlan() at registration (katman_start through startLicense()); katman_account is the
+//   only open tool, and the CLI uses the same gate. Without a key nothing is sent to katman.pro.
 // - Tests inject a LicenseProvider (createServer({ license }) / runCli(args, { license })); there is no env
 //   switch that turns the gate off.
 import { createHash } from "node:crypto";
@@ -15,31 +23,11 @@ import path from "node:path";
 import { promises as fs } from "node:fs";
 import { resolveRoot } from "./context.js";
 import { HOMEPAGE, VERSION } from "./meta.js";
+import { AUDIT_FEATURES, PRO_FEATURES, TOOL_FEATURES, toolForFeature } from "./plans.js";
 import { ok } from "./util.js";
-import { proNotice, projectFacts, renderUpsell, statusLine, upsellStructured } from "./tools/account/upsell.js";
-/** License features (spec §6). Trial = Pro. */
-export const PRO_FEATURES = ["plan", "prompts", "briefs", "generate", "lint", "visibility", "manual_check", "indexnow", "report", "monitoring", "sync"];
-/** Tools that never need a key (the free diagnosis). */
-export const FREE_TOOLS = ["katman_start", "katman_research", "katman_scan_code", "katman_audit_site", "katman_keywords", "katman_account"];
-/** Pro tool → license feature. */
-export const PRO_TOOLS = {
-    katman_plan: "plan",
-    katman_prompt: "prompts",
-    katman_page_brief: "briefs",
-    katman_generate: "generate",
-    katman_lint_content: "lint",
-    katman_visibility_run: "visibility",
-    katman_manual_check: "manual_check",
-    katman_indexnow: "indexnow",
-    katman_report: "report",
-    katman_setup_monitoring: "monitoring",
-    katman_sync: "sync",
-};
-/** Appended to every Pro tool's description. */
-export const PRO_NOTE = " (Katman Pro — needs KATMAN_KEY; 7-day free trial at katman.pro/app)";
-export function toolForFeature(feature) {
-    return Object.keys(PRO_TOOLS).find((t) => PRO_TOOLS[t] === feature) ?? `katman_${feature}`;
-}
+import { METHOD_INLINE, applyMethod } from "./tools/method/data/_store.js";
+import { planNotice, projectFacts, renderUpsell, statusLine, upsellStructured } from "./tools/account/upsell.js";
+export * from "./plans.js";
 export function allows(status, feature) {
     return status.state === "valid" && status.features.includes(feature);
 }
@@ -79,7 +67,7 @@ export function apiBase(env) {
     return { url: `${u.protocol}//${u.host}${u.pathname.replace(/\/+$/, "")}` };
 }
 /** POST JSON. Redirects are not followed (a 3xx must never carry the key to another host). Never throws. */
-export const postJson = async (url, body, { timeoutMs }) => {
+export const postJson = async (url, body, { timeoutMs, maxChars = 100_000 }) => {
     const ctrl = new AbortController();
     const timer = setTimeout(() => ctrl.abort(), timeoutMs);
     try {
@@ -94,7 +82,7 @@ export const postJson = async (url, body, { timeoutMs }) => {
             },
             body: JSON.stringify(body),
         });
-        const text = (await res.text()).slice(0, 100_000);
+        const text = (await res.text()).slice(0, maxChars);
         return { status: res.status, body: text };
     }
     catch (e) {
@@ -114,6 +102,17 @@ export const GRACE_MS = 7 * DAY_S * 1000;
 /** After a failed attempt, wait this long before trying the network again while the grace covers us. */
 const RETRY_AFTER_FAILURE_MS = 10 * 60 * 1000;
 const TIMEOUT_MS = 8_000;
+/** The audit check sits in front of every audit: short, and the audit runs anyway when it times out. */
+const USAGE_TIMEOUT_MS = 5_000;
+/** The method data is a few hundred kB, fetched once per process. */
+const METHOD_TIMEOUT_MS = 20_000;
+const METHOD_MAX_CHARS = 8_000_000;
+/**
+ * Entries this version writes (verify API v2: plans none / audit / pro, now with limits and usage). Katman 0.1.x
+ * cached free / trial / pro with other feature names in the same file, and 0.2.x entries have no limits; they don't
+ * count here and are replaced at the next check.
+ */
+const CACHE_CONTRACT = 3;
 export function defaultCacheFile() {
     return path.join(os.homedir(), ".katman", "license.json");
 }
@@ -150,9 +149,10 @@ function prune(entries, keep, now) {
     out.sort((a, b) => Date.parse(b[1].checkedAt ?? "") - Date.parse(a[1].checkedAt ?? ""));
     return Object.fromEntries(out.slice(0, 20));
 }
+/** checkAgainAfter in seconds: at least a minute, at most a day (the server lowers it at the end of an Audit Week). */
 function ttlSeconds(x) {
     const n = Number(x);
-    return Number.isFinite(n) && n > 0 ? Math.min(Math.max(Math.round(n), 60), 7 * DAY_S) : DEFAULT_TTL_S;
+    return Number.isFinite(n) && n > 0 ? Math.min(Math.max(Math.round(n), 60), DAY_S) : DEFAULT_TTL_S;
 }
 function toIso(x) {
     if (typeof x === "string" && x.trim()) {
@@ -163,7 +163,43 @@ function toIso(x) {
         return new Date(x < 1e12 ? x * 1000 : x).toISOString();
     return undefined;
 }
-/** Parse a /api/web/mcp/verify response (spec §6). Only a 401 (or an explicit ok:false) is a rejection. */
+const isObj = (x) => !!x && typeof x === "object" && !Array.isArray(x);
+const wholeNumber = (x, min, max = 1_000_000) => typeof x === "number" && Number.isInteger(x) && x >= min && x <= max ? x : undefined;
+/** {sites, auditsPerMonth} from katman.pro; anything that isn't two positive whole numbers is no limit. */
+export function parseLimits(x) {
+    if (!isObj(x))
+        return undefined;
+    const sites = wholeNumber(x.sites, 1);
+    const auditsPerMonth = wholeNumber(x.auditsPerMonth, 1);
+    return sites !== undefined && auditsPerMonth !== undefined ? { sites, auditsPerMonth } : undefined;
+}
+/** {month, audits, sites, resetsAt} from katman.pro; malformed counts are dropped. */
+export function parseUsage(x) {
+    if (!isObj(x))
+        return undefined;
+    const audits = wholeNumber(x.audits, 0);
+    const sites = wholeNumber(x.sites, 0);
+    const resetsAt = toIso(x.resetsAt);
+    const month = typeof x.month === "string" && /^\d{4}-\d{2}$/.test(x.month) ? x.month : undefined;
+    return audits !== undefined && sites !== undefined && resetsAt && month ? { month, audits, sites, resetsAt } : undefined;
+}
+/** "0.3.0" >= "0.3.0"; anything that isn't a plain x.y.z version counts as older. */
+export function versionAtLeast(version, min) {
+    const parse = (v) => (/^\d+\.\d+\.\d+/.test(v) ? v.split("-")[0].split(".").map(Number) : undefined);
+    const a = parse(version);
+    const b = parse(min);
+    if (!a || !b)
+        return false;
+    for (let i = 0; i < 3; i++)
+        if ((a[i] ?? 0) !== (b[i] ?? 0))
+            return (a[i] ?? 0) > (b[i] ?? 0);
+    return true;
+}
+/**
+ * Parse a /api/web/mcp/verify response (spec §6, API v2). Only a 401 (or an explicit ok:false) is a rejection.
+ * Tolerant of older servers: an unknown plan (trial, free…) is "none", `features` is read from the array whatever the
+ * plan says, and trialEndsAt counts as planEndsAt.
+ */
 export function parseVerify(res) {
     let j;
     try {
@@ -175,16 +211,36 @@ export function parseVerify(res) {
         j = undefined;
     }
     if (res.status === 200 && j?.ok === true) {
-        const plan = j.plan === "trial" || j.plan === "pro" ? j.plan : "free";
+        const plan = j.plan === "audit" || j.plan === "pro" ? j.plan : "none";
         const features = Array.isArray(j.features)
             ? j.features.filter((f) => typeof f === "string").slice(0, 64)
-            : plan === "free"
-                ? []
-                : [...PRO_FEATURES];
+            : plan === "pro"
+                ? [...PRO_FEATURES]
+                : plan === "audit"
+                    ? [...AUDIT_FEATURES]
+                    : [];
         const account = j.account && typeof j.account === "object" ? j.account : {};
         const emailMasked = typeof account.emailMasked === "string" ? account.emailMasked.slice(0, 120) : undefined;
-        const trialEndsAt = toIso(j.trialEndsAt);
-        return { kind: "good", good: { plan, features, checkAgainAfter: ttlSeconds(j.checkAgainAfter), ...(trialEndsAt ? { trialEndsAt } : {}), ...(emailMasked ? { emailMasked } : {}) } };
+        const planEndsAt = toIso(j.planEndsAt) ?? toIso(j.trialEndsAt);
+        // Only a plan with limits (Katman Pro, 1 site / 3 sites) carries limits, usage, enforced and updateMcpTo.
+        const limits = parseLimits(j.limits);
+        const usage = limits ? parseUsage(j.usage) : undefined;
+        const updateMcpTo = limits && typeof j.updateMcpTo === "string" && /^\d{1,4}\.\d{1,5}\.\d{1,6}$/.test(j.updateMcpTo) ? j.updateMcpTo : undefined;
+        return {
+            kind: "good",
+            good: {
+                plan,
+                features,
+                checkAgainAfter: ttlSeconds(j.checkAgainAfter),
+                ...(planEndsAt ? { planEndsAt } : {}),
+                ...(j.auditWeekUsed === true ? { auditWeekUsed: true } : {}),
+                ...(limits ? { limits } : {}),
+                ...(usage ? { usage } : {}),
+                ...(limits && typeof j.enforced === "boolean" ? { enforced: j.enforced } : {}),
+                ...(updateMcpTo ? { updateMcpTo } : {}),
+                ...(emailMasked ? { emailMasked } : {}),
+            },
+        };
     }
     if (res.status === 401 || (j?.ok === false && (j.error === "invalid_key" || j.error === "revoked"))) {
         return { kind: "rejected", error: j?.error === "revoked" ? "revoked" : "invalid_key" };
@@ -195,6 +251,30 @@ export function parseVerify(res) {
         return { kind: "failed", error: `unexpected redirect (HTTP ${res.status}); check KATMAN_API_URL` };
     return { kind: "failed", error: `HTTP ${res.status}${res.status === 200 ? " (unexpected answer)" : ""}` };
 }
+/** The end date of a plan that grants features and still ran when it was checked; once it passes, check again. */
+function endsAfterCheck(g, checkedAt) {
+    const ends = Date.parse(g.planEndsAt ?? "");
+    return g.features.length && Number.isFinite(ends) && ends > checkedAt ? ends : undefined;
+}
+function nextCheck(g) {
+    const checked = Date.parse(g.checkedAt);
+    return new Date(Math.min(checked + g.checkAgainAfter * 1000, endsAfterCheck(g, checked) ?? Infinity)).toISOString();
+}
+/** The offline grace: 7 days after the last good check, never past the end of an Audit Week. */
+function graceUntil(g) {
+    const grace = Date.parse(g.checkedAt) + GRACE_MS;
+    const ends = g.plan === "pro" ? NaN : Date.parse(g.planEndsAt ?? "");
+    return new Date(Number.isFinite(ends) ? Math.min(grace, ends) : grace).toISOString();
+}
+/** A "none" answer right after a paid plan remembers which plan ended and, when the old end date has passed, when. */
+function withEnded(next, prev, at) {
+    if (next.plan !== "none" || next.features.length || !prev)
+        return next;
+    if (prev.plan === "none")
+        return prev.ended ? { ...next, ended: prev.ended } : next;
+    const ends = Date.parse(prev.planEndsAt ?? "");
+    return { ...next, ended: { plan: prev.plan, ...(Number.isFinite(ends) && ends <= at ? { at: prev.planEndsAt } : {}) } };
+}
 export function createLicenseProvider(deps = {}) {
     const env = () => deps.env ?? process.env;
     const post = deps.post ?? postJson;
@@ -206,34 +286,48 @@ export function createLicenseProvider(deps = {}) {
     /** Never let the key appear in an error string (belt and braces: it's only ever in a request body). */
     const scrub = (s, key) => (key ? s.split(key).join(keyHint(key)) : s);
     function fromGood(g, source, at, extra = {}) {
-        // A trial past its end date is free, even if the cached answer still says trial (no offline extension).
-        const ended = g.plan !== "pro" && !!g.trialEndsAt && Date.parse(g.trialEndsAt) <= at;
-        const cutOff = ended && g.plan === "trial";
+        // A plan past its end date gives nothing, even if the cached or offline answer still lists features (no offline
+        // extension of an Audit Week). Pro renews into a new period, so its end date only triggers a new check (fresh()).
+        const expired = g.plan !== "pro" && !!g.planEndsAt && Date.parse(g.planEndsAt) <= at;
+        const ended = expired ? { plan: g.plan === "audit" ? "audit" : g.ended?.plan, at: g.planEndsAt } : g.plan === "none" ? g.ended : undefined;
+        const endsAt = g.planEndsAt ?? ended?.at;
         return {
             state: "valid",
-            plan: cutOff ? "free" : g.plan,
-            features: cutOff ? [] : [...g.features],
-            ...(g.trialEndsAt ? { trialEndsAt: g.trialEndsAt } : {}),
-            ...(ended ? { trialEnded: true } : {}),
+            plan: expired ? "none" : g.plan,
+            features: expired ? [] : [...g.features],
+            ...(endsAt ? { planEndsAt: endsAt } : {}),
+            ...(ended ? { planEnded: true, ...(ended.plan ? { endedPlan: ended.plan } : {}) } : {}),
+            ...(g.auditWeekUsed || (expired && g.plan === "audit") ? { auditWeekUsed: true } : {}),
+            ...(!expired && g.limits ? { limits: g.limits } : {}),
+            // The counts start again on the 1st: a count from last month is not shown.
+            ...(!expired && g.limits && g.usage && Date.parse(g.usage.resetsAt) > at ? { usage: g.usage } : {}),
+            ...(!expired && g.limits && g.enforced !== undefined ? { enforced: g.enforced } : {}),
+            ...(!expired && g.updateMcpTo && !versionAtLeast(version, g.updateMcpTo) ? { updateMcpTo: g.updateMcpTo } : {}),
             ...(g.emailMasked ? { emailMasked: g.emailMasked } : {}),
             checkedAt: g.checkedAt,
-            nextCheckAt: new Date(Date.parse(g.checkedAt) + g.checkAgainAfter * 1000).toISOString(),
+            nextCheckAt: nextCheck(g),
             source,
             ...extra,
         };
     }
     function rejected(error, source, key) {
-        return { state: error === "revoked" ? "revoked" : "invalid", plan: "free", features: [], source, keyHint: keyHint(key) };
+        return { state: error === "revoked" ? "revoked" : "invalid", plan: "none", features: [], source, keyHint: keyHint(key) };
     }
     function fresh(e, at) {
         if (!e.result || !e.checkedAt)
             return false;
-        const age = at - Date.parse(e.checkedAt);
+        const checked = Date.parse(e.checkedAt);
+        const age = at - checked;
         if (!(age >= 0))
             return false; // unparsable or in the future (clock change): check again
         if (!e.result.ok)
             return age < REJECTED_TTL_S * 1000;
-        if (e.result.plan === "trial" && e.result.trialEndsAt && Date.parse(e.result.trialEndsAt) <= at)
+        // "Update katman-mcp" was the answer for an older version: after the update, ask again at once.
+        if (e.result.updateMcpTo && versionAtLeast(version, e.result.updateMcpTo))
+            return false;
+        // Once the plan's end date has passed, check again at once: an Audit Week ends, Pro renews into a new period.
+        const ends = endsAfterCheck(e.result, checked);
+        if (ends !== undefined && ends <= at)
             return false;
         return age < e.result.checkAgainAfter * 1000;
     }
@@ -249,8 +343,12 @@ export function createLicenseProvider(deps = {}) {
         const server = base.url ?? HOMEPAGE;
         const cache = await readCache(cacheFile);
         const cached = cache.entries[hash];
-        const entry = cached && (cached.base ?? HOMEPAGE) === server ? cached : {};
+        const entry = cached && cached.contract === CACHE_CONTRACT && (cached.base ?? HOMEPAGE) === server ? cached : {};
         const hint = keyHint(key);
+        const offline = (g, error) => ({
+            ...fromGood(g, "offline-grace", at, { graceUntil: graceUntil(g), ...(error ? { error } : {}) }),
+            keyHint: hint,
+        });
         if (!refresh && fresh(entry, at)) {
             const r = entry.result;
             return r.ok ? { ...fromGood({ ...r, checkedAt: entry.checkedAt }, "cache", at), keyHint: hint } : rejected(r.error, "cache", key);
@@ -258,7 +356,7 @@ export function createLicenseProvider(deps = {}) {
         // Offline and recently failed: don't wait for another timeout on every tool call.
         const failedAt = Date.parse(entry.failedAt ?? "");
         if (!refresh && Number.isFinite(failedAt) && at - failedAt >= 0 && at - failedAt < RETRY_AFTER_FAILURE_MS && withinGrace(entry, at)) {
-            return { ...fromGood(entry.good, "offline-grace", at, { graceUntil: new Date(Date.parse(entry.good.checkedAt) + GRACE_MS).toISOString(), error: entry.failure }), keyHint: hint };
+            return offline(entry.good, entry.failure);
         }
         const res = base.url
             ? await post(`${base.url}/api/web/mcp/verify`, { key, mcpVersion: version }, { timeoutMs })
@@ -267,21 +365,22 @@ export function createLicenseProvider(deps = {}) {
         const checkedAt = new Date(at).toISOString();
         let status;
         if (parsed.kind === "good") {
-            cache.entries[hash] = { base: server, checkedAt, result: { ok: true, ...parsed.good }, good: { ...parsed.good, checkedAt } };
-            status = { ...fromGood({ ...parsed.good, checkedAt }, "network", at), keyHint: hint };
+            const good = withEnded(parsed.good, entry.good, at);
+            cache.entries[hash] = { contract: CACHE_CONTRACT, base: server, checkedAt, result: { ok: true, ...good }, good: { ...good, checkedAt } };
+            status = { ...fromGood({ ...good, checkedAt }, "network", at), keyHint: hint };
         }
         else if (parsed.kind === "rejected") {
-            cache.entries[hash] = { base: server, checkedAt, result: { ok: false, error: parsed.error } };
+            cache.entries[hash] = { contract: CACHE_CONTRACT, base: server, checkedAt, result: { ok: false, error: parsed.error } };
             status = rejected(parsed.error, "network", key);
         }
         else {
             const error = scrub(parsed.error, key);
-            cache.entries[hash] = { ...entry, base: server, failedAt: checkedAt, failure: error };
+            cache.entries[hash] = { ...entry, contract: CACHE_CONTRACT, base: server, failedAt: checkedAt, failure: error };
             status = withinGrace(entry, at)
-                ? { ...fromGood(entry.good, "offline-grace", at, { graceUntil: new Date(Date.parse(entry.good.checkedAt) + GRACE_MS).toISOString(), error }), keyHint: hint }
+                ? offline(entry.good, error)
                 : {
                     state: "unreachable",
-                    plan: "free",
+                    plan: "none",
                     features: [],
                     source: "network",
                     error,
@@ -293,17 +392,29 @@ export function createLicenseProvider(deps = {}) {
         await writeCache(cacheFile, cache);
         return status;
     }
+    /** Keep the newest counts in the cached answer, so katman_account shows this month's audits without another check. */
+    async function remember(key, limits, usage) {
+        const server = apiBase(env()).url ?? HOMEPAGE;
+        const cache = await readCache(cacheFile);
+        const e = cache.entries[hashKey(key)];
+        if (!e || e.contract !== CACHE_CONTRACT || (e.base ?? HOMEPAGE) !== server || !e.result?.ok)
+            return;
+        e.result = { ...e.result, limits, usage };
+        if (e.good)
+            e.good = { ...e.good, limits, usage };
+        await writeCache(cacheFile, cache);
+    }
     return {
         hasKey: () => !!readKey(env()).key,
         baseUrl: () => apiBase(env()).url ?? HOMEPAGE,
         async status(opts = {}) {
             const { key, hint } = readKey(env());
             if (!key)
-                return { state: "no_key", plan: "free", features: [], source: "none", ...(hint ? { hint } : {}) };
+                return { state: "no_key", plan: "none", features: [], source: "none", ...(hint ? { hint } : {}) };
             if (!KEY_RE.test(key)) {
                 return {
                     state: "invalid",
-                    plan: "free",
+                    plan: "none",
                     features: [],
                     source: "local",
                     keyHint: keyHint(key),
@@ -320,6 +431,74 @@ export function createLicenseProvider(deps = {}) {
             inflight.set(flightKey, p);
             return p;
         },
+        async loadMethod() {
+            const { key } = readKey(env());
+            if (!key || !KEY_RE.test(key))
+                return { ok: false, error: "KATMAN_KEY is not set" };
+            const base = apiBase(env());
+            if (!base.url)
+                return { ok: false, error: base.error ?? "no API URL" };
+            const res = await post(`${base.url}/api/web/mcp/method`, { key, mcpVersion: version }, { timeoutMs: METHOD_TIMEOUT_MS, maxChars: METHOD_MAX_CHARS });
+            let j;
+            try {
+                const x = JSON.parse(res.body);
+                if (isObj(x))
+                    j = x;
+            }
+            catch {
+                j = undefined;
+            }
+            if (res.status === 200 && j?.ok === true && isObj(j.data))
+                return { ok: true, data: j.data };
+            if (res.status === 401)
+                return { ok: false, error: "katman.pro did not accept this KATMAN_KEY" };
+            if (res.status === 403)
+                return { ok: false, error: "this key has no active Katman plan" };
+            const code = typeof j?.error === "string" && /^[a-z_]{1,40}$/.test(j.error) ? ` ${j.error}` : "";
+            const why = res.status === 0 ? res.error || "network error" : `HTTP ${res.status}${code}`;
+            return { ok: false, error: scrub(why, key).slice(0, 120) };
+        },
+        async useAudit(domain) {
+            const { key } = readKey(env());
+            if (!key || !KEY_RE.test(key))
+                return { allowed: false, reason: "no_plan" };
+            const unchecked = (error) => ({ allowed: true, unchecked: true, error: scrub(error, key).slice(0, 120) });
+            const base = apiBase(env());
+            if (!base.url)
+                return unchecked(base.error ?? "no API URL");
+            const res = await post(`${base.url}/api/web/mcp/usage`, { key, kind: "audit", domain, mcpVersion: version }, { timeoutMs: USAGE_TIMEOUT_MS });
+            let j;
+            try {
+                const x = JSON.parse(res.body);
+                if (isObj(x))
+                    j = x;
+            }
+            catch {
+                j = undefined;
+            }
+            if (res.status === 401)
+                return { allowed: false, reason: j?.error === "revoked" ? "revoked" : "invalid_key" };
+            if (res.status === 200 && j?.ok === true && typeof j.allowed === "boolean") {
+                const limits = parseLimits(j.limits);
+                const usage = parseUsage(j.usage);
+                const reason = j.reason === "audit_limit" || j.reason === "site_limit" || j.reason === "no_plan" ? j.reason : undefined;
+                const plan = j.plan === "audit" || j.plan === "pro" || j.plan === "none" ? j.plan : undefined;
+                if (limits && usage)
+                    await remember(key, limits, usage).catch(() => undefined);
+                return {
+                    allowed: j.allowed,
+                    ...(j.allowed ? {} : { reason: reason ?? "no_plan" }),
+                    ...(plan ? { plan } : {}),
+                    ...(typeof j.enforced === "boolean" ? { enforced: j.enforced } : {}),
+                    limits: limits ?? null,
+                    ...(usage ? { usage } : {}),
+                };
+            }
+            // Anything else (no network, a timeout, 5xx, a rate limit, a host without this endpoint, an answer this version
+            // doesn't understand): the audit runs, and the result says the count wasn't checked.
+            const code = typeof j?.error === "string" && /^[a-z_]{1,40}$/.test(j.error) ? j.error : undefined;
+            return unchecked(res.status === 0 ? res.error || "network error" : res.status >= 300 && res.status < 400 ? `unexpected redirect (HTTP ${res.status}); check KATMAN_API_URL` : `HTTP ${res.status}${code ? ` ${code}` : ""}`);
+        },
         async sync(body) {
             const { key } = readKey(env());
             if (!key || !KEY_RE.test(key))
@@ -345,7 +524,7 @@ export function createLicenseProvider(deps = {}) {
                 return { ok: true, status: res.status, dashboardUrl: dashboardUrl(base.url, j.url ?? j.dashboardUrl, projectId), ...(projectId ? { projectId } : {}), ...(message ? { message } : {}) };
             }
             const code = typeof j.error === "string" ? j.error.slice(0, 60) : undefined;
-            const error = res.status === 0 ? "network" : res.status === 401 ? (code === "revoked" ? "revoked" : "invalid_key") : res.status === 402 || res.status === 403 ? code ?? "not_pro" : code ?? `HTTP ${res.status}`;
+            const error = res.status === 0 ? "network" : res.status === 401 ? (code === "revoked" ? "revoked" : "invalid_key") : res.status === 402 || res.status === 403 ? code ?? "pro_required" : code ?? `HTTP ${res.status}`;
             return { ok: false, status: res.status, error, ...(res.status === 0 && res.error ? { message: scrub(res.error, key) } : message ? { message } : {}) };
         },
     };
@@ -375,24 +554,61 @@ export function licenseOf(ctx) {
 }
 // ---------------------------------------------------------------------------------------------------------------
 // Gate
-export async function requirePro(feature, provider) {
-    let status;
+/** The provider's status; a provider that throws counts as unreachable. */
+export async function statusOf(provider) {
     try {
-        status = await provider.status();
+        return await provider.status();
     }
     catch (e) {
-        status = { state: "unreachable", plan: "free", features: [], source: "network", error: e instanceof Error ? e.message : String(e) };
+        return { state: "unreachable", plan: "none", features: [], source: "network", error: e instanceof Error ? e.message : String(e) };
     }
-    return { allowed: allows(status, feature), status };
+}
+export async function requireFeature(feature, provider) {
+    const status = await statusOf(provider);
+    const allowed = allows(status, feature);
+    if (allowed)
+        await ensureMethod(provider);
+    return { allowed, status };
+}
+// ---------------------------------------------------------------------------------------------------------------
+// Method data (the published package carries none; see src/tools/method/data/_store.ts)
+let methodLoaded = METHOD_INLINE;
+let methodLoading;
+/** Thrown when a tool needs the method and katman.pro couldn't send it; the message is shown to the user. */
+export class MethodUnavailableError extends Error {
 }
 /**
- * Wrap a Pro tool's handler at registration. Without a Pro/trial license it returns a friendly upsell
+ * Make sure the method data is in memory before a paid tool runs: fetched from katman.pro once per process with the
+ * key, never written to disk. Throws MethodUnavailableError with a readable reason when it can't be loaded.
+ */
+export async function ensureMethod(provider) {
+    if (methodLoaded)
+        return;
+    if (!provider.loadMethod)
+        throw new MethodUnavailableError("Katman could not load its method data (this license provider can't fetch it).");
+    methodLoading ??= provider.loadMethod().then((r) => {
+        if (r.ok) {
+            applyMethod(r.data);
+            methodLoaded = true;
+        }
+        else {
+            methodLoading = undefined;
+        }
+        return r;
+    });
+    const r = await methodLoading;
+    if (!r.ok) {
+        throw new MethodUnavailableError(`Katman needs to reach ${provider.baseUrl()} once per session to load its method for your plan, and couldn't (${r.error}). Check the connection and KATMAN_KEY, then try again.`);
+    }
+}
+/**
+ * Wrap a tool's handler at registration. Without a plan that includes the feature it returns a short explanation
  * (not isError, so the agent relays it) instead of running the tool.
  */
-export function withPro(ctx, feature, handler) {
+export function withPlan(ctx, feature, handler) {
     const tool = toolForFeature(feature);
     return async (args, extra) => {
-        const gate = await requirePro(feature, licenseOf(ctx));
+        const gate = await requireFeature(feature, licenseOf(ctx));
         if (gate.allowed)
             return handler(args, extra);
         let facts;
@@ -407,42 +623,59 @@ export function withPro(ctx, feature, handler) {
         return ok(renderUpsell({ tool, feature, status: gate.status, facts, args: a, surface: "mcp" }), upsellStructured(tool, feature, gate.status));
     };
 }
-/**
- * For katman_start: a one-line plan status when KATMAN_KEY is set (no line and no network without it), and a
- * notice when the recommended next tool is a Pro tool the license doesn't cover.
- */
-export async function startLicense(ctx) {
-    const provider = licenseOf(ctx);
-    let status;
+/** Ask whether an audit of this domain may run (and have it counted). Never throws: a failing provider counts as unchecked, the audit runs. */
+export async function meterAudit(provider, domain) {
     try {
-        status = await provider.status();
+        return await provider.useAudit(domain);
     }
     catch (e) {
-        status = { state: "unreachable", plan: "free", features: [], source: "network", error: e instanceof Error ? e.message : String(e) };
+        return { allowed: true, unchecked: true, error: e instanceof Error ? e.message.slice(0, 120) : "error" };
     }
-    const keySet = provider.hasKey();
+}
+/** For katman_start: the gate, the plan line, and a notice when the recommended next tool isn't in the plan. */
+export async function startLicense(ctx) {
+    const provider = licenseOf(ctx);
+    const status = await statusOf(provider);
+    const allowed = allows(status, "start");
+    if (allowed)
+        await ensureMethod(provider);
     return {
-        ...(keySet || status.hint ? { line: statusLine(status) } : {}),
+        allowed,
+        status,
+        line: statusLine(status),
         notice: (tool) => {
-            const feature = PRO_TOOLS[tool];
-            return feature && !allows(status, feature) ? proNotice(tool, status) : undefined;
+            const feature = Object.hasOwn(TOOL_FEATURES, tool) ? TOOL_FEATURES[tool] : undefined;
+            return feature && !allows(status, feature) ? planNotice(tool, feature, status) : undefined;
+        },
+        structured: {
+            keySet: provider.hasKey(),
+            state: status.state,
+            plan: status.plan,
+            ...(status.planEndsAt ? { planEndsAt: status.planEndsAt } : {}),
+            ...(status.planEnded ? { planEnded: true } : {}),
+            ...(status.limits ? { limits: status.limits } : {}),
+            ...(status.usage ? { usage: status.usage } : {}),
+            ...(status.updateMcpTo ? { updateMcpTo: status.updateMcpTo } : {}),
         },
-        structured: { keySet, state: status.state, plan: status.plan, ...(status.trialEndsAt ? { trialEndsAt: status.trialEndsAt } : {}) },
     };
 }
 // ---------------------------------------------------------------------------------------------------------------
 // CLI
-/** Exit code of a Pro CLI command without a license. */
-export const EXIT_NEEDS_PRO = 4;
-/** CLI command → feature: plan, report, check, and indexnow only with --submit. */
-export function cliFeature(cmd, rest) {
-    if (rest.includes("--help") || rest.includes("-h"))
-        return undefined;
-    switch (cmd) {
-        case "plan": return "plan";
-        case "report": return "report";
-        case "check": return "visibility";
-        case "indexnow": return rest.includes("--submit") ? "indexnow" : undefined;
-        default: return undefined;
-    }
+/** Exit code of a CLI command without the plan it needs. */
+export const EXIT_NEEDS_PLAN = 4;
+/** CLI command → feature. Every command needs its feature except the OPEN_COMMANDS (and --help / --version). */
+export const CLI_FEATURES = {
+    scan: "scan",
+    audit: "audit",
+    keywords: "keywords",
+    plan: "plan",
+    report: "report",
+    check: "visibility",
+    models: "visibility",
+    indexnow: "indexnow",
+};
+/** Commands that always work, even without a key. */
+export const OPEN_COMMANDS = ["account"];
+export function cliFeature(cmd) {
+    return cmd !== undefined && Object.hasOwn(CLI_FEATURES, cmd) ? CLI_FEATURES[cmd] : undefined;
 }