katman-mcp 0.1.0 → 0.2.0

package/README.md

@@ -11,13 +11,16 @@ 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.
+
 | Plan | Price | What you get |
 |---|---|---|
-| **Free** | $0, no account, no key | The diagnosis: `katman_start`, `katman_research`, `katman_scan_code`, `katman_audit_site`, `katman_keywords`, `katman_account`. Katman shows what keeps assistants from reading, quoting and recommending your site. |
-| **7-day trial** | $0, no card | Everything in Katman Pro. Starts when you create your account at https://katman.pro/app. |
-| **Katman Pro** | **$29/month founding price** (first 100 customers, locked in) | The treatment: the plan, prompts P0–P14 with acceptance checks, page briefs, generators, content lint, AI-visibility runs, manual checks, IndexNow, reports, monitoring and the katman.pro dashboard sync. |
+| **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`). |
+
+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.
 
-Pro tools need `KATMAN_KEY` in your MCP config: sign in at https://katman.pro/app → **MCP → Create key**. Without a key, a Pro tool tells you what it would do for your project and how to start the trial, instead of running. `katman_account` shows your plan at any time.
+The Katman book and workbook PDFs are sold separately at https://katman.pro/guide; the MCP plans don't include them.
 
 ---
 
@@ -35,16 +38,16 @@ Our own sample site, an AI-powered consumer web app we launched on 21 September
 
 ## Install
 
-Katman runs locally with `npx`. Both keys are optional:
+Katman runs locally with `npx`. It reads two keys from its environment:
 
-- `KATMAN_KEY` (`km_live_…`) unlocks the Pro tools. Get it at https://katman.pro/app → **MCP → Create key** (7-day free trial, no card). The free tools work without it.
-- `OPENROUTER_API_KEY` is only for AI-visibility runs through APIs, paid with your own OpenRouter credits.
+- `KATMAN_KEY` (`km_live_…`), **required**: your licence key. Get it at https://katman.pro/app → **MCP → Create key** once you have a plan (https://katman.pro/pricing). Step by step for each editor: https://katman.pro/docs/getting-started.
+- `OPENROUTER_API_KEY`, optional: only for AI-visibility runs through APIs, paid with your own OpenRouter credits.
 
 **Claude Code**
 ```bash
 claude mcp add katman --scope user -e KATMAN_KEY=km_live_... -e OPENROUTER_API_KEY=sk-or-... -- npx -y katman-mcp
 ```
-Already added without a key? Run `claude mcp remove katman --scope user` first. With the Katman Claude Code plugin, set its `katman_key` and `openrouter_api_key` options instead.
+Already added without a key? Run `claude mcp remove katman --scope user` first. With the Katman Claude Code plugin, set its `katman_key` and `openrouter_api_key` options instead (`/plugin configure katman@katman`).
 
 **Cursor**: add this to `~/.cursor/mcp.json` (your user file, so the key never lands in a repository), or use the "Add to Cursor" button on https://katman.pro/mcp.
 ```json
@@ -55,7 +58,7 @@ Already added without a key? Run `claude mcp remove katman --scope user` first.
 ```json
 {
   "inputs": [
-    { "type": "promptString", "id": "katman_key", "description": "Katman key from katman.pro/app (optional)", "password": true },
+    { "type": "promptString", "id": "katman_key", "description": "Katman key from katman.pro/app/mcp", "password": true },
     { "type": "promptString", "id": "openrouter_api_key", "description": "OpenRouter API key (optional)", "password": true }
   ],
   "servers": { "katman": { "type": "stdio", "command": "npx", "args": ["-y", "katman-mcp"], "env": { "KATMAN_KEY": "${input:katman_key}", "OPENROUTER_API_KEY": "${input:openrouter_api_key}" } } }
@@ -82,51 +85,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. Step 1 and the diagnosis in step 2 (scan and audit) are free; the rest is Katman Pro:
+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:
 
 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** (`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.
+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.
 
 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.
