katman-mcp 0.2.0 → 0.3.0

package/README.md

@@ -11,14 +11,20 @@ Katman is an MCP server that works inside your AI coding tool (Cursor, Claude Co
 
 ## Pricing
 
-Katman needs a licence key (`KATMAN_KEY`) with an active plan. Every tool except `katman_account` needs it.
+Katman needs a licence key (`KATMAN_KEY`) with an active plan. Every tool except `katman_account` needs it. Katman Pro comes in two sizes, monthly, and both include every tool:
 
-| Plan | Price | What you get |
+| Plan | Price | Each calendar month |
 |---|---|---|
-| **Audit Week** | **$3 once** for 7 days. No auto-renewal, one per account | Audit and recommendations: `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`. Katman shows what keeps assistants from reading, quoting and recommending your site, and what to do about it. It doesn't build pages or write site files. |
-| **Katman Pro** | **$29/month founding price** for the first 100 customers, locked while you stay subscribed (later $49/month), or **$290/year** | Everything in the Audit Week, plus the tools that build: prompts P0–P14 with acceptance checks (`katman_prompt` and the `katman://prompts/*` resources), `katman_page_brief`, `katman_generate`, `katman_indexnow`, `katman_setup_monitoring` and the katman.pro dashboard sync (`katman_sync`). |
+| **Katman Pro, 1 site** | **$49/month** | 1 site, 5 audits |
+| **Katman Pro, 3 sites** | **$88/month** | 3 sites, 30 audits |
 
-Choose a plan at https://katman.pro/pricing, then sign in at https://katman.pro/app → **MCP → Create key** and add the key to your MCP config (below). Without a key, or with a plan that doesn't cover a tool, the tool tells you what it would do for your project and how to get the right plan, instead of running. `katman_account` always works and shows your plan, the days left and how to upgrade.
+Every tool is in both plans, and so is the full course and the private community: `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`, the prompts P0–P14 with acceptance checks (`katman_prompt` and the `katman://prompts/*` resources), `katman_page_brief`, `katman_generate`, `katman_indexnow`, `katman_setup_monitoring` and the katman.pro dashboard sync (`katman_sync`).
+
+**What counts.** An audit is one run of `katman_audit_site` on a live site (or the CLI `audit`). Sites and audits are counted per calendar month (UTC): a site is a domain you audited that month. Re-reading earlier results, the other tools and visibility runs are not counted. Counts start again on the 1st. When the month's audits or sites are used up, `katman_audit_site` says so, shows when the counts start again and does not run; every other tool keeps working. `katman_account` shows what you have used this month.
+
+Choose a plan at https://katman.pro/pricing, then sign in at https://katman.pro/app → **MCP → Create key** and add the key to your MCP config (below). Without a key, or without an active plan, a tool tells you what it would do for your project and how to get the plan, instead of running. `katman_account` always works and shows your plan, this month's audits and sites, and how to upgrade.
+
+Accounts that bought an older plan keep what they bought: an Audit Week (no longer sold) until it ends, with the audit and recommendation tools, and an earlier Katman Pro subscription as it was, without these monthly limits.
 
 The Katman book and workbook PDFs are sold separately at https://katman.pro/guide; the MCP plans don't include them.
 
@@ -34,7 +40,7 @@ AI assistants recommend a site only when three gates are open:
 | **Quote** | The first 1–3 sentences answer the question on their own, with the same one sentence everywhere | Pages that open with "Welcome to…", llms.txt contradicting the pricing page |
 | **Fit** | There's a page for the situation the customer describes to the assistant | Pages named after the product instead of the customer's problem |
 
-Our own sample site, an AI-powered consumer web app we launched on 21 September 2026, went through these gates in its first week. It got **333 real ChatGPT visitors in 7 days**, and **11 of its 17 paying customers** came from ChatGPT. Source: the site's own analytics, human sessions only. The site is our own product, not a client. The full story is at https://katman.pro/case-studies/sample-site-first-7-days.
+Our own sample site, an AI-powered consumer web app we launched on 21 September 2026, went through these gates in its first week. It got **333 real ChatGPT visitors in 7 days**, and **11 of its 17 paying customers** came from ChatGPT (the site's own analytics, human sessions only, 21–27 September 2026). By 1 October 2026, **503 distinct visitors** had come from ChatGPT, about 416 after removing bots, with 40–90 a day since 23 September. The site is our own product, not a client. The full story is at https://katman.pro/case-studies/sample-site-first-7-days.
 
 ## Install
 
@@ -85,53 +91,53 @@ Open your project in your editor and tell your AI:
 
 > Use Katman to make this site recommendable by ChatGPT. Start with katman_start.
 
-Katman then walks your agent through four steps. The Audit Week covers steps 1 and 2, the checks of step 4 and the measurements; Katman Pro adds step 3 (building), IndexNow, monitoring and the dashboard sync:
+Katman then walks your agent through four steps:
 
 1. **Research** (`katman_research`): your one sentence (what the customer brings, what you do, what they get, which fear is unnecessary), a not-X note, 10–12 customer situations written without your brand name, competitors (with source and date), proof and a question set.
 2. **Plan** (`katman_scan_code`, `katman_audit_site`, `katman_plan`): a report of what's broken, with no code changes. Then a page plan and a task list ordered like a 30-day plan.
-3. **Build** (Pro: `katman_prompt` P0–P14, `katman_page_brief`, `katman_generate`): exact prompts for your AI, each with an acceptance criterion, plus generated robots.txt, llms.txt, JSON-LD and analytics snippets.
-4. **Verify** (`katman_audit_site`, `katman_lint_content`; Pro: `katman_indexnow`): Katman checks that each acceptance criterion is really met, then notifies search engines about new or changed URLs only.
+3. **Build** (`katman_prompt` P0–P14, `katman_page_brief`, `katman_generate`): exact prompts for your AI, each with an acceptance criterion, plus generated robots.txt, llms.txt, JSON-LD and analytics snippets.
+4. **Verify** (`katman_audit_site`, `katman_lint_content`, `katman_indexnow`): Katman checks that each acceptance criterion is really met, then notifies search engines about new or changed URLs only.
 
 Measure every 14 days with `katman_visibility_run` (API) or `katman_manual_check` (answers you paste from the ChatGPT/Claude/Perplexity apps).
 
 ## Tools
 
-"Audit Week" in the Plan column means the Audit Week or Katman Pro; "Pro" means Katman Pro only.
+Every tool is in both Katman Pro plans. Only `katman_audit_site` is counted: each run uses one audit of the month.
 
 | Tool | Plan | What it does | Writes |
 |---|---|---|---|
-| `katman_account` | Always | Your plan (none, Audit Week with the days left, or Pro), the tools it unlocks, masked account email, last key check, how to get a key or upgrade. Works without a key | — |
-| `katman_start` | Audit Week | Shows where you are in the method and the exact next call, with a one-line plan status. Without a plan: what Katman does, the two plans and how to set the key | `config.json` (site URL) |
-| `katman_research` | Audit Week | Research template, merge and validation, 12+2 question set | `research.json`, `research.md` |
-| `katman_keywords` | Audit Week | Google autocomplete expansion into situation and single-question page ideas (≤40 throttled requests) | `research.json` (optional) |
-| `katman_scan_code` | Audit Week | Framework, rendering (SSR/SSG/CSR), routes, head tags, robots/sitemap/llms.txt, JSON-LD, links, images, analytics | `scan.json` |
-| `katman_audit_site` | Audit Week | Live audit as AI crawlers see it: bot access through your CDN, JS-off text, 404s, canonicals, sitemap, hreflang, JSON-LD, internal links | `audits/`, `audit.md` |
-| `katman_plan` | Audit Week | Page plan and task list with P-codes and acceptance criteria (keeps your checkboxes) | `plan.json`, `plan.md` |
-| `katman_lint_content` | Audit Week | Checks a page against the content rules: answer-first, same one sentence, no hype, sourced numbers, FAQ, not-for, links | — |
-| `katman_visibility_run` | Audit Week | Asks your question set to ChatGPT, Claude, Gemini, Perplexity and Grok models with live web search via OpenRouter and your own key (API answers are a proxy for the consumer apps). Dry run and cost estimate first; presets economy/full/probe; `samples` for stability | `runs/`, `measurements.md` |
-| `katman_manual_check` | Audit Week | Records an answer you paste from a consumer app (logged out, search on); no API cost | `runs/`, `measurements.md` |
-| `katman_report` | Audit Week | Shareable report: gates, visibility deltas, competitors, cited domains, next 7 days | `report.md` |
-| `katman_prompt` | Pro | Prompt P0–P14 filled with your data, plus Accept / Why / How Katman verifies | — |
-| `katman_page_brief` | Pro | Brief for a situation, comparison, pricing, FAQ or about page, and where the file goes in your framework | — |
-| `katman_generate` | Pro | robots.txt, llms.txt, Organization/WebSite/SoftwareApplication/FAQ/Breadcrumb JSON-LD, AI-channel analytics snippet, server-side bot counter, IndexNow key | only with `write: true`, never overwrites without `overwrite: true` |
-| `katman_indexnow` | Pro | Submits only new or changed URLs to IndexNow, plus a Search Console / Bing / Brave checklist | `indexnow.json` |
-| `katman_setup_monitoring` | Pro | GitHub Actions workflow that re-measures weekly with your own keys | `.github/workflows/katman.yml` only with `write: true` |
-| `katman_sync` | Pro | Sends your progress to your katman.pro dashboard: gate pass counts, visibility rates by assistant and language, plan progress, top 10 issue titles, dates, Katman version. Never code, file contents, answers, questions or prompts. Dry run (the exact JSON) by default | — |
-
-Slash-command prompts: `katman-start`, `katman-audit`, `katman-situation-page`, `katman-measure` (each tool they call checks the plan). Resources: the method, the checklists and the content rules (Audit Week), this project's `research.md` (Audit Week) and the raw prompts `katman://prompts/P0`…`P14` (Pro).
+| `katman_account` | Always | Your plan (none, Katman Pro 1 site or 3 sites with this month's audits and sites used, or an older Audit Week with the days left), the tools it unlocks, masked account email, last key check, how to get a key or upgrade. Works without a key | — |
+| `katman_start` | Katman Pro | Shows where you are in the method and the exact next call, with a one-line plan status. Without a plan: what Katman does, the two plans and how to set the key | `config.json` (site URL) |
+| `katman_research` | Katman Pro | Research template, merge and validation, 12+2 question set | `research.json`, `research.md` |
+| `katman_keywords` | Katman Pro | Google autocomplete expansion into situation and single-question page ideas (≤40 throttled requests) | `research.json` (optional) |
+| `katman_scan_code` | Katman Pro | Framework, rendering (SSR/SSG/CSR), routes, head tags, robots/sitemap/llms.txt, JSON-LD, links, images, analytics | `scan.json` |
+| `katman_audit_site` | Katman Pro | Live audit as AI crawlers see it: bot access through your CDN, JS-off text, 404s, canonicals, sitemap, hreflang, JSON-LD, internal links. Counted: one run = one audit of the month. Re-read the last result in `audit.md` for free | `audits/`, `audit.md` |
+| `katman_plan` | Katman Pro | Page plan and task list with P-codes and acceptance criteria (keeps your checkboxes) | `plan.json`, `plan.md` |
+| `katman_lint_content` | Katman Pro | Checks a page against the content rules: answer-first, same one sentence, no hype, sourced numbers, FAQ, not-for, links | — |
+| `katman_visibility_run` | Katman Pro | Asks your question set to ChatGPT, Claude, Gemini, Perplexity and Grok models with live web search via OpenRouter and your own key (API answers are a proxy for the consumer apps). Dry run and cost estimate first; presets economy/full/probe; `samples` for stability | `runs/`, `measurements.md` |
+| `katman_manual_check` | Katman Pro | Records an answer you paste from a consumer app (logged out, search on); no API cost | `runs/`, `measurements.md` |
+| `katman_report` | Katman Pro | Shareable report: gates, visibility deltas, competitors, cited domains, next 7 days | `report.md` |
+| `katman_prompt` | Katman Pro | Prompt P0–P14 filled with your data, plus Accept / Why / How Katman verifies | — |
+| `katman_page_brief` | Katman Pro | Brief for a situation, comparison, pricing, FAQ or about page, and where the file goes in your framework | — |
+| `katman_generate` | Katman Pro | robots.txt, llms.txt, Organization/WebSite/SoftwareApplication/FAQ/Breadcrumb JSON-LD, AI-channel analytics snippet, server-side bot counter, IndexNow key | only with `write: true`, never overwrites without `overwrite: true` |
+| `katman_indexnow` | Katman Pro | Submits only new or changed URLs to IndexNow, plus a Search Console / Bing / Brave checklist | `indexnow.json` |
+| `katman_setup_monitoring` | Katman Pro | GitHub Actions workflow that re-measures weekly with your own keys | `.github/workflows/katman.yml` only with `write: true` |
+| `katman_sync` | Katman Pro | Sends your progress to your katman.pro dashboard: gate pass counts, visibility rates by assistant and language, plan progress, top 10 issue titles, dates, Katman version. Never code, file contents, answers, questions or prompts. Dry run (the exact JSON) by default | — |
+
+Slash-command prompts: `katman-start`, `katman-audit`, `katman-situation-page`, `katman-measure` (each tool they call checks the plan). Resources: the method, the checklists and the content rules, this project's `research.md` and the raw prompts `katman://prompts/P0`…`P14`.
 
 ## What Katman can and can't do
 
 - **Reads** files in your project, but skips `node_modules`, `.git` and build output, and **never** reads `.env*`, `.dev.vars*`, keys, certificates or credential files.
 - **Writes** only to `.katman/` in your project, except `katman_generate` and `katman_setup_monitoring` when you pass `write: true`.
-- **Network**: your own site (audits), `openrouter.ai` (visibility runs, with your key, after a dry run), `api.indexnow.org` (only when you submit), `suggestqueries.google.com` (only `katman_keywords`), and `katman.pro` only for two things: checking your `KATMAN_KEY` (at most once a day, and again when a plan ends; only when the key is set) and `katman_sync` (only with `dry_run: false`). **No telemetry**: without a key, nothing is sent to Katman; the key check sends only the key and the Katman version.
-- **Your keys** (`KATMAN_KEY`, `OPENROUTER_API_KEY`) are read from the environment and are never printed or written to disk. The licence check is cached in `~/.katman/license.json` under the key's SHA-256 hash (never the key); if katman.pro can't be reached, your plan keeps working for 7 days after the last successful check, never past the end of an Audit Week.
+- **Network**: your own site (audits), `openrouter.ai` (visibility runs, with your key, after a dry run), `api.indexnow.org` (only when you submit), `suggestqueries.google.com` (only `katman_keywords`), and `katman.pro` only for four things: checking your `KATMAN_KEY` (at most once a day, and again when a plan ends; only when the key is set), loading Katman's method (the prompts, page briefs and checklists; once per session, before the first tool your plan includes; it sends the key and the Katman version, and the method stays in memory, never on disk), counting an audit (right before each `katman_audit_site` run or CLI `audit`: it sends the key, the domain being audited and the Katman version, and nothing else) and `katman_sync` (only with `dry_run: false`). **No telemetry**: without a key, nothing is sent to Katman; the key check sends only the key and the Katman version. If katman.pro can't be reached when an audit is about to be counted, the audit runs anyway and its result says the count wasn't checked. The method itself needs katman.pro once per session: if it can't be reached then, the tool says so and you can try again.
+- **Your keys** (`KATMAN_KEY`, `OPENROUTER_API_KEY`) are read from the environment and are never printed or written to disk. The licence check is cached in `~/.katman/license.json` under the key's SHA-256 hash (never the key); if katman.pro can't be reached, your plan keeps working for 7 days after the last successful check, never past the end of an older Audit Week.
 - **No automation of consumer chat apps.** Katman doesn't drive chatgpt.com, claude.ai or perplexity.ai with a headless browser: their terms forbid programmatic extraction, and it gets accounts banned. It uses the providers' own web-search models through OpenRouter. For the consumer apps, you paste answers into `katman_manual_check`.
 - **No ranking guarantees.** A single measurement run is a small sample, so re-run the same questions every 14 days.
 
 ## Costs
 
-Katman itself: the Audit Week is $3 once for 7 days; Katman Pro is $29/month (founding price) or $290/year. On top of that, API visibility runs use your own OpenRouter credits (the same with either plan); search results are billed as input tokens, so they're not pennies:
+Katman itself: Katman Pro, 1 site is $49/month and Katman Pro, 3 sites is $88/month. On top of that, API visibility runs use your own OpenRouter credits (the same with either plan, and not counted as audits); search results are billed as input tokens, so they're not pennies:
 
 | Panel | What | Typical cost per run (14 questions) |
 |---|---|---|
@@ -144,18 +150,18 @@ The exact estimate is shown before anything runs, and `max_cost_usd` (default $3
 ## CLI
 
 ```bash
-npx -y katman-mcp account [--refresh]                     # always: your plan, days left, how to get a key
-npx -y katman-mcp scan [path]                             # Audit Week or Pro
-npx -y katman-mcp audit https://your.site --max 50        # Audit Week or Pro
-npx -y katman-mcp keywords "invoice software" --lang en   # Audit Week or Pro
-npx -y katman-mcp check --root . [--yes] [--max-cost 2]   # Audit Week or Pro: visibility run; dry run without --yes
-npx -y katman-mcp models                                  # Audit Week or Pro: the default visibility models and prices
-npx -y katman-mcp plan --root .                           # Audit Week or Pro
-npx -y katman-mcp report --root .                         # Audit Week or Pro
-npx -y katman-mcp indexnow --root . [--submit]            # Pro
+npx -y katman-mcp account [--refresh]                     # always: your plan, this month's audits and sites, how to get a key
+npx -y katman-mcp scan [path]
+npx -y katman-mcp audit https://your.site --max 50        # counted: one run = one audit of the month
+npx -y katman-mcp keywords "invoice software" --lang en
+npx -y katman-mcp check --root . [--yes] [--max-cost 2]   # visibility run; dry run without --yes
+npx -y katman-mcp models                                  # the default visibility models and prices
+npx -y katman-mcp plan --root .
+npx -y katman-mcp report --root .
+npx -y katman-mcp indexnow --root . [--submit]
 ```
 
-Every command except `account`, `--help` and `--version` reads `KATMAN_KEY` from the environment (`KATMAN_KEY=km_live_... npx -y katman-mcp report --root .`; in GitHub Actions, a repository secret) and, without a plan that covers it, exits with code 4 and a short explanation.
+Every command except `account`, `--help` and `--version` reads `KATMAN_KEY` from the environment (`KATMAN_KEY=km_live_... npx -y katman-mcp report --root .`; in GitHub Actions, a repository secret) and, without an active plan (or when `audit` finds the month's audits or sites used up), exits with code 4 and a short explanation. A scheduled `audit` (a CI job, the workflow from `katman_setup_monitoring`) uses one audit per run: weekly is 4–5 a month.
 
 ## Files
 

package/dist/license.js

@@ -1,14 +1,18 @@
 // 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.
+// 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.
+//   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
@@ -21,6 +25,7 @@ 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 { 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) {
@@ -62,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 {
@@ -77,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) {
@@ -97,11 +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). 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.
+ * 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 = 2;
+const CACHE_CONTRACT = 3;
 export function defaultCacheFile() {
     return path.join(os.homedir(), ".katman", "license.json");
 }
@@ -152,6 +163,38 @@ function toIso(x) {
         return new Date(x < 1e12 ? x * 1000 : x).toISOString();
     return undefined;
 }
+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
@@ -179,6 +222,10 @@ export function parseVerify(res) {
         const account = j.account && typeof j.account === "object" ? j.account : {};
         const emailMasked = typeof account.emailMasked === "string" ? account.emailMasked.slice(0, 120) : undefined;
         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: {
@@ -187,6 +234,10 @@ export function parseVerify(res) {
                 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 } : {}),
             },
         };
@@ -247,6 +298,11 @@ export function createLicenseProvider(deps = {}) {
             ...(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: nextCheck(g),
@@ -266,6 +322,9 @@ export function createLicenseProvider(deps = {}) {
             return false; // unparsable or in the future (clock change): check again
         if (!e.result.ok)
             return age < REJECTED_TTL_S * 1000;
+        // "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)
@@ -333,6 +392,18 @@ 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,
@@ -360,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))
@@ -415,7 +554,8 @@ export function licenseOf(ctx) {
 }
 // ---------------------------------------------------------------------------------------------------------------
 // Gate
-async function statusOf(provider) {
+/** The provider's status; a provider that throws counts as unreachable. */
+export async function statusOf(provider) {
     try {
         return await provider.status();
     }
@@ -425,7 +565,41 @@ async function statusOf(provider) {
 }
 export async function requireFeature(feature, provider) {
     const status = await statusOf(provider);
-    return { allowed: allows(status, feature), status };
+    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 {
+}
+/**
+ * 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
@@ -449,12 +623,24 @@ export function withPlan(ctx, feature, handler) {
         return ok(renderUpsell({ tool, feature, status: gate.status, facts, args: a, surface: "mcp" }), upsellStructured(tool, feature, gate.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 {
+        return await provider.useAudit(domain);
+    }
+    catch (e) {
+        return { allowed: true, unchecked: true, error: e instanceof Error ? e.message.slice(0, 120) : "error" };
+    }
+}
 /** 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 {
-        allowed: allows(status, "start"),
+        allowed,
         status,
         line: statusLine(status),
         notice: (tool) => {
@@ -467,6 +653,9 @@ export async function startLicense(ctx) {
             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 } : {}),
         },
     };
 }

package/dist/meta.js

@@ -1,19 +1,31 @@
-export const VERSION = "0.2.0";
+export const VERSION = "0.3.0";
 export const HOMEPAGE = "https://katman.pro";
-/** Plans (docs/07-APP-SPEC.md §1): nothing is free. Audit Week = $3 once for 7 days; Katman Pro = the founding price. */
+/**
+ * Plans (docs/07-APP-SPEC.md §1): nothing is free. Katman Pro, 1 site = $49/month (1 site, 5 audits a month); Katman Pro,
+ * 3 sites = $88/month (3 sites, 30 audits a month); both include every tool. The Audit Week ($3 once, 7 days) is no
+ * longer sold; the package still recognises it for accounts that bought it.
+ */
 export const APP_URL = `${HOMEPAGE}/app`;
 export const KEYS_URL = `${APP_URL}/mcp`;
 export const BILLING_URL = `${APP_URL}/billing`;
+/** The billing page opened on one plan (product ids pro_1 / pro_3); signed-out people are asked to log in first. */
+export const BUY_PRO_1_URL = `${BILLING_URL}?buy=pro_1`;
+export const BUY_PRO_3_URL = `${BILLING_URL}?buy=pro_3`;
 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";
-/** 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";
+export const PRO_1_PRICE = "$49/month";
+export const PRO_3_PRICE = "$88/month";
+/** Katman Pro, 1 site, in one phrase. */
+export const PRO_1_NOTE = "Katman Pro, 1 site $49/month (1 site, 5 audits a month)";
+/** Katman Pro, 3 sites, in one phrase. */
+export const PRO_3_NOTE = "Katman Pro, 3 sites $88/month (3 sites, 30 audits a month)";
+/** Both plans in one phrase. */
+export const PRO_PRICE_NOTE = `${PRO_1_NOTE} or ${PRO_3_NOTE}; both include every tool`;
+export const PRO_PRICE_NOTE_TR = "Katman Pro, 1 site ayda 49 $ (1 site, ayda 5 denetim) ya da Katman Pro, 3 site ayda 88 $ (3 site, ayda 30 denetim); ikisinde de tüm araçlar var";
+/** How audits are counted: the same sentence as katman.pro/pricing (en and tr). */
+export const AUDIT_COUNT_NOTE = "An audit is one run of katman_audit_site on a live site. Sites and audits are counted per calendar month (UTC): a site is a domain you audited that month. Re-reading earlier results, the other tools and visibility runs are not counted.";
+export const AUDIT_COUNT_NOTE_TR = "Denetim, canlı bir sitede katman_audit_site’ın bir çalıştırmasıdır. Siteler ve denetimler her takvim ayı (UTC) için sayılır: site, o ay denetlediğiniz bir alan adıdır. Önceki sonuçları yeniden okumak, diğer araçlar ve görünürlük ölçümleri sayılmaz.";
 /** 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.
 
@@ -22,10 +34,10 @@ 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.
 
-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.
+Plans: every tool except katman_account needs KATMAN_KEY with an active Katman Pro plan in the MCP config. Katman Pro, 1 site ($49/month: 1 site, 5 audits a month) and Katman Pro, 3 sites ($88/month: 3 sites, 30 audits a month) both include every tool: 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, katman_prompt (P0–P14), katman_page_brief, katman_generate, katman_indexnow, katman_setup_monitoring and katman_sync.
+An audit is one run of katman_audit_site, counted per calendar month; a site is a domain audited that month. Re-reading earlier results (.katman/audit.md) and every other tool are not counted. Each katman_audit_site run uses one of the user's audits, so don't repeat it without a reason; use the saved result instead.
+Accounts with an older Audit Week (no longer sold) keep it until it ends: the audit and recommendation tools only; the page-building tools return an upgrade note.
+Without the right plan, or when this month's audits or sites are used up, a tool returns a short explanation instead of running: pass it on to the user. katman_account always works and shows the plan, this month's audits and sites, 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:

package/dist/plans.js

@@ -1,9 +1,16 @@
 // 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. */
+//
+// Sold: Katman Pro, 1 site ($49/month: 1 site, 5 audits a month) and Katman Pro, 3 sites ($88/month: 3 sites, 30
+// audits a month). Both include every tool. The Audit Week ($3, 7 days) is no longer sold; the plan stays here for
+// accounts that bought it, and so do the accounts that never had limits (the older $29 Katman Pro, admin grants).
+/** The limits of the two plans on sale (katman.pro's answer is what counts; these only name a plan from its limits). */
+export const PRO_1_LIMITS = { sites: 1, auditsPerMonth: 5 };
+export const PRO_3_LIMITS = { sites: 3, auditsPerMonth: 30 };
+/** The audit tier: audit and recommendations. What an Audit Week (no longer sold) covers; 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. */
+/** Katman Pro: the audit tier plus the tools that build pages and keep things running (every tool). */
 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 = {
@@ -26,11 +33,11 @@ export const TOOL_FEATURES = {
 };
 /** 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 audit-tier tool. */
+export const AUDIT_NOTE = " (Katman 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). */
+/** True for the features only Katman Pro unlocks (not in the older Audit Week). */
 export function isProOnly(feature) {
     return !AUDIT_FEATURES.includes(feature);
 }
@@ -41,7 +48,7 @@ export function tierNote(feature) {
 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. */
+/** The tools of one tier: "audit" = the audit tier (what an Audit Week covers; 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"));
 }