@kivimedia/kmhub 2.10.0 → 2.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kivimedia/kmhub",
-  "version": "2.10.0",
+  "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",

package/prompts/run.md

@@ -21,6 +21,7 @@ The request is `$ARGUMENTS`, in the user's own words. Pass it through as they wr
 - **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
 

package/tools/fact-review.mjs

@@ -34,7 +34,7 @@ function routeMissing(r) {
 const NOT_SUPPORTED =
   'Your KM Hub cannot review business facts from the terminal yet. Nothing is wrong with the workspace and nothing ' +
   'was changed. The owner can confirm or reject them in the web app at https://hub.kivimedia.co under Settings, ' +
-  'Connect, Business Knowledge.';
+  'Account, Business Knowledge.';
 
 const FACT_IDS = z
   .array(z.string())

package/tools/gols.mjs

@@ -28,7 +28,7 @@ function routeMissing(r) {
 
 const NOT_SUPPORTED =
   'This KM Hub does not expose GOLS (the grand-opening scout) to the terminal yet. Nothing is broken; it is in the ' +
-  'web app at https://hub.kivimedia.co/gols. Nothing was charged.';
+  'web app at https://hub.kivimedia.co/?page=gols. Nothing was charged.';
 
 const CONFIRM_TOKEN = z
   .string()
@@ -42,23 +42,30 @@ const CONFIRM_TOKEN = z
 export function register(server, call, { out, text, qs }) {
   server.tool(
     'km_gols_finds',
-    'GOLS (the Grand Opening / Event Scout, also written "gols"): the businesses KM Hub has found that just opened or ' +
-      'have announced an opening near the owner, each scored hot / warm / cold for how likely it is to book event ' +
-      'services for a grand opening, launch or ribbon cutting. Best first. Reach for it when the owner asks about ' +
-      'GOLS, grand openings, new businesses near them, or "who is opening soon". `when` says "Opens <date>" only ' +
-      'for a date the announcement stated; "In the news <date>" is just the article date, so never call that an ' +
-      'opening date. Free, read only. To find more, use km_gols_scan; to act on one, km_gols_push_find.',
+    'GOLS (the Grand Opening / Event Scout, also written "gols"): businesses near the owner that announced an opening ' +
+      'and have NOT opened yet, each scored hot / warm / cold for how likely it is to book event services for its ' +
+      'grand opening, launch or ribbon cutting. By default only openings at least 2 weeks away or with the date not ' +
+      'announced, soonest dated first; the reply counts what it hid (already opened, under 2 weeks away, not an ' +
+      'opening) and when "all" shows them. Reach for it when the owner asks about GOLS, grand openings, new businesses ' +
+      'near them, or "who is opening soon". `when` says "Opens <date>" only for a date the announcement stated; ' +
+      '"Announced, opening date not stated" means the article gave no date, so never invent one. `location` is the ' +
+      "business's own town, or null when the article did not say. Free, read only. To find more, use km_gols_scan; " +
+      'to act on one, km_gols_push_find.',
     {
       status: z
         .enum(['new', 'pushed', 'dismissed', 'all'])
         .optional()
         .describe('Which finds. Default "new" = not yet acted on. "pushed" = already in the pipeline.'),
+      when: z
+        .enum(['upcoming', 'all'])
+        .optional()
+        .describe('Default "upcoming" = not open yet and at least 2 weeks out (or date not announced). "all" = every row, including past ones.'),
       tier: z.enum(['hot', 'warm', 'cold']).optional().describe('Only this fit tier. Leave out for all.'),
       city: z.string().optional().describe('Only finds from scans of this city, as the scan was run.'),
       limit: z.number().int().min(1).max(100).optional().describe('How many. Default 30.'),
     },
-    async ({ status, tier, city, limit }) => {
-      const r = await call('GET', `/gols/finds${qs({ status, tier, city, limit })}`);
+    async ({ status, when, tier, city, limit }) => {
+      const r = await call('GET', `/gols/finds${qs({ status, when, tier, city, limit })}`);
       if (routeMissing(r)) return text(NOT_SUPPORTED, true);
       return out(r);
     },
@@ -67,23 +74,26 @@ export function register(server, call, { out, text, qs }) {
   server.tool(
     'km_gols_scan',
     [
-      'Run a GOLS scan (grand-opening scout): search the news (and Google Places when connected) for businesses that',
-      'just opened near a city, or with ahead=true for ones that have ANNOUNCED an opening that has not happened yet,',
-      'then score each one for event-services fit and save it. It takes about a minute and returns the finds.',
+      'Run a GOLS scan (grand-opening scout): read the last 90 days of opening announcements in the news for ONE US',
+      'county (county + state: the county by name plus its biggest towns) or near a city (city + state), keep only',
+      'businesses that have NOT opened yet (finds that already opened, or that are outside the county, are dropped',
+      'and counted), score each one for event-services fit and save it. A business already on the list is updated,',
+      'not added twice. For several counties, call it once per county; each county is priced on its own. For a place',
+      'outside the US, such as Windsor, Ontario, scan the city. There is no look-back setting and no "recently',
+      'opened" mode. It takes about a minute and returns the finds.',
       'THIS COSTS MONEY (AI time, billed to the workspace). Call it FIRST without confirm_spend: nothing runs and you',
       'get the price. Tell the person the price, and on a yes call again with confirm_spend true; KM Hub then answers',
       '409 with the exact action and a confirm_token, which you show them and send back with the same arguments.',
       'Never start one on your own initiative. It contacts nobody.',
     ].join(' '),
     {
-      city: z.string().describe('The city to scan around, as the person said it. For example "Southfield".'),
-      state: z.string().describe('State or province, for example "MI" or "Ontario".'),
-      radius_miles: z.number().int().min(1).max(200).optional().describe('How far around the city. Default 25.'),
-      lookback_days: z.number().int().min(1).max(120).optional().describe('How far back in the news to look. Default 30.'),
-      ahead: z
-        .boolean()
+      county: z
+        .string()
         .optional()
-        .describe('true = announced openings that have NOT happened yet (the best time to pitch). Default false = already opened.'),
+        .describe('A US county to scan, as the person said it, for example "Oakland" or "Oakland County". Needs state. Leave out to scan around a city.'),
+      city: z.string().optional().describe('The city to scan around, for example "Southfield". Leave out when you pass county.'),
+      state: z.string().describe('State or province, for example "MI" or "Ontario".'),
+      radius_miles: z.number().int().min(1).max(200).optional().describe('How far around the city (city scans only). Default 25.'),
       vertical: z.string().optional().describe('The trade to score fit for, only if it differs from the workspace, e.g. "balloon decor".'),
       zip: z.string().optional().describe('ZIP code, only if the person gave one.'),
       confirm_spend: z

package/tools/knowledge.mjs

@@ -60,7 +60,7 @@ export function register(server, call, { out, qs }) {
 
   server.tool(
     'km_get_business_facts',
-    'What this business has told KM Hub about itself: the facts its owner has CONFIRMED, the standing facts they asked to be remembered permanently, and the knowledge distilled from documents they uploaded such as past proposals, pricing sheets and contracts. Read it before you write anything in the business name, so you work from what is actually true here instead of from a generic idea of the trade. Everything it returns is owner-approved and safe to rely on. Facts that are still waiting for the owner are counted but deliberately not shown, because nobody has confirmed them yet - if that count is above zero it is worth telling the person they have some waiting: km_list_pending_business_facts shows them, and km_confirm_business_facts confirms the ones the owner says are right. Read only.',
+    'What this business has told KM Hub about itself: the facts its owner has CONFIRMED, the standing facts they asked to be remembered permanently, and the knowledge distilled from documents they uploaded such as past proposals, pricing sheets and contracts. Read it before you write anything in the business name, so you work from what is actually true here instead of from a generic idea of the trade. Everything it returns is owner-approved and safe to rely on. A confirmed fact marked internal: true (a cost, a margin, a goal) is for the owner only: use it to advise them, but never quote it to a customer and never put it in a draft. Facts that are still waiting for the owner are counted but deliberately not shown, because nobody has confirmed them yet - if that count is above zero it is worth telling the person they have some waiting: km_list_pending_business_facts shows them, and km_confirm_business_facts confirms the ones the owner says are right. Read only.',
     {
       kind: z
         .enum(['business', 'service', 'price', 'voice', 'vertical_craft'])
@@ -109,7 +109,7 @@ export function register(server, call, { out, qs }) {
 
   server.tool(
     'km_propose_business_fact',
-    'Write down something durable this business has learned about itself, for example that they no longer travel more than two hours, or that their busy season starts in March, or that they always need a stage of a certain size. It is saved as a PROPOSAL and not as truth: it waits in KM Hub under Business Knowledge until the owner confirms it, and no draft, quote or answer will use it before then. Use it only for something that will still be true next month. A detail about ONE client or ONE booking is not a business fact and belongs on that record instead. Always say in source_note where the fact came from, in one line, because that is what the owner reads when deciding whether to accept it. After calling this, tell the person plainly that it is waiting for their approval; when they say it is right, km_confirm_business_facts confirms it with the fact_id this returns. This tool itself cannot confirm a fact, cannot edit or replace an existing one, and cannot remove one.',
+    'Write down something durable this business has learned about itself, for example that they no longer travel more than two hours, or that their busy season starts in March, or that they always need a stage of a certain size. It is saved as a PROPOSAL and not as truth: it waits in KM Hub under Business Knowledge until the owner confirms it, and nothing uses it before then. Once the owner confirms it, KM Hub\'s AI writers use it: business, service and craft facts in the drafts, replies and messages they write, a price fact only in replies and quotes and never in a first cold email, and a voice fact as style for every writer. Set audience to internal for anything that must never reach a customer, such as what something costs the business, a margin, or a sales goal: an internal fact never reaches any AI writer or any customer, and stays visible to the owner and to you. Use it only for something that will still be true next month. A detail about ONE client or ONE booking is not a business fact and belongs on that record instead. Always say in source_note where the fact came from, in one line, because that is what the owner reads when deciding whether to accept it. After calling this, tell the person plainly that it is waiting for their approval; when they say it is right, km_confirm_business_facts confirms it with the fact_id this returns. This tool itself cannot confirm a fact, cannot edit or replace an existing one, and cannot remove one.',
     {
       text: z.string().describe('The fact itself, in one plain sentence, written the way the owner would say it.'),
       source_note: z
@@ -119,6 +119,10 @@ export function register(server, call, { out, qs }) {
         .enum(['business', 'service', 'price', 'voice', 'vertical_craft'])
         .optional()
         .describe('What sort of fact it is. business is the default and covers how they operate. Use price only for a real published price, service for something they offer, voice for how they sound.'),
+      audience: z
+        .enum(['customer', 'internal'])
+        .optional()
+        .describe('Who the fact is for. customer is the default. internal keeps it away from every AI writer and every customer: use it for costs, margins, goals and anything the owner said never to quote. Text that starts with INTERNAL is treated as internal anyway.'),
     },
     async (args) => out(await call('POST', '/knowledge/facts', args)),
   );

package/tools/voice.mjs

@@ -57,8 +57,11 @@ export function register(server, call, { out, text }) {
     'km_update_brand_voice',
     'Change how this business sounds in everything the AI writes: the brand voice box (the owner\'s own words about ' +
       'their values, tone and style) and the name every email is signed with. It is the same box the owner sees in ' +
-      'KM Hub under Settings, General, and in the Sales Playbook Values tab, and every AI writer reads it: first ' +
-      'replies, rewrites, review replies, broadcasts, templates, follow-ups. ' +
+      'KM Hub under Business Knowledge, Voice, under Settings, General, and in the Sales Playbook Values tab, and ' +
+      'every AI writer reads it: first replies, rewrites, review replies, broadcasts, templates, follow-ups. ' +
+      'When the owner asks you to teach KM Hub their voice, or says "now that you know my voice make sure KM Hub ' +
+      'knows it", this is the tool: send the full profile here (up to 8000 characters). Never upload a voice ' +
+      'profile as a Business Knowledge document. ' +
       'Call km_get_brand_voice first so you change from what is actually there. When the person asks to ADD to their ' +
       'voice, send the existing text with the addition, never just the new sentence, or the rest is lost. Write ' +
       'what they said in their words; do not polish it into marketing copy. ' +
@@ -69,7 +72,7 @@ export function register(server, call, { out, text }) {
         .string()
         .nullable()
         .optional()
-        .describe('The full brand voice text, up to 4000 characters. It REPLACES what is there. Send null to clear it.'),
+        .describe('The full brand voice text, up to 8000 characters. It REPLACES what is there. Send null to clear it.'),
       sign_emails_as: z
         .string()
         .nullable()

package/tools.mjs

@@ -30,7 +30,7 @@ import { readdirSync, readFileSync } from 'node:fs';
 import { z } from 'zod';
 
 export const SERVER_NAME = 'kmhub';
-export const SERVER_VERSION = '2.10.0';
+export const SERVER_VERSION = '2.11.0';
 
 export const DEFAULT_BASE =
   process.env.KMHUB_API_BASE ||