+
 | Tool | Plan | What it does | Writes |
 |---|---|---|---|
-| `katman_start` | Free | Shows where you are in the method and the exact next call (plus a one-line plan status when `KATMAN_KEY` is set) | `config.json` (site URL) |
-| `katman_research` | Free | Research template, merge and validation, 12+2 question set | `research.json`, `research.md` |
-| `katman_keywords` | Free | Google autocomplete expansion into situation and single-question page ideas (≤40 throttled requests) | `research.json` (optional) |
-| `katman_scan_code` | Free | Framework, rendering (SSR/SSG/CSR), routes, head tags, robots/sitemap/llms.txt, JSON-LD, links, images, analytics | `scan.json` |
-| `katman_audit_site` | Free | 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_account` | Free | Your plan (free, trial days left, Pro), features, masked account email, last key check, how to connect or upgrade | — |
-| `katman_plan` | Pro | Page plan and task list with P-codes and acceptance criteria (keeps your checkboxes) | `plan.json`, `plan.md` |
+| `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_lint_content` | Pro | Checks a page against the content rules: answer-first, same one sentence, no hype, sourced numbers, FAQ, not-for, links | — |
-| `katman_visibility_run` | Pro | Asks your question set to ChatGPT, Claude, Gemini, Perplexity and Grok models with live web search via OpenRouter (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` | Pro | Records an answer you paste from a consumer app (logged out, search on); no API cost | `runs/`, `measurements.md` |
 | `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_report` | Pro | Shareable report: gates, visibility deltas, competitors, cited domains, next 7 days | `report.md` |
 | `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`.
+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).
 
 ## 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, 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 license check is cached in `~/.katman/license.json` under the key's SHA-256 hash (never the key); if katman.pro can't be reached, Pro keeps working for 7 days after the last successful check.
+- **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.
 - **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 diagnosis is free; Katman Pro is $29/month (founding price) after a 7-day free trial. On top of that, API visibility runs use your own OpenRouter credits; search results are billed as input tokens, so they're not pennies:
+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:
 
 | Panel | What | Typical cost per run (14 questions) |
 |---|---|---|
