katman-mcp 0.1.0 → 0.2.0

package/dist/license.js

@@ -1,12 +1,16 @@
-// 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, the Audit Week (audit and recommendations, 7 days) or Katman Pro (everything); 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.
+// - 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.
+// - 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 +19,10 @@ 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 { 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);
 }
@@ -114,6 +97,11 @@ 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;
+/**
+ * Entries this version writes (verify API v2: plans none / audit / pro). Katman 0.1.x cached free / trial / pro with
+ * other feature names in the same file; its entries don't count here and are replaced at the next check.
+ */
+const CACHE_CONTRACT = 2;
 export function defaultCacheFile() {
     return path.join(os.homedir(), ".katman", "license.json");
 }
@@ -150,9 +138,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 +152,11 @@ 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. */
+/**
+ * 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 +168,28 @@ 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);
+        return {
+            kind: "good",
+            good: {
+                plan,
+                features,
+                checkAgainAfter: ttlSeconds(j.checkAgainAfter),
+                ...(planEndsAt ? { planEndsAt } : {}),
+                ...(j.auditWeekUsed === true ? { auditWeekUsed: true } : {}),
+                ...(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 +200,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 +235,40 @@ 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 } : {}),
             ...(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)
+        // 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 +284,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 +297,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 +306,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,
@@ -299,11 +339,11 @@ export function createLicenseProvider(deps = {}) {
         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),
@@ -345,7 +385,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 +415,26 @@ export function licenseOf(ctx) {
 }
 // ---------------------------------------------------------------------------------------------------------------
 // Gate
-export async function requirePro(feature, provider) {
-    let status;
+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) };
     }
+}
+export async function requireFeature(feature, provider) {
+    const status = await statusOf(provider);
     return { allowed: allows(status, feature), status };
 }
 /**
- * Wrap a Pro tool's handler at registration. Without a Pro/trial license it returns a friendly upsell
+ * 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 +449,44 @@ 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.
- */
+/** 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);
-    let status;
-    try {
-        status = await provider.status();
-    }
-    catch (e) {
-        status = { state: "unreachable", plan: "free", features: [], source: "network", error: e instanceof Error ? e.message : String(e) };
-    }
-    const keySet = provider.hasKey();
+    const status = await statusOf(provider);
     return {
-        ...(keySet || status.hint ? { line: statusLine(status) } : {}),
+        allowed: allows(status, "start"),
+        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 } : {}),
         },
-        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;
 }

package/dist/meta.js

@@ -1,12 +1,19 @@
-export const VERSION = "0.1.0";
+export const VERSION = "0.2.0";
 export const HOMEPAGE = "https://katman.pro";
-/** Katman Pro (docs/07-APP-SPEC.md §1): 7-day trial without a card, then the founding price. */
+/** Plans (docs/07-APP-SPEC.md §1): nothing is free. Audit Week = $3 once for 7 days; Katman Pro = the founding price. */
 export const APP_URL = `${HOMEPAGE}/app`;
 export const KEYS_URL = `${APP_URL}/mcp`;
 export const BILLING_URL = `${APP_URL}/billing`;
-export const TRIAL_DAYS = 7;
+export const PRICING_URL = `${HOMEPAGE}/pricing`;
+/** How to add KATMAN_KEY to each editor's MCP config. */
+export const KEY_DOCS_URL = `${HOMEPAGE}/docs/getting-started`;
+export const AUDIT_WEEK_DAYS = 7;
+export const AUDIT_WEEK_PRICE = "$3";
 export const PRO_PRICE = "$29/month";
