@kivimedia/kmhub 2.9.1 → 2.11.0

package/index.mjs

@@ -1,57 +1,57 @@
-#!/usr/bin/env node
-/**
- * kmhub-mcp (C9) - a standalone LOCAL (stdio) MCP server that wraps the KM Hub public
- * REST API (the kmhub-api edge function) as MCP tools. Any MCP client (Claude Desktop,
- * Claude Code, IDEs) can then read your queue and create leads, authenticated with a
- * single KM Hub API key from the environment.
- *
- * For the multi-tenant, zero-local-install variant (one VPS process serving many orgs
- * over Streamable HTTP, each request scoped by its own Bearer token), see remote.mjs.
- *
- * Setup:
- *   1. In KM Hub: Settings > Developer & API > create an API key (kmh_live_...).
- *   2. npm install (in this folder).
- *   3. Add to your MCP client config with env KMHUB_API_KEY=kmh_live_...
- *
- * Env:
- *   KMHUB_API_KEY   required, the org's key
- *   KMHUB_API_BASE  override the kmhub-api base URL
- *   KMHUB_PROFILE   which tool families to load: core, outreach, money, content, full.
- *                   Default full (everything). A narrower profile means fewer tool
- *                   schemas in every turn, which is real context back for the model.
- *
- * One org-scoped auth substrate: the same key + routes the Telegram bot / Zapier use.
- */
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { registerPrompts } from './prompts.mjs';
-import {
-  DEFAULT_BASE,
-  SERVER_NAME,
-  SERVER_VERSION,
-  makeCaller,
-  registerTools,
-  resolveProfile,
-} from './tools.mjs';
-
-const BASE = DEFAULT_BASE;
-const KEY = process.env.KMHUB_API_KEY;
-if (!KEY) {
-  console.error('kmhub-mcp: set KMHUB_API_KEY (create one in KM Hub > Settings > Developer & API).');
-  process.exit(1);
-}
-
-// An unknown KMHUB_PROFILE falls back to full rather than failing to start: a typo in
-// a config file should never cost someone their whole toolset.
-const PROFILE = resolveProfile(process.env.KMHUB_PROFILE);
-
-const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
-const { families, tools } = registerTools(server, makeCaller(BASE, KEY), { profile: PROFILE });
-const prompts = registerPrompts(server);
-
-const transport = new StdioServerTransport();
-await server.connect(transport);
-console.error(
-  `kmhub-mcp ${SERVER_VERSION}: connected (stdio), profile '${PROFILE}' ` +
-    `(families: ${families.join(', ')}). Tools: ${tools.join(', ')}.`,
-);
+#!/usr/bin/env node
+/**
+ * kmhub-mcp (C9) - a standalone LOCAL (stdio) MCP server that wraps the KM Hub public
+ * REST API (the kmhub-api edge function) as MCP tools. Any MCP client (Claude Desktop,
+ * Claude Code, IDEs) can then read your queue and create leads, authenticated with a
+ * single KM Hub API key from the environment.
+ *
+ * For the multi-tenant, zero-local-install variant (one VPS process serving many orgs
+ * over Streamable HTTP, each request scoped by its own Bearer token), see remote.mjs.
+ *
+ * Setup:
+ *   1. In KM Hub: Settings > Developer & API > create an API key (kmh_live_...).
+ *   2. npm install (in this folder).
+ *   3. Add to your MCP client config with env KMHUB_API_KEY=kmh_live_...
+ *
+ * Env:
+ *   KMHUB_API_KEY   required, the org's key
+ *   KMHUB_API_BASE  override the kmhub-api base URL
+ *   KMHUB_PROFILE   which tool families to load: core, outreach, money, content, full.
+ *                   Default full (everything). A narrower profile means fewer tool
+ *                   schemas in every turn, which is real context back for the model.
+ *
+ * One org-scoped auth substrate: the same key + routes the Telegram bot / Zapier use.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerPrompts } from './prompts.mjs';
+import {
+  DEFAULT_BASE,
+  SERVER_NAME,
+  SERVER_VERSION,
+  makeCaller,
+  registerTools,
+  resolveProfile,
+} from './tools.mjs';
+
+const BASE = DEFAULT_BASE;
+const KEY = process.env.KMHUB_API_KEY;
+if (!KEY) {
+  console.error('kmhub-mcp: set KMHUB_API_KEY (create one in KM Hub > Settings > Developer & API).');
+  process.exit(1);
+}
+
+// An unknown KMHUB_PROFILE falls back to full rather than failing to start: a typo in
+// a config file should never cost someone their whole toolset.
+const PROFILE = resolveProfile(process.env.KMHUB_PROFILE);
+
+const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+const { families, tools } = registerTools(server, makeCaller(BASE, KEY), { profile: PROFILE });
+const prompts = registerPrompts(server);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(
+  `kmhub-mcp ${SERVER_VERSION}: connected (stdio), profile '${PROFILE}' ` +
+    `(families: ${families.join(', ')}). Tools: ${tools.join(', ')}.`,
+);

package/package.json

@@ -1,56 +1,56 @@
-{
-  "name": "@kivimedia/kmhub",
-  "version": "2.9.1",
-  "description": "KM Hub Terminal Mode. Installs the KM Hub MCP connector into your own Claude Code on your own machine, and ships the kmhub CLI that registers, updates and diagnoses it.",
-  "keywords": [
-    "kmhub",
-    "kivimedia",
-    "mcp",
-    "model-context-protocol",
-    "claude-code",
-    "terminal-mode",
-    "crm"
-  ],
-  "homepage": "https://hub.kivimedia.co",
-  "license": "UNLICENSED",
-  "author": "Kivi Media (https://hub.kivimedia.co)",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/kivimedia/kmhub.git",
-    "directory": "mcp-server"
-  },
-  "type": "module",
-  "engines": {
-    "node": ">=18.17"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "bin": {
-    "kmhub": "bin/kmhub.mjs",
-    "kmhub-mcp": "index.mjs",
-    "kmhub-mcp-remote": "remote.mjs"
-  },
-  "files": [
-    "bin/kmhub.mjs",
-    "index.mjs",
-    "remote.mjs",
-    "tools.mjs",
-    "coach-book-output-guard.mjs",
-    "tools/*.mjs",
-    "prompts.mjs",
-    "prompts/*.md",
-    "read-only-tools.json"
-  ],
-  "scripts": {
-    "start": "node index.mjs",
-    "start:remote": "node remote.mjs",
-    "check:version": "node -e \"const fs=require('fs');const p=JSON.parse(fs.readFileSync('package.json','utf8'));const t=fs.readFileSync('tools.mjs','utf8');const m=t.match(/SERVER_VERSION\\s*=\\s*'([^']+)'/);if(!m){console.error('kmhub: could not find SERVER_VERSION in tools.mjs, so the two identities cannot be compared.');process.exit(1)}if(m[1]!==p.version){console.error('kmhub: version mismatch. package.json is '+p.version+' and tools.mjs SERVER_VERSION is '+m[1]+'. Make them the same string in one commit, then publish.');process.exit(1)}console.log('kmhub: version check ok, both say '+p.version)\"",
-    "prepublishOnly": "npm run check:version"
-  },
-  "dependencies": {
-    "@hono/node-server": "1.19.15",
-    "@modelcontextprotocol/sdk": "^1.30.0",
-    "zod": "^3.23.8"
-  }
-}
+{
+  "name": "@kivimedia/kmhub",
+  "version": "2.11.0",
+  "description": "KM Hub Terminal Mode. Installs the KM Hub MCP connector into your own Claude Code on your own machine, and ships the kmhub CLI that registers, updates and diagnoses it.",
+  "keywords": [
+    "kmhub",
+    "kivimedia",
+    "mcp",
+    "model-context-protocol",
+    "claude-code",
+    "terminal-mode",
+    "crm"
+  ],
+  "homepage": "https://hub.kivimedia.co",
+  "license": "UNLICENSED",
+  "author": "Kivi Media (https://hub.kivimedia.co)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kivimedia/kmhub.git",
+    "directory": "mcp-server"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=18.17"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "kmhub": "bin/kmhub.mjs",
+    "kmhub-mcp": "index.mjs",
+    "kmhub-mcp-remote": "remote.mjs"
+  },
+  "files": [
+    "bin/kmhub.mjs",
+    "index.mjs",
+    "remote.mjs",
+    "tools.mjs",
+    "coach-book-output-guard.mjs",
+    "tools/*.mjs",
+    "prompts.mjs",
+    "prompts/*.md",
+    "read-only-tools.json"
+  ],
+  "scripts": {
+    "start": "node index.mjs",
+    "start:remote": "node remote.mjs",
+    "check:version": "node -e \"const fs=require('fs');const p=JSON.parse(fs.readFileSync('package.json','utf8'));const t=fs.readFileSync('tools.mjs','utf8');const m=t.match(/SERVER_VERSION\\s*=\\s*'([^']+)'/);if(!m){console.error('kmhub: could not find SERVER_VERSION in tools.mjs, so the two identities cannot be compared.');process.exit(1)}if(m[1]!==p.version){console.error('kmhub: version mismatch. package.json is '+p.version+' and tools.mjs SERVER_VERSION is '+m[1]+'. Make them the same string in one commit, then publish.');process.exit(1)}console.log('kmhub: version check ok, both say '+p.version)\"",
+    "prepublishOnly": "npm run check:version"
+  },
+  "dependencies": {
+    "@hono/node-server": "1.19.15",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^3.23.8"
+  }
+}

package/prompts/briefing.md

@@ -1,29 +1,29 @@
----
-description: "The KM Hub day briefing: what needs you today, ranked, with the reason each thing is on the list. Use for /kmhub-briefing, or when the user says what needs me today, what have I got on, morning, catch me up, where are we, what should I do first, anything urgent, what did I miss, or opens a session with no specific task."
-disable-model-invocation: false
----
-
-# The KM Hub briefing
-
-Call `km_briefing`. Answer from what it returns. That single call already replaces `km_waiting` plus `km_list_outreach_drafts` plus `km_list_outreach_replies` plus `km_list_tasks` plus `km_list_invoices` plus `km_my_schedule`, so do not run those first and do not run them afterwards to check its work.
-
-## Read it out in this shape
-
-1. **The headline.** It is written to be said out loud. Say it.
-2. **The ranked list**, in the order it came back. Each item carries a plain `why`. Use it. "This has been sitting 47 days and sends nothing until you release it" is the whole point; "draft pending" is not.
-3. **The diary**, including anything only pencilled in with nothing signed behind it. A free day is worth saying out loud too.
-4. **Money that is already late**, if there is any.
-
-## Do not re-sort it
-
-The ranking is deliberate. A new enquiry nobody has answered and a reply nobody has handled sit near the top because they stop being worth anything if left. Late money worth a real amount outranks something merely unread. A gig today is high, but as a fact to absorb, not a decision to make. Every item carries `score` so the order is inspectable. Work down it.
-
-## Before you finish
-
-- Read the `notes` array and the `complete` flag. When a part of the workspace could not be read, the briefing says which part. Pass that on rather than presenting a partial day as the whole day.
-- `counts.truncated` means there was more than you were shown. Say how many.
-- If `suggested_play` came back, offer it in one line and name `/kmhub-play`. Offer it; do not start it.
-
-## Then stop
-
-The briefing is a briefing. Do not start working the list, draft anything, or change a record because an item looked urgent. Wait to be asked.
+---
+description: "The KM Hub day briefing: what needs you today, ranked, with the reason each thing is on the list. Use for /kmhub-briefing, or when the user says what needs me today, what have I got on, morning, catch me up, where are we, what should I do first, anything urgent, what did I miss, or opens a session with no specific task."
+disable-model-invocation: false
+---
+
+# The KM Hub briefing
+
+Call `km_briefing`. Answer from what it returns. That single call already replaces `km_waiting` plus `km_list_outreach_drafts` plus `km_list_outreach_replies` plus `km_list_tasks` plus `km_list_invoices` plus `km_my_schedule`, so do not run those first and do not run them afterwards to check its work.
+
+## Read it out in this shape
+
+1. **The headline.** It is written to be said out loud. Say it.
+2. **The ranked list**, in the order it came back. Each item carries a plain `why`. Use it. "This has been sitting 47 days and sends nothing until you release it" is the whole point; "draft pending" is not.
+3. **The diary**, including anything only pencilled in with nothing signed behind it. A free day is worth saying out loud too.
+4. **Money that is already late**, if there is any.
+
+## Do not re-sort it
+
+The ranking is deliberate. A new enquiry nobody has answered and a reply nobody has handled sit near the top because they stop being worth anything if left. Late money worth a real amount outranks something merely unread. A gig today is high, but as a fact to absorb, not a decision to make. Every item carries `score` so the order is inspectable. Work down it.
+
+## Before you finish
+
+- Read the `notes` array and the `complete` flag. When a part of the workspace could not be read, the briefing says which part. Pass that on rather than presenting a partial day as the whole day.
+- `counts.truncated` means there was more than you were shown. Say how many.
+- If `suggested_play` came back, offer it in one line and name `/kmhub-play`. Offer it; do not start it.
+
+## Then stop
+
+The briefing is a briefing. Do not start working the list, draft anything, or change a record because an item looked urgent. Wait to be asked.

package/prompts/luxury.md

@@ -1,70 +1,70 @@
----
-description: "Explain and run the luxury plays: the brand and pricing family built from The Luxury Strategy. Use for /kmhub-luxury, or when the user asks what the luxury plays are, which one to run first, in what order, or says their prices feel too low, their website undersells them, they are thinking of discounting, adding a service, or wondering what to say about price on a call."
-argument-hint: nothing for the tour, or the play to run
-disable-model-invocation: false
----
-
-# The luxury plays
-
-Fifteen plays in the catalog carry the method from The Luxury Strategy by Kapferer and
-Bastien. They are about what a business charges, what it says, and who it says it to.
-
-The user typed `$ARGUMENTS`. If that names a play, run it with `km_play_run`. If it is empty,
-give the tour below in your own words, keep it short, and end by offering to run the first one.
-
-## The idea the whole family rests on
-
-The book's first claim is that luxury, premium and fashion are three different businesses,
-not three points on one scale, and that mixing their rules is what costs money.
-
-- **Luxury** never compares itself, sets its own price, and makes buying it take effort.
-- **Premium** is comparative: pay more, get more, and the price is justified by what it does.
-- **Fashion** runs on trends and speed.
-
-Most businesses here are premium, and that is a legitimate place to be. It is not a lesser
-answer, it is a different rulebook. The owner picks which one they want to run.
-
-## An optional second opinion
-
-`luxury-positioning-check` reads the real offers, prices, win rate, diary and past clients,
-then says which of the three the evidence shows today. It is advice, not a gate: nothing else
-waits for it. If the owner wants luxury, every play runs full luxury rules, whatever the check
-said, and the check can record that choice. With no verdict on file, the plays ask once
-"luxury or premium rules?" or default to luxury.
-
-## A sensible order
-
-1. `brand-archaeology` - what this brand actually is: its story, its icons, the signatures that
-   should appear everywhere.
-2. `offer-ladder-architect` - the shape of the range: one signature offer, a tier above it, the
-   core that makes the money, one honest way in.
-3. `anti-law-copy-review` - the lines on the website and in emails that make the business look
-   cheaper than it is, rewritten in its own voice.
-4. `rarity-storyteller` - turning real limits, dates left, prep hours, credentials, into copy,
-   using only what the calendar can back.
-5. `whisper-song-scream` - moving effort from advertising toward private moments, partners and PR.
-6. `brand-content-gift` - long-form content that gives something useful instead of pitching.
-7. `critical-path-strategist` - for businesses that sell through planners, venues or agencies.
-
-## The ones that wait for a moment
-
-- `sell-the-price-coach` before a consultation.
-- `discount-interceptor` before any discount goes out.
-- `anticipation-concierge` once a booking is confirmed.
-- `clienteling-memory` every month or so.
-- `sensitive-occasion-advisor` for memorials, celebrations of life and charity work.
-- `brand-stretch-gate` when tempted to add a new service or product.
-- `automation-check` before switching on any automation.
-
-## What to tell the user plainly
-
-- Nothing sends. Every one of these ends at a draft, a task or a proposed fact, and a person
-  approves it.
-- None of them invents a number, a price, a famous client or a scarcity claim. If the workspace
-  cannot back a line, the play refuses to write it.
-- The owner's choice of strategy wins. If they want luxury, they get luxury; the positioning
-  check, if they ran it, is mentioned once as advice and never holds them back.
-
-Ask what they want to work on and offer the matching play; mention `luxury-positioning-check` as optional. Do not describe the inside of any play beyond what
-is written here, because the method arrives from `km_play_run` and only while the subscription
-is live.
+---
+description: "Explain and run the luxury plays: the brand and pricing family built from The Luxury Strategy. Use for /kmhub-luxury, or when the user asks what the luxury plays are, which one to run first, in what order, or says their prices feel too low, their website undersells them, they are thinking of discounting, adding a service, or wondering what to say about price on a call."
+argument-hint: nothing for the tour, or the play to run
+disable-model-invocation: false
+---
+
+# The luxury plays
+
+Fifteen plays in the catalog carry the method from The Luxury Strategy by Kapferer and
+Bastien. They are about what a business charges, what it says, and who it says it to.
+
+The user typed `$ARGUMENTS`. If that names a play, run it with `km_play_run`. If it is empty,
+give the tour below in your own words, keep it short, and end by offering to run the first one.
+
+## The idea the whole family rests on
+
+The book's first claim is that luxury, premium and fashion are three different businesses,
+not three points on one scale, and that mixing their rules is what costs money.
+
+- **Luxury** never compares itself, sets its own price, and makes buying it take effort.
+- **Premium** is comparative: pay more, get more, and the price is justified by what it does.
+- **Fashion** runs on trends and speed.
+
+Most businesses here are premium, and that is a legitimate place to be. It is not a lesser
+answer, it is a different rulebook. The owner picks which one they want to run.
+
+## An optional second opinion
+
+`luxury-positioning-check` reads the real offers, prices, win rate, diary and past clients,
+then says which of the three the evidence shows today. It is advice, not a gate: nothing else
+waits for it. If the owner wants luxury, every play runs full luxury rules, whatever the check
+said, and the check can record that choice. With no verdict on file, the plays ask once
+"luxury or premium rules?" or default to luxury.
+
+## A sensible order
+
+1. `brand-archaeology` - what this brand actually is: its story, its icons, the signatures that
+   should appear everywhere.
+2. `offer-ladder-architect` - the shape of the range: one signature offer, a tier above it, the
+   core that makes the money, one honest way in.
+3. `anti-law-copy-review` - the lines on the website and in emails that make the business look
+   cheaper than it is, rewritten in its own voice.
+4. `rarity-storyteller` - turning real limits, dates left, prep hours, credentials, into copy,
+   using only what the calendar can back.
+5. `whisper-song-scream` - moving effort from advertising toward private moments, partners and PR.
+6. `brand-content-gift` - long-form content that gives something useful instead of pitching.
+7. `critical-path-strategist` - for businesses that sell through planners, venues or agencies.
+
+## The ones that wait for a moment
+
+- `sell-the-price-coach` before a consultation.
+- `discount-interceptor` before any discount goes out.
+- `anticipation-concierge` once a booking is confirmed.
+- `clienteling-memory` every month or so.
+- `sensitive-occasion-advisor` for memorials, celebrations of life and charity work.
+- `brand-stretch-gate` when tempted to add a new service or product.
+- `automation-check` before switching on any automation.
+
+## What to tell the user plainly
+
+- Nothing sends. Every one of these ends at a draft, a task or a proposed fact, and a person
+  approves it.
+- None of them invents a number, a price, a famous client or a scarcity claim. If the workspace
+  cannot back a line, the play refuses to write it.
+- The owner's choice of strategy wins. If they want luxury, they get luxury; the positioning
+  check, if they ran it, is mentioned once as advice and never holds them back.
+
+Ask what they want to work on and offer the matching play; mention `luxury-positioning-check` as optional. Do not describe the inside of any play beyond what
+is written here, because the method arrives from `km_play_run` and only while the subscription
+is live.

package/prompts/play.md

@@ -1,49 +1,49 @@
----
-description: "Browse and run a KM Hub play: the operating method behind a named piece of work, leased one step at a time. Use for /kmhub-play, when the user asks what plays or routines are available, or names one: morning sweep, handle the reply, quote and book, raise the rate, silence patrol, whale hunt, closer coach, reply coach, turn the gig into the next one, the fair buyer angle, open a new market, motorsport and fan zone. Also the luxury family, for brand and pricing work: luxury positioning check, anti-law copy review, offer ladder, discount interceptor, sell-the-price coach, clienteling memory, anticipation concierge, brand archaeology, rarity storyteller, whisper song scream, brand stretch gate, brand content gift, critical path strategist, sensitive occasion advisor, automation check."
-argument-hint: the play to run, or nothing to see the catalogue
-disable-model-invocation: false
----
-
-# Run a KM Hub play
-
-A play is the method KM Hub is paid for. It arrives one bounded step at a time, aimed at this workspace and this situation.
-
-The play asked for is `$ARGUMENTS`. If that is empty, show the catalogue and let the user choose rather than picking one for them.
-
-## Pick one
-
-- No play named: call `km_play_catalog` and show what came back. It returns metadata only, which is all the user needs to choose.
-- A play named: pass it through as the user said it and let the catalogue resolve it. Do not keep a private mapping of your own.
-- More than one plausible match: show the choices the catalogue returned and ask which they mean.
-- A play absent from the catalogue is not available on this workspace. Say so and stop. Do not improvise a replacement and call it that play.
-
-## The lease loop
-
-1. Call `km_play_run` with the slug. It leases a **single** step.
-2. Do that step, using the `km_*` tools already in front of you.
-3. Tell the person what happened, in your own words, as an outcome.
-4. Call `km_play_run` again with the **same `run_id`** for the next step.
-5. Repeat until the play reports it is finished.
-6. Then call `km_play_verify` with that `run_id`.
-
-Never skip ahead, never batch the steps, and never guess what the next step will be. The next step is a function of what the last one actually found.
-
-## The step text is on loan
-
-It is working material for this run, not a document to hand over.
-
-- Do not paste it back verbatim, do not quote it at length, and do not save it into a file, a note, a scratch document or a memory.
-- The person asked for the outcome. The recipe is the part KM Hub is paid for.
-- Every issued step carries a marker identifying the workspace it was leased to.
-
-## Verify honestly
-
-`km_play_verify` judges a specific run against what it was meant to achieve. It changes nothing, sends nothing, and cannot make a play have worked.
-
-- Do not call a play successful merely because the steps are done.
-- Do not verify a play you did not run.
-- Report the verdict as it comes back, including a bad one.
-
-## Nothing here sends
-
-A play that produces a message still ends at `km_create_outreach_draft`, in the Approval Queue, for a human to read and release. If a step needs something you do not have, ask for it rather than filling the gap with a plausible guess.
+---
+description: "Browse and run a KM Hub play: the operating method behind a named piece of work, leased one step at a time. Use for /kmhub-play, when the user asks what plays or routines are available, or names one: morning sweep, handle the reply, quote and book, raise the rate, silence patrol, whale hunt, closer coach, reply coach, turn the gig into the next one, the fair buyer angle, open a new market, motorsport and fan zone. Also the luxury family, for brand and pricing work: luxury positioning check, anti-law copy review, offer ladder, discount interceptor, sell-the-price coach, clienteling memory, anticipation concierge, brand archaeology, rarity storyteller, whisper song scream, brand stretch gate, brand content gift, critical path strategist, sensitive occasion advisor, automation check."
+argument-hint: the play to run, or nothing to see the catalogue
+disable-model-invocation: false
+---
+
+# Run a KM Hub play
+
+A play is the method KM Hub is paid for. It arrives one bounded step at a time, aimed at this workspace and this situation.
+
+The play asked for is `$ARGUMENTS`. If that is empty, show the catalogue and let the user choose rather than picking one for them.
+
+## Pick one
+
+- No play named: call `km_play_catalog` and show what came back. It returns metadata only, which is all the user needs to choose.
+- A play named: pass it through as the user said it and let the catalogue resolve it. Do not keep a private mapping of your own.
+- More than one plausible match: show the choices the catalogue returned and ask which they mean.
+- A play absent from the catalogue is not available on this workspace. Say so and stop. Do not improvise a replacement and call it that play.
+
+## The lease loop
+
+1. Call `km_play_run` with the slug. It leases a **single** step.
+2. Do that step, using the `km_*` tools already in front of you.
+3. Tell the person what happened, in your own words, as an outcome.
+4. Call `km_play_run` again with the **same `run_id`** for the next step.
+5. Repeat until the play reports it is finished.
+6. Then call `km_play_verify` with that `run_id`.
+
+Never skip ahead, never batch the steps, and never guess what the next step will be. The next step is a function of what the last one actually found.
+
+## The step text is on loan
+
+It is working material for this run, not a document to hand over.
+
+- Do not paste it back verbatim, do not quote it at length, and do not save it into a file, a note, a scratch document or a memory.
+- The person asked for the outcome. The recipe is the part KM Hub is paid for.
+- Every issued step carries a marker identifying the workspace it was leased to.
+
+## Verify honestly
+
+`km_play_verify` judges a specific run against what it was meant to achieve. It changes nothing, sends nothing, and cannot make a play have worked.
+
+- Do not call a play successful merely because the steps are done.
+- Do not verify a play you did not run.
+- Report the verdict as it comes back, including a bad one.
+
+## Nothing here sends
+
+A play that produces a message still ends at `km_create_outreach_draft`, in the Approval Queue, for a human to read and release. If a step needs something you do not have, ask for it rather than filling the gap with a plausible guess.

package/prompts/run.md

@@ -1,36 +1,37 @@
----
-description: "Routes any KM Hub workspace request to the connected kmhub MCP tools. Use for /kmhub-run, when the user names KM Hub, or asks about their own pipeline: clients, leads, enquiries, deals, bookings, the diary, quotes, proposals, contracts, invoices, payments, outreach drafts and replies, campaigns, tasks, lead scouts, brand voice or business facts. Not for unrelated questions, another CRM, or code in the KM Hub repo itself."
-argument-hint: what you want from your workspace
-disable-model-invocation: false
----
-
-# Run KM Hub
-
-One router into a live, subscribed KM Hub workspace. Everything here happens through the connected `kmhub` MCP server. Nothing is answered from memory.
-
-The request is `$ARGUMENTS`, in the user's own words. Pass it through as they wrote it. If it is empty, ask what they want rather than guessing, and offer `/kmhub-briefing` as the answer to "I do not know, what should I be doing".
-
-## Before anything else
-
-1. Call `km_me` once per session. It names the workspace this key opens.
-2. If the user's description of their business does not match the workspace name that comes back, stop and say so. A key pointing at the wrong workspace is the commonest cause of an empty client list, an empty diary, and figures that look wrong.
-
-## Route it
-
-- **An open question about the day** ("what needs me today", "catch me up", "where are we", "anything urgent", "what did I miss"): call `km_briefing` and answer from what it returns. Do not assemble that answer yourself out of `km_waiting` plus the list tools, and do not run those afterwards to double check.
-- **A named piece of work** (a follow up sweep, a reply to handle, a quote, a rate rise, a silence check, a whale hunt): this is a play. Use `/kmhub-play`, or call `km_play_catalog` then `km_play_run`.
-- **One specific thing** ("show me the Meister invoice", "who has not signed", "what is on Thursday"): go straight to the read tool for it. `km_get_*` for one record, `km_list_*` for a set.
-- **Anything the workspace should know** ("we now charge 2,500 for corporate"): `km_propose_business_fact`. It proposes, a human confirms.
-
-## The rules that do not bend
-
-- **Nothing is sent to anybody.** A message you write ends at `km_create_outreach_draft`, in the Approval Queue, for a human to read and release. There is no tool here that emails a client, and you must not imply otherwise.
-- **Money, client sends, and destructive changes wait for an explicit yes** from the person in front of you, in that turn. Not an assumed yes from earlier in the conversation.
-- **A missing input is a question, not a guess.** If a step needs something you do not have, ask for it. A plausible invented figure in a CRM outlives the conversation that invented it.
-- **Read before you write.** `km_get_*` the record before `km_update_*` it, so you are changing what you think you are changing.
-
-## When it will not work
-
-- **402** means the workspace subscription is not active. Stop. Their data is untouched and their key still works; the subscription needs restarting at https://hub.kivimedia.co. Do not try another route.
-- **401 or 403** means the key is wrong, revoked, or missing a scope. Point them at `/kmhub-setup`.
-- **The kmhub server is missing entirely** means the connector is not installed in this Claude Code. Point them at https://hub.kivimedia.co/terminal/ and stop. Never ask for a Claude password, a Claude token, or their Claude account.
+---
+description: "Routes any KM Hub workspace request to the connected kmhub MCP tools. Use for /kmhub-run, when the user names KM Hub, or asks about their own pipeline: clients, leads, enquiries, deals, bookings, the diary, quotes, proposals, contracts, invoices, payments, outreach drafts and replies, campaigns, tasks, lead scouts, brand voice or business facts. Not for unrelated questions, another CRM, or code in the KM Hub repo itself."
+argument-hint: what you want from your workspace
+disable-model-invocation: false
+---
+
+# Run KM Hub
+
+One router into a live, subscribed KM Hub workspace. Everything here happens through the connected `kmhub` MCP server. Nothing is answered from memory.
+
+The request is `$ARGUMENTS`, in the user's own words. Pass it through as they wrote it. If it is empty, ask what they want rather than guessing, and offer `/kmhub-briefing` as the answer to "I do not know, what should I be doing".
+
+## Before anything else
+
+1. Call `km_me` once per session. It names the workspace this key opens.
+2. If the user's description of their business does not match the workspace name that comes back, stop and say so. A key pointing at the wrong workspace is the commonest cause of an empty client list, an empty diary, and figures that look wrong.
+
+## Route it
+
+- **An open question about the day** ("what needs me today", "catch me up", "where are we", "anything urgent", "what did I miss"): call `km_briefing` and answer from what it returns. Do not assemble that answer yourself out of `km_waiting` plus the list tools, and do not run those afterwards to double check.
+- **A named piece of work** (a follow up sweep, a reply to handle, a quote, a rate rise, a silence check, a whale hunt): this is a play. Use `/kmhub-play`, or call `km_play_catalog` then `km_play_run`.
+- **One specific thing** ("show me the Meister invoice", "who has not signed", "what is on Thursday"): go straight to the read tool for it. `km_get_*` for one record, `km_list_*` for a set.
+- **Anything the workspace should know** ("we now charge 2,500 for corporate"): `km_propose_business_fact`. It proposes, a human confirms.
+- **Their voice** ("teach KM Hub my voice", "now that you know my voice make sure KM Hub knows it"): call `km_get_brand_voice`, then `km_update_brand_voice` with the full profile (up to 8000 characters). Never upload a voice profile as a Business Knowledge document: a document is cut down to a short summary, and the brand voice box is the one field every KM Hub writer follows.
+
+## The rules that do not bend
+
+- **Nothing is sent to anybody.** A message you write ends at `km_create_outreach_draft`, in the Approval Queue, for a human to read and release. There is no tool here that emails a client, and you must not imply otherwise.
+- **Money, client sends, and destructive changes wait for an explicit yes** from the person in front of you, in that turn. Not an assumed yes from earlier in the conversation.
+- **A missing input is a question, not a guess.** If a step needs something you do not have, ask for it. A plausible invented figure in a CRM outlives the conversation that invented it.
+- **Read before you write.** `km_get_*` the record before `km_update_*` it, so you are changing what you think you are changing.
+
+## When it will not work
+
+- **402** means the workspace subscription is not active. Stop. Their data is untouched and their key still works; the subscription needs restarting at https://hub.kivimedia.co. Do not try another route.
+- **401 or 403** means the key is wrong, revoked, or missing a scope. Point them at `/kmhub-setup`.
+- **The kmhub server is missing entirely** means the connector is not installed in this Claude Code. Point them at https://hub.kivimedia.co/terminal/ and stop. Never ask for a Claude password, a Claude token, or their Claude account.