@@ -139,21 +144,22 @@ The exact estimate is shown before anything runs, and `max_cost_usd` (default $3
 ## CLI
 
 ```bash
-npx -y katman-mcp scan [path]                             # free
-npx -y katman-mcp audit https://your.site --max 50        # free
-npx -y katman-mcp keywords "invoice software" --lang en   # free
-npx -y katman-mcp account [--refresh]                     # free: your plan
-npx -y katman-mcp indexnow --root . [--submit]            # dry run free; --submit is Pro
-npx -y katman-mcp check --root . [--yes] [--max-cost 2]   # Pro: visibility run; dry run without --yes
-npx -y katman-mcp plan --root .                           # Pro
-npx -y katman-mcp report --root .                         # Pro
+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
 ```
 
-Pro commands read `KATMAN_KEY` from the environment (`KATMAN_KEY=km_live_... npx -y katman-mcp report --root .`; in GitHub Actions, a repository secret) and exit with code 4 and a short explanation without it.
+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.
 
 ## Files
 
-Everything Katman learns about your project lives in `.katman/`: `research.json`/`.md`, `scan.json`, `audits/`, `runs/`, `measurements.md`, `plan.md`, `report.md`, `log.md`. It contains no secrets, and it's worth committing, because it's the history of what you changed and what happened. The only file outside the project is the license cache `~/.katman/license.json` (key hash, plan, last check).
+Everything Katman learns about your project lives in `.katman/`: `research.json`/`.md`, `scan.json`, `audits/`, `runs/`, `measurements.md`, `plan.md`, `report.md`, `log.md`. It contains no secrets, and it's worth committing, because it's the history of what you changed and what happened. The only file outside the project is the licence cache `~/.katman/license.json` (key hash, plan, plan end, last check).
 
 ---
 

package/dist/cli.js

@@ -5,35 +5,48 @@ import * as method from "./tools/method/cli.js";
 import * as crawl from "./tools/crawl/cli.js";
 import * as visibility from "./tools/visibility/cli.js";
 import * as account from "./tools/account/cli.js";
-import { EXIT_NEEDS_PRO, cliFeature, defaultLicense, requirePro, toolForFeature } from "./license.js";
+import { EXIT_NEEDS_PLAN, OPEN_COMMANDS, cliFeature, defaultLicense, requireFeature, toolForFeature } from "./license.js";
 import { projectFacts, renderUpsell } from "./tools/account/upsell.js";
+/** Every CLI command by name (built on call: the module CLIs import this file). */
+export function cliCommands() {
+    return { ...method.commands, ...crawl.commands, ...visibility.commands, ...account.commands };
+}
 export async function runCli(args, deps = {}) {
     const [cmd, ...rest] = args;
     if (cmd === "--version" || cmd === "-v" || cmd === "version") {
         console.log(VERSION);
         return 0;
     }
-    const all = { ...method.commands, ...crawl.commands, ...visibility.commands, ...account.commands };
-    const fn = all[cmd];
-    if (!fn) {
+    const all = cliCommands();
+    const fn = cmd !== undefined && Object.hasOwn(all, cmd) ? all[cmd] : undefined;
+    // --help anywhere only prints the help: it never runs a command, so it can't get past the gate.
+    if (!fn || rest.includes("--help") || rest.includes("-h")) {
         printHelp();
-        return cmd === "help" || cmd === "--help" || cmd === "-h" ? 0 : 1;
+        return fn || cmd === "help" || cmd === "--help" || cmd === "-h" ? 0 : 1;
     }
-    // Katman Pro commands (plan, report, check, indexnow --submit): same gate as the MCP tools.
-    const feature = cliFeature(cmd, rest);
-    if (feature) {
-        const gate = await requirePro(feature, deps.license ?? defaultLicense());
+    // Every command except account needs a plan with its feature: the same gate as the MCP tools.
+    if (!OPEN_COMMANDS.includes(cmd)) {
+        const feature = cliFeature(cmd);
+        if (!feature) {
+            console.error(`katman-mcp ${cmd}: no licence rule for this command.`);
+            return EXIT_NEEDS_PLAN;
+        }
+        const gate = await requireFeature(feature, deps.license ?? defaultLicense());
         if (!gate.allowed) {
             const { _, flags } = parseArgs(rest);
-            const root = path.resolve(typeof flags.root === "string" ? flags.root : cmd === "plan" || cmd === "report" ? (_[0] ?? process.cwd()) : process.cwd());
-            const facts = await projectFacts(root).catch(() => undefined);
-            const command = `katman-mcp ${cmd}${cmd === "indexnow" ? " --submit" : ""}`;
-            console.error(renderUpsell({ tool: toolForFeature(feature), feature, status: gate.status, facts, surface: "cli", command }));
-            return EXIT_NEEDS_PRO;
+            const rootArg = typeof flags.root === "string" ? flags.root : cmd === "scan" || cmd === "plan" || cmd === "report" ? _[0] : undefined;
+            const facts = await projectFacts(path.resolve(rootArg ?? process.cwd())).catch(() => undefined);
+            const example = ["katman-mcp", cmd, ...rest].map(shellWord).join(" ");
+            console.error(renderUpsell({ tool: toolForFeature(feature), feature, status: gate.status, facts, surface: "cli", command: `katman-mcp ${cmd}`, example }));
+            return EXIT_NEEDS_PLAN;
         }
     }
     return fn(rest, deps);
 }
+/** Quote an argument for the "run it again with the key" example when the shell would split or expand it. */
+function shellWord(a) {
+    return /^[\w./:@%+,=-]+$/.test(a) ? a : `'${a.replace(/'/g, `'\\''`)}'`;
+}
 function printHelp() {
     const lines = [
         `katman-mcp ${VERSION} — make your site readable, quotable and recommendable by AI assistants`,