-export const PRO_PRICE_NOTE = "$29/month founding price, locked for the first 100 customers";
+/** Audit Week in one phrase. */
+export const AUDIT_PRICE_NOTE = "$3 once for 7 days, no auto-renewal, one per account";
+/** Katman Pro in one phrase. */
+export const PRO_PRICE_NOTE = "$29/month founding price for the first 100 customers, locked while you stay subscribed (later $49), or $290/year";
 /** Sent to the client model at initialization. Keep it short and imperative. */
 export const SERVER_INSTRUCTIONS = `Katman makes this project's public website readable, quotable and recommendable by AI assistants (ChatGPT, Claude, Gemini, Perplexity, Copilot) and findable in Google, Bing and Brave.
 
@@ -15,8 +22,11 @@ It follows the Katman method: 4 steps (1 Research → 2 Plan → 3 Build → 4 V
 - Quote: the first 1–3 sentences answer the question on their own, with the brand's one-sentence description.
 - Fit: there is a page written for the situation the customer describes to the assistant.
 
-Free vs Pro: katman_start, katman_research, katman_scan_code, katman_audit_site, katman_keywords and katman_account are free (the diagnosis). Every other tool is Katman Pro and needs KATMAN_KEY in the MCP config (7-day free trial, no card: katman.pro/app); without it the tool returns a short explanation instead of running — pass it on to the user.
-Never try to bypass or work around the license (no editing Katman's code or cache, no made-up keys); the free tools keep working either way.
+Plans: every tool except katman_account needs KATMAN_KEY with an active plan in the MCP config.
+- Audit Week ($3 for 7 days): katman_start, katman_research, katman_scan_code, katman_audit_site, katman_keywords, katman_plan, katman_lint_content, katman_visibility_run, katman_manual_check, katman_report. Audit and recommendations only: it never builds pages or writes site files.
+- Katman Pro ($29/month founding price, or $290/year): all of the above plus katman_prompt (P0–P14), katman_page_brief, katman_generate, katman_indexnow, katman_setup_monitoring and katman_sync.
+Without the right plan a tool returns a short explanation instead of running: pass it on to the user. katman_account always works and shows the plan, the days left and how to get a key.
+Never try to bypass or work around the licence (no editing Katman's code or cache, no made-up keys).
 
 How to work:
 1. Always call katman_start first; it tells you the next step. Pass project_root (absolute path of the project) and site_url when you know them.

package/dist/plans.js

@@ -0,0 +1,47 @@
+// Katman plans and license features (docs/07-APP-SPEC.md §1 and §6). Nothing is free: every tool except
+// katman_account needs KATMAN_KEY with an active plan. Shared by the gate (license.ts) and its texts
+// (tools/account/upsell.ts); no imports, so both sides can use it.
+/** Audit Week ($3 for 7 days): audit and recommendations. It never builds pages or writes site files. */
+export const AUDIT_FEATURES = ["start", "research", "scan", "audit", "keywords", "plan", "lint", "visibility", "manual_check", "report"];
+/** Katman Pro: the Audit Week set plus the tools that build pages and keep things running. */
+export const PRO_FEATURES = [...AUDIT_FEATURES, "prompts", "briefs", "generate", "indexnow", "monitoring", "sync"];
+/** Tool → license feature. Every tool needs its feature, except the OPEN_TOOLS. */
+export const TOOL_FEATURES = {
+    katman_start: "start",
+    katman_research: "research",
+    katman_scan_code: "scan",
+    katman_audit_site: "audit",
+    katman_keywords: "keywords",
+    katman_plan: "plan",
+    katman_lint_content: "lint",
+    katman_visibility_run: "visibility",
+    katman_manual_check: "manual_check",
+    katman_report: "report",
+    katman_prompt: "prompts",
+    katman_page_brief: "briefs",
+    katman_generate: "generate",
+    katman_indexnow: "indexnow",
+    katman_setup_monitoring: "monitoring",
+    katman_sync: "sync",
+};
+/** Tools that always work, even without a key. */
+export const OPEN_TOOLS = ["katman_account"];
+/** Appended to the description of every Audit Week tool. */
+export const AUDIT_NOTE = " (Audit Week or Pro — needs KATMAN_KEY)";
+/** Appended to the description of every Pro-only tool. */
+export const PRO_NOTE = " (Katman Pro — needs KATMAN_KEY)";
+/** True for the features only Katman Pro unlocks (not in the Audit Week). */
+export function isProOnly(feature) {
+    return !AUDIT_FEATURES.includes(feature);
+}
+/** The description note for a tool's feature. */
+export function tierNote(feature) {
+    return isProOnly(feature) ? PRO_NOTE : AUDIT_NOTE;
+}
+export function toolForFeature(feature) {
+    return Object.keys(TOOL_FEATURES).find((t) => TOOL_FEATURES[t] === feature) ?? `katman_${feature}`;
+}
+/** The tools of one tier: "audit" = the Audit Week tools (also in Pro), "pro" = the Pro-only tools. */
+export function toolsOf(tier) {
+    return Object.keys(TOOL_FEATURES).filter((t) => isProOnly(TOOL_FEATURES[t]) === (tier === "pro"));
+}

package/dist/tools/account/account.js

@@ -1,64 +1,85 @@
-// katman_account (free): the Katman plan behind KATMAN_KEY, trial days left, Pro features, masked account
-// email, last check, and how to connect or upgrade. Never shows the key.
-import { FREE_TOOLS, PRO_TOOLS, allows } from "../../license.js";
-import { APP_URL, BILLING_URL, PRO_PRICE_NOTE } from "../../meta.js";
-import { fmtDay, fmtWhen, howToText, reasonText, trialDaysLeft } from "./upsell.js";
+// katman_account (always open, even without a key): the Katman plan behind KATMAN_KEY (none, Audit Week with the
+// days left, or Katman Pro), the tools it unlocks, the masked account email, the last check, and how to get a key
+// or upgrade. Never shows the key.
+import { OPEN_TOOLS, TOOL_FEATURES, allows, toolsOf } from "../../license.js";
+import { APP_URL, BILLING_URL, KEYS_URL, PRICING_URL, PRO_PRICE_NOTE } from "../../meta.js";
+import { NO_KEY_TEXT, endedPhrase, fmtDay, fmtWhen, howToText, planDaysLeft, reasonText } from "./upsell.js";
+function planCell(s, left) {
+    if (s.state === "no_key")
+        return s.hint ? "None (KATMAN_KEY placeholder not filled)" : "None (no KATMAN_KEY)";
+    if (s.state !== "valid")
+        return `None (key ${s.state === "unreachable" ? "not verified" : s.state})`;
+    if (s.plan === "audit")
+        return `Audit Week: ${left ?? "?"} day${left === 1 ? "" : "s"} left (ends ${fmtDay(s.planEndsAt)}; no auto-renewal)`;
+    if (s.plan === "pro")
+        return "Katman Pro";
+    return `No active plan${s.planEnded ? ` (${endedPhrase(s)})` : s.auditWeekUsed ? " (Audit Week used)" : ""}`;
+}
+/** "on", "3 of 10 on" or "off". */
+function onText(tools, s) {
+    const on = tools.filter((t) => allows(s, TOOL_FEATURES[t])).length;
+    return on === tools.length ? "on" : on ? `${on} of ${tools.length} on` : "off";
+}
 export async function runAccount(provider, opts = {}) {
     const now = opts.now ?? new Date();
     const s = await provider.status({ refresh: opts.refresh });
-    const left = trialDaysLeft(s, now);
-    const proTools = Object.keys(PRO_TOOLS);
-    const on = proTools.filter((t) => allows(s, PRO_TOOLS[t]));
-    const planCell = s.state === "no_key"
-        ? "Free (no KATMAN_KEY)"
-        : s.state !== "valid"
-            ? `Free (key ${s.state === "unreachable" ? "not verified" : s.state})`
-            : s.plan === "trial"
-                ? `Trial: ${left ?? "?"} day${left === 1 ? "" : "s"} left (ends ${fmtDay(s.trialEndsAt)})`
-                : s.plan === "pro"
-                    ? "Katman Pro"
-                    : `Free${s.trialEnded ? ` (trial ended ${fmtDay(s.trialEndsAt)})` : ""}`;
+    const left = planDaysLeft(s, now);
+    const auditTools = toolsOf("audit");
+    const proTools = toolsOf("pro");
+    const on = Object.keys(TOOL_FEATURES).filter((t) => allows(s, TOOL_FEATURES[t]));
     const source = s.source === "cache" ? "cached answer" : s.source === "network" ? "just checked" : s.source === "offline-grace" ? `offline grace until ${fmtWhen(s.graceUntil)}` : s.source === "local" ? "not sent: malformed key" : "no key";
     const rows = [
-        ["Plan", planCell],
+        ["Plan", planCell(s, left)],
         ["Account", s.emailMasked ?? "–"],
         ["Key", s.state === "no_key" ? (s.hint ? "placeholder, not filled" : "not set (KATMAN_KEY)") : `${s.keyHint ?? "km_…"} (from KATMAN_KEY)`],
-        ["Pro features", s.features.length ? s.features.join(", ") : "none"],
+        ["Features", s.features.length ? s.features.join(", ") : "none"],
         ["Last check", s.checkedAt ? `${fmtWhen(s.checkedAt)} (${source}${s.nextCheckAt && s.source !== "offline-grace" ? `; next check after ${fmtWhen(s.nextCheckAt)}` : ""})` : `– (${source})`],
     ];
     if (s.error)
         rows.push(["Connection", `couldn't reach katman.pro: ${s.error}`]);
     const L = ["# Katman account", rows.map(([k, v]) => `- **${k}:** ${v}`).join("\n")];
-    L.push(`**Free tools** (no key): ${FREE_TOOLS.join(", ")}.`, `**Pro tools** (${on.length === proTools.length ? "on" : on.length ? `${on.length} of ${proTools.length} on` : "off"}): ${proTools.join(", ")}.`);
+    L.push([
+        `**Audit Week tools** (${onText(auditTools, s)}; Audit Week or Pro): ${auditTools.join(", ")}.`,
+        `**Katman Pro tools** (${onText(proTools, s)}; Pro only): ${proTools.join(", ")}.`,
+        `**Always open:** ${OPEN_TOOLS.join(", ")}.`,
+    ].join("\n"));
     if (s.state === "valid" && s.plan === "pro") {
         L.push(`Manage the subscription and invoices at ${BILLING_URL}.`);
     }
-    else if (s.state === "valid" && s.plan === "trial") {
-        L.push(`Keep Pro after the trial: ${BILLING_URL} (${PRO_PRICE_NOTE}). The key stays the same.`);
+    else if (s.state === "valid" && s.plan === "audit") {
+        L.push(`Your Audit Week ends on ${fmtDay(s.planEndsAt)} and doesn't renew. Katman Pro builds the pages (the P0–P14 prompts, page briefs, file generation, IndexNow, monitoring and the dashboard sync): ${PRO_PRICE_NOTE}, at ${BILLING_URL}. The key stays the same.`);
     }
     else {
-        if (s.state !== "no_key" || s.hint)
-            L.push(`**Why Pro tools are off:** ${reasonText(s)}`);
+        if (s.state === "no_key" && !s.hint)
+            L.push(NO_KEY_TEXT);
+        else
+            L.push(`**Why the tools are off:** ${reasonText(s)}`);
         L.push(howToText(s));
     }
-    L.push(`Network: Katman contacts katman.pro only to check this key (at most once a day, only when KATMAN_KEY is set) and when you call katman_sync. The key is never shown or written to disk; the cache (~/.katman/license.json) stores its SHA-256 hash. Account and keys: ${APP_URL}.`);
+    L.push(`Network: Katman contacts katman.pro only to check this key (at most once a day and when a plan ends, only when KATMAN_KEY is set) and when you call katman_sync. The key is never shown or written to disk; the cache (~/.katman/license.json) stores its SHA-256 hash. Plans: ${PRICING_URL} · account and keys: ${APP_URL}.`);
     return {
         text: L.join("\n\n"),
         structured: {
             state: s.state,
             plan: s.plan,
-            trialEndsAt: s.trialEndsAt ?? null,
-            trialDaysLeft: left ?? null,
-            trialEnded: !!s.trialEnded,
+            planEndsAt: s.planEndsAt ?? null,
+            planDaysLeft: left ?? null,
+            planEnded: !!s.planEnded,
+            endedPlan: s.endedPlan ?? null,
+            auditWeekUsed: !!s.auditWeekUsed,
             features: s.features,
             account: { emailMasked: s.emailMasked ?? null },
             checkedAt: s.checkedAt ?? null,
             nextCheckAt: s.nextCheckAt ?? null,
             source: s.source,
             graceUntil: s.graceUntil ?? null,
-            freeTools: [...FREE_TOOLS],
+            auditTools,
             proTools,
-            proToolsOn: on,
+            openTools: [...OPEN_TOOLS],
+            toolsOn: on,
+            pricingUrl: PRICING_URL,
+            upgradeUrl: BILLING_URL,
+            keysUrl: KEYS_URL,
         },
     };
 }

package/dist/tools/account/cli.js

@@ -16,6 +16,8 @@ export const commands = {
     },
 };
 export const help = [
-    "  katman-mcp account [--refresh]  Katman plan behind KATMAN_KEY (free / trial / Pro) and how to connect or upgrade",
-    "                             Pro commands (plan, report, check, indexnow --submit) need KATMAN_KEY; exit code 4 without it",
+    "  katman-mcp account [--refresh]  your Katman plan (none / Audit Week / Pro), days left, and how to get a key or upgrade",
+    "",
+    "Every command except account, --help and --version needs KATMAN_KEY with an active plan: Audit Week or Katman Pro",
+    "(indexnow: Katman Pro only). Without it a command explains the plans and exits with code 4. Plans: https://katman.pro/pricing",
 ];