@kivimedia/kmhub 2.9.0 → 2.10.0

package/tools/venueradar.mjs

@@ -1,151 +1,151 @@
-/**
- * Tool family: venueradar - the Venue Radar directory, read from the terminal.
- *
- * ONE directory for the entertainment-buying venue market, in lanes: bars and restaurants,
- * taprooms and tasting rooms (breweries/wineries), and banquet halls / event venues. The engine
- * builds it from Google Places county tiles, Open Brewery DB and the TTB winery CSV, then crawls
- * each venue's OWN pages for two evidence lanes: proof it already books recurring entertainment
- * (trivia, live music, game night - each signal quoted), and a published preferred-vendor list
- * (the categories it names are stored; a category ABSENT from the venue's own list is the
- * placement pitch). So the thing a person wants from the terminal is "show me what is already in
- * there", filtered by lane, and that needs its own family rather than another mission list entry.
- *
- *   km_venue_radar_venues -> GET /venue-radar/venues
- *   km_venue_radar_venue  -> GET /venue-radar/venues/:ref
- *
- * 🚨 READ ONLY, and there are three separate reasons, all of which the descriptions say out loud:
- *
- *   1. NOTHING HERE SUBMITS, APPROVES OR SENDS. Writing to a venue or dialing it is a human act
- *      in KM Hub, behind the Approval Queue - venue_radar drafts are a never-auto source, because
- *      a cold first impression to a venue is exactly the message a human must read first.
- *   2. NOTHING HERE STARTS A SWEEP. Queueing one is admin-only under RLS in the web app, and the
- *      API runs on the service role, which bypasses RLS: a start tool would quietly hand any
- *      read/write key a power the product refuses to a non-admin member. Whether a sweep is
- *      running is readable through km_list_radar_scans with kind 'venue_radar_ingest'.
- *   3. Reading costs NOTHING and sends NOTHING. The directory is shared reference data with
- *      global read, so there is no first click to make and no bill for looking.
- *
- * The family contract this file follows is documented in ./README.md.
- */
-import { z } from 'zod';
-
-export const FAMILY = 'venueradar';
-
-export const TOOLS = [
-  'km_venue_radar_venues',
-  'km_venue_radar_venue',
-];
-
-// Finding and reaching buyers is outreach work, so this family joins that profile. It is not in
-// `core`: a session that only wants orientation should not carry two more schemas.
-export const PROFILES = ['outreach'];
-
-/**
- * Has this KM Hub simply never heard of the route, or did the route run and find nothing?
- *
- * 🚨 Same discrimination as the military and clubs families, for the same reason: asking for a
- * venue that is not in the directory is a real, ordinary 404. Collapsing the two would answer a
- * plain typo with "your KM Hub does not have the venue directory", which is a false statement
- * about the product rather than a wrong answer about a venue. So only the router's own
- * self-describing 404, which carries the whole route list, counts as a missing route.
- */
-function routeMissing(r) {
-  if (r.status === 405 || r.status === 501) return true;
-  if (r.status !== 404) return false;
-  const body = r && r.data && typeof r.data === 'object' ? r.data : null;
-  if (!body) return true;
-  if (Array.isArray(body.routes)) return true;
-  return typeof body.message === 'string' && body.message.startsWith('Unknown route');
-}
-
-const NOT_SUPPORTED =
-  'This KM Hub does not serve the venue directory to the terminal yet. Nothing is broken: the workspace is fine ' +
-  'and every other tool works as normal. The directory is there in the web app at https://hub.kivimedia.co under ' +
-  'Outbound, named Venue Radar.';
-
-const NO_SEND =
-  'What it will NOT do: it cannot write to a venue, dial a phone, mark a lane status or send anything, and no ' +
-  'other tool here can either. Working a venue - the ladder to a weekly residency, or the funnel onto its vendor ' +
-  'list - happens in KM Hub at https://hub.kivimedia.co, on purpose. Never tell somebody a message went out.';
-
-const NO_INVENTION =
-  'Never construct an address or a claim. books_entertainment is counted from signals quoted off the venue\'s own ' +
-  'pages, a venue that publishes no buyer keeps no buyer, and an email marked guess must verify before it may ' +
-  'reach a draft - say so whenever one is shown.';
-
-export function register(server, call, { out, text, qs }) {
-  server.tool(
-    'km_venue_radar_venues',
-    'The venues KM Hub has already gathered and evidenced: bars, restaurants, breweries/taprooms, wineries, ' +
-      'banquet halls and event venues, each with its two evidence lanes - proof it books recurring entertainment ' +
-      '(trivia, live music, game night, each signal quoted from its own pages) and whether it publishes a ' +
-      'preferred-vendor list, with the categories that list names. ' +
-      'Reach for it whenever somebody asks about bars, restaurants, taprooms, breweries, wineries, banquet halls ' +
-      'or event venues as BUYERS, and reach for it FIRST rather than describing the feature: reading it costs ' +
-      'nothing, spends nothing and sends nothing. ' +
-      '🚨 The lane filter is the point. lane "entertainment" answers "who already pays for a weekly night I could ' +
-      'fill"; lane "vendor_list" answers "which halls keep a vendor list my category is missing from" - the ' +
-      'categories their own list names come back per venue, so the absent-category pitch is readable straight off ' +
-      'the row. Per venue you also get this workspace\'s own working state, the fit score and the already_client ' +
-      'flag (computed against this workspace\'s own client list - the "has not booked us yet" filter). ' +
-      'A venue with no lane data yet is NORMAL, not missing: the enrich sweep fills evidence venue by venue. ' +
-      NO_INVENTION +
-      ' ' +
-      'Whether a sweep is running is a different question, answered by km_list_radar_scans with kind ' +
-      "'venue_radar_ingest'. Starting one is done in KM Hub, never from here. " +
-      NO_SEND,
-    {
-      kind: z
-        .enum(['bar', 'restaurant', 'brewery', 'winery', 'banquet_hall', 'event_venue'])
-        .optional()
-        .describe('One venue kind. Leave it out to see all six.'),
-      lane: z
-        .enum(['entertainment', 'vendor_list'])
-        .optional()
-        .describe('Evidence lane: "entertainment" = proven recurring entertainment buyer; "vendor_list" = publishes a preferred-vendor list.'),
-      county: z.string().optional().describe('County name, matched loosely, for example "Monmouth".'),
-      state: z.string().optional().describe('Two-letter US state, for example "NJ".'),
-      city: z.string().optional().describe('City name, matched loosely.'),
-      q: z.string().optional().describe('Free text against name, place, kind and subtype, in any order.'),
-      limit: z.number().int().min(1).max(200).optional().describe('How many venues to return. Default 40. Check `truncated`.'),
-    },
-    async ({ kind, lane, county, state, city, q, limit }) => {
-      const r = await call('GET', `/venue-radar/venues${qs({ kind, lane, county, state, city, q, limit })}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_venue_radar_venue',
-    'One venue in full: every entertainment signal with the page it was quoted from, the vendor list with the ' +
-      'categories it names, the buyer (name, title, role, published email or labelled guess, with its evidence), ' +
-      'and whatever working state this workspace has already recorded on both lanes. ' +
-      'Use it after km_venue_radar_venues when somebody picks a venue, or whenever they name one directly. It ' +
-      'takes the venue_key from a previous answer (for example "obdb:some-brewery-id") or a Google place id. ' +
-      '🚨 An evidence entry marked stale means the quarterly recheck could no longer find that signal on its page ' +
-      '- the trail is kept, never deleted, and a stale trivia night is not a live pitch. buyer.email was read ' +
-      'verbatim off the page in its source_url; buyer.email_guess must verify before any draft, and any draft ' +
-      'against it is refused until it does. ' +
-      NO_INVENTION +
-      ' ' +
-      'Read only. Costs nothing, spends nothing. ' +
-      NO_SEND,
-    {
-      venue: z
-        .string()
-        .describe('The venue_key from a previous answer, for example "obdb:some-brewery-id", or the venue\'s Google place id.'),
-    },
-    async ({ venue }) => {
-      const ref = String(venue || '').trim();
-      if (!ref) {
-        return text(
-          'I need to know which venue. km_venue_radar_venues lists them, and each row carries the venue_key this tool takes.',
-        );
-      }
-      const r = await call('GET', `/venue-radar/venues/${encodeURIComponent(ref)}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-}
+/**
+ * Tool family: venueradar - the Venue Radar directory, read from the terminal.
+ *
+ * ONE directory for the entertainment-buying venue market, in lanes: bars and restaurants,
+ * taprooms and tasting rooms (breweries/wineries), and banquet halls / event venues. The engine
+ * builds it from Google Places county tiles, Open Brewery DB and the TTB winery CSV, then crawls
+ * each venue's OWN pages for two evidence lanes: proof it already books recurring entertainment
+ * (trivia, live music, game night - each signal quoted), and a published preferred-vendor list
+ * (the categories it names are stored; a category ABSENT from the venue's own list is the
+ * placement pitch). So the thing a person wants from the terminal is "show me what is already in
+ * there", filtered by lane, and that needs its own family rather than another mission list entry.
+ *
+ *   km_venue_radar_venues -> GET /venue-radar/venues
+ *   km_venue_radar_venue  -> GET /venue-radar/venues/:ref
+ *
+ * 🚨 READ ONLY, and there are three separate reasons, all of which the descriptions say out loud:
+ *
+ *   1. NOTHING HERE SUBMITS, APPROVES OR SENDS. Writing to a venue or dialing it is a human act
+ *      in KM Hub, behind the Approval Queue - venue_radar drafts are a never-auto source, because
+ *      a cold first impression to a venue is exactly the message a human must read first.
+ *   2. NOTHING HERE STARTS A SWEEP. Queueing one is admin-only under RLS in the web app, and the
+ *      API runs on the service role, which bypasses RLS: a start tool would quietly hand any
+ *      read/write key a power the product refuses to a non-admin member. Whether a sweep is
+ *      running is readable through km_list_radar_scans with kind 'venue_radar_ingest'.
+ *   3. Reading costs NOTHING and sends NOTHING. The directory is shared reference data with
+ *      global read, so there is no first click to make and no bill for looking.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'venueradar';
+
+export const TOOLS = [
+  'km_venue_radar_venues',
+  'km_venue_radar_venue',
+];
+
+// Finding and reaching buyers is outreach work, so this family joins that profile. It is not in
+// `core`: a session that only wants orientation should not carry two more schemas.
+export const PROFILES = ['outreach'];
+
+/**
+ * Has this KM Hub simply never heard of the route, or did the route run and find nothing?
+ *
+ * 🚨 Same discrimination as the military and clubs families, for the same reason: asking for a
+ * venue that is not in the directory is a real, ordinary 404. Collapsing the two would answer a
+ * plain typo with "your KM Hub does not have the venue directory", which is a false statement
+ * about the product rather than a wrong answer about a venue. So only the router's own
+ * self-describing 404, which carries the whole route list, counts as a missing route.
+ */
+function routeMissing(r) {
+  if (r.status === 405 || r.status === 501) return true;
+  if (r.status !== 404) return false;
+  const body = r && r.data && typeof r.data === 'object' ? r.data : null;
+  if (!body) return true;
+  if (Array.isArray(body.routes)) return true;
+  return typeof body.message === 'string' && body.message.startsWith('Unknown route');
+}
+
+const NOT_SUPPORTED =
+  'This KM Hub does not serve the venue directory to the terminal yet. Nothing is broken: the workspace is fine ' +
+  'and every other tool works as normal. The directory is there in the web app at https://hub.kivimedia.co under ' +
+  'Outbound, named Venue Radar.';
+
+const NO_SEND =
+  'What it will NOT do: it cannot write to a venue, dial a phone, mark a lane status or send anything, and no ' +
+  'other tool here can either. Working a venue - the ladder to a weekly residency, or the funnel onto its vendor ' +
+  'list - happens in KM Hub at https://hub.kivimedia.co, on purpose. Never tell somebody a message went out.';
+
+const NO_INVENTION =
+  'Never construct an address or a claim. books_entertainment is counted from signals quoted off the venue\'s own ' +
+  'pages, a venue that publishes no buyer keeps no buyer, and an email marked guess must verify before it may ' +
+  'reach a draft - say so whenever one is shown.';
+
+export function register(server, call, { out, text, qs }) {
+  server.tool(
+    'km_venue_radar_venues',
+    'The venues KM Hub has already gathered and evidenced: bars, restaurants, breweries/taprooms, wineries, ' +
+      'banquet halls and event venues, each with its two evidence lanes - proof it books recurring entertainment ' +
+      '(trivia, live music, game night, each signal quoted from its own pages) and whether it publishes a ' +
+      'preferred-vendor list, with the categories that list names. ' +
+      'Reach for it whenever somebody asks about bars, restaurants, taprooms, breweries, wineries, banquet halls ' +
+      'or event venues as BUYERS, and reach for it FIRST rather than describing the feature: reading it costs ' +
+      'nothing, spends nothing and sends nothing. ' +
+      '🚨 The lane filter is the point. lane "entertainment" answers "who already pays for a weekly night I could ' +
+      'fill"; lane "vendor_list" answers "which halls keep a vendor list my category is missing from" - the ' +
+      'categories their own list names come back per venue, so the absent-category pitch is readable straight off ' +
+      'the row. Per venue you also get this workspace\'s own working state, the fit score and the already_client ' +
+      'flag (computed against this workspace\'s own client list - the "has not booked us yet" filter). ' +
+      'A venue with no lane data yet is NORMAL, not missing: the enrich sweep fills evidence venue by venue. ' +
+      NO_INVENTION +
+      ' ' +
+      'Whether a sweep is running is a different question, answered by km_list_radar_scans with kind ' +
+      "'venue_radar_ingest'. Starting one is done in KM Hub, never from here. " +
+      NO_SEND,
+    {
+      kind: z
+        .enum(['bar', 'restaurant', 'brewery', 'winery', 'banquet_hall', 'event_venue'])
+        .optional()
+        .describe('One venue kind. Leave it out to see all six.'),
+      lane: z
+        .enum(['entertainment', 'vendor_list'])
+        .optional()
+        .describe('Evidence lane: "entertainment" = proven recurring entertainment buyer; "vendor_list" = publishes a preferred-vendor list.'),
+      county: z.string().optional().describe('County name, matched loosely, for example "Monmouth".'),
+      state: z.string().optional().describe('Two-letter US state, for example "NJ".'),
+      city: z.string().optional().describe('City name, matched loosely.'),
+      q: z.string().optional().describe('Free text against name, place, kind and subtype, in any order.'),
+      limit: z.number().int().min(1).max(200).optional().describe('How many venues to return. Default 40. Check `truncated`.'),
+    },
+    async ({ kind, lane, county, state, city, q, limit }) => {
+      const r = await call('GET', `/venue-radar/venues${qs({ kind, lane, county, state, city, q, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_venue_radar_venue',
+    'One venue in full: every entertainment signal with the page it was quoted from, the vendor list with the ' +
+      'categories it names, the buyer (name, title, role, published email or labelled guess, with its evidence), ' +
+      'and whatever working state this workspace has already recorded on both lanes. ' +
+      'Use it after km_venue_radar_venues when somebody picks a venue, or whenever they name one directly. It ' +
+      'takes the venue_key from a previous answer (for example "obdb:some-brewery-id") or a Google place id. ' +
+      '🚨 An evidence entry marked stale means the quarterly recheck could no longer find that signal on its page ' +
+      '- the trail is kept, never deleted, and a stale trivia night is not a live pitch. buyer.email was read ' +
+      'verbatim off the page in its source_url; buyer.email_guess must verify before any draft, and any draft ' +
+      'against it is refused until it does. ' +
+      NO_INVENTION +
+      ' ' +
+      'Read only. Costs nothing, spends nothing. ' +
+      NO_SEND,
+    {
+      venue: z
+        .string()
+        .describe('The venue_key from a previous answer, for example "obdb:some-brewery-id", or the venue\'s Google place id.'),
+    },
+    async ({ venue }) => {
+      const ref = String(venue || '').trim();
+      if (!ref) {
+        return text(
+          'I need to know which venue. km_venue_radar_venues lists them, and each row carries the venue_key this tool takes.',
+        );
+      }
+      const r = await call('GET', `/venue-radar/venues/${encodeURIComponent(ref)}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+}

package/tools/voice.mjs

@@ -1,134 +1,134 @@
-/**
- * Tool family: voice - telling KM Hub how to write, from the terminal.
- *
- *   km_update_brand_voice -> PATCH /knowledge/voice          (brand_values, sign_emails_as)
- *   km_set_writing_rules  -> PUT   /knowledge/writing-rules  (the house rules)
- *   km_set_service_rule   -> PUT   /knowledge/service-rules  (one package's writing rule)
- *
- * WHY THIS EXISTS. km_get_brand_voice and km_get_offers_and_pricing could READ how
- * the business sounds and what it sells, and the owner had no way to change either
- * from a terminal conversation. Ziv, 22-Sep-26: "allow Mark to chat through terminal
- * mode with rules about the services, the voice, anything you write". These are the
- * write halves, in their own family so the read family (knowledge.mjs) is untouched.
- *
- * 🚨 Every tool here is a confirmed write. KM Hub answers 409 with a server-written
- * sentence naming the before and after. Put that sentence to the person, wait for a
- * real yes, then call again with the confirm_token and the SAME arguments.
- *
- * The family contract this file follows is documented in ./README.md.
- */
-import { z } from 'zod';
-
-export const FAMILY = 'voice';
-
-export const TOOLS = ['km_update_brand_voice', 'km_set_writing_rules', 'km_set_service_rule'];
-
-// Same profiles as the knowledge family that reads these values: anything that
-// writes words for a real person should be able to correct how it writes them.
-export const PROFILES = ['outreach', 'content', 'money'];
-
-function routeMissing(r) {
-  return r.status === 404 || r.status === 405 || r.status === 501;
-}
-
-const NOT_SUPPORTED =
-  'Your KM Hub does not accept voice and writing-rule changes from the terminal yet. Nothing is wrong with the ' +
-  'workspace. The brand voice box is in the web app at https://hub.kivimedia.co under Settings, General, and this ' +
-  'connector will edit it once your KM Hub is on a build that publishes these routes.';
-
-const CONFIRM_TOKEN = z
-  .string()
-  .optional()
-  .describe(
-    'Leave this out on the first call. KM Hub answers 409 with the sentence to put to the person and a token. Only '
-      + 'after they actually say yes, call again with the token and the SAME arguments. A yes for one change never '
-      + 'authorises a different one.',
-  );
-
-/** Forward only what the caller set: undefined means "leave alone", null means "clear". */
-function defined(args) {
-  const body = {};
-  for (const [k, v] of Object.entries(args)) if (v !== undefined) body[k] = v;
-  return body;
-}
-
-export function register(server, call, { out, text }) {
-  server.tool(
-    '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. ' +
-      '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. ' +
-      '🚨 A confirmed write. KM Hub answers 409 with the exact before and after; say that to the person, wait for a ' +
-      'real yes in this turn, then call again with the confirm_token and the same arguments.',
-    {
-      brand_values: z
-        .string()
-        .nullable()
-        .optional()
-        .describe('The full brand voice text, up to 4000 characters. It REPLACES what is there. Send null to clear it.'),
-      sign_emails_as: z
-        .string()
-        .nullable()
-        .optional()
-        .describe('The name every email is signed with, for example "Mark" or "Mark and the Twisty Art team". Send null to clear it.'),
-      confirm_token: CONFIRM_TOKEN,
-    },
-    async (args) => {
-      const r = await call('PATCH', '/knowledge/voice', defined(args));
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_set_writing_rules',
-    'Set the house writing rules: the standing instructions every message the AI writes for this business must obey, ' +
-      'for example "never quote a price in the first email", "always offer a phone call", "never call our performers ' +
-      'clowns". They are mandatory, not style, and they apply to every AI writer including automatic ones. ' +
-      'Use append to add one rule to the end (the usual case, and safe); use rules only when the person wants the whole ' +
-      'list rewritten, and then send every rule they want kept, because rules replaces the list. km_get_brand_voice ' +
-      'shows the current list under voice.house_rules. ' +
-      '🚨 A confirmed write: KM Hub answers 409 with the before and after, the person says yes, you call again with ' +
-      'the confirm_token and the same arguments.',
-    {
-      append: z.string().optional().describe('One or more new rules to add to the end of the list.'),
-      rules: z
-        .string()
-        .nullable()
-        .optional()
-        .describe('The complete list of rules, one per line, up to 3000 characters. Replaces the list. Send null to clear every rule.'),
-      confirm_token: CONFIRM_TOKEN,
-    },
-    async (args) => {
-      const r = await call('PUT', '/knowledge/writing-rules', defined(args));
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_set_service_rule',
-    'Give one service its own writing rule: an instruction the AI must follow whenever a message mentions that ' +
-      'service, for example "Balloon Twisting: always say each child gets one design, never a number of balloons" or ' +
-      '"Face Painting: mention we only use FDA compliant paints". One rule per service; setting it again replaces it, ' +
-      'null removes it. Name the service by package_id or by its exact name from km_get_offers_and_pricing, which ' +
-      'also lists every current rule under service_rules. ' +
-      '🚨 A confirmed write: KM Hub answers 409 with the before and after, the person says yes, you call again with ' +
-      'the confirm_token and the same arguments.',
-    {
-      package_id: z.string().optional().describe('The service package id from km_get_offers_and_pricing (proposal_packages[].id).'),
-      package_name: z.string().optional().describe('Or the exact service name, when you do not have the id.'),
-      rule: z.string().nullable().describe('The rule, up to 1000 characters. Send null to remove this service\'s rule.'),
-      confirm_token: CONFIRM_TOKEN,
-    },
-    async (args) => {
-      const r = await call('PUT', '/knowledge/service-rules', defined(args));
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-}
+/**
+ * Tool family: voice - telling KM Hub how to write, from the terminal.
+ *
+ *   km_update_brand_voice -> PATCH /knowledge/voice          (brand_values, sign_emails_as)
+ *   km_set_writing_rules  -> PUT   /knowledge/writing-rules  (the house rules)
+ *   km_set_service_rule   -> PUT   /knowledge/service-rules  (one package's writing rule)
+ *
+ * WHY THIS EXISTS. km_get_brand_voice and km_get_offers_and_pricing could READ how
+ * the business sounds and what it sells, and the owner had no way to change either
+ * from a terminal conversation. Ziv, 22-Sep-26: "allow Mark to chat through terminal
+ * mode with rules about the services, the voice, anything you write". These are the
+ * write halves, in their own family so the read family (knowledge.mjs) is untouched.
+ *
+ * 🚨 Every tool here is a confirmed write. KM Hub answers 409 with a server-written
+ * sentence naming the before and after. Put that sentence to the person, wait for a
+ * real yes, then call again with the confirm_token and the SAME arguments.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'voice';
+
+export const TOOLS = ['km_update_brand_voice', 'km_set_writing_rules', 'km_set_service_rule'];
+
+// Same profiles as the knowledge family that reads these values: anything that
+// writes words for a real person should be able to correct how it writes them.
+export const PROFILES = ['outreach', 'content', 'money'];
+
+function routeMissing(r) {
+  return r.status === 404 || r.status === 405 || r.status === 501;
+}
+
+const NOT_SUPPORTED =
+  'Your KM Hub does not accept voice and writing-rule changes from the terminal yet. Nothing is wrong with the ' +
+  'workspace. The brand voice box is in the web app at https://hub.kivimedia.co under Settings, General, and this ' +
+  'connector will edit it once your KM Hub is on a build that publishes these routes.';
+
+const CONFIRM_TOKEN = z
+  .string()
+  .optional()
+  .describe(
+    'Leave this out on the first call. KM Hub answers 409 with the sentence to put to the person and a token. Only '
+      + 'after they actually say yes, call again with the token and the SAME arguments. A yes for one change never '
+      + 'authorises a different one.',
+  );
+
+/** Forward only what the caller set: undefined means "leave alone", null means "clear". */
+function defined(args) {
+  const body = {};
+  for (const [k, v] of Object.entries(args)) if (v !== undefined) body[k] = v;
+  return body;
+}
+
+export function register(server, call, { out, text }) {
+  server.tool(
+    '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. ' +
+      '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. ' +
+      '🚨 A confirmed write. KM Hub answers 409 with the exact before and after; say that to the person, wait for a ' +
+      'real yes in this turn, then call again with the confirm_token and the same arguments.',
+    {
+      brand_values: z
+        .string()
+        .nullable()
+        .optional()
+        .describe('The full brand voice text, up to 4000 characters. It REPLACES what is there. Send null to clear it.'),
+      sign_emails_as: z
+        .string()
+        .nullable()
+        .optional()
+        .describe('The name every email is signed with, for example "Mark" or "Mark and the Twisty Art team". Send null to clear it.'),
+      confirm_token: CONFIRM_TOKEN,
+    },
+    async (args) => {
+      const r = await call('PATCH', '/knowledge/voice', defined(args));
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_set_writing_rules',
+    'Set the house writing rules: the standing instructions every message the AI writes for this business must obey, ' +
+      'for example "never quote a price in the first email", "always offer a phone call", "never call our performers ' +
+      'clowns". They are mandatory, not style, and they apply to every AI writer including automatic ones. ' +
+      'Use append to add one rule to the end (the usual case, and safe); use rules only when the person wants the whole ' +
+      'list rewritten, and then send every rule they want kept, because rules replaces the list. km_get_brand_voice ' +
+      'shows the current list under voice.house_rules. ' +
+      '🚨 A confirmed write: KM Hub answers 409 with the before and after, the person says yes, you call again with ' +
+      'the confirm_token and the same arguments.',
+    {
+      append: z.string().optional().describe('One or more new rules to add to the end of the list.'),
+      rules: z
+        .string()
+        .nullable()
+        .optional()
+        .describe('The complete list of rules, one per line, up to 3000 characters. Replaces the list. Send null to clear every rule.'),
+      confirm_token: CONFIRM_TOKEN,
+    },
+    async (args) => {
+      const r = await call('PUT', '/knowledge/writing-rules', defined(args));
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_set_service_rule',
+    'Give one service its own writing rule: an instruction the AI must follow whenever a message mentions that ' +
+      'service, for example "Balloon Twisting: always say each child gets one design, never a number of balloons" or ' +
+      '"Face Painting: mention we only use FDA compliant paints". One rule per service; setting it again replaces it, ' +
+      'null removes it. Name the service by package_id or by its exact name from km_get_offers_and_pricing, which ' +
+      'also lists every current rule under service_rules. ' +
+      '🚨 A confirmed write: KM Hub answers 409 with the before and after, the person says yes, you call again with ' +
+      'the confirm_token and the same arguments.',
+    {
+      package_id: z.string().optional().describe('The service package id from km_get_offers_and_pricing (proposal_packages[].id).'),
+      package_name: z.string().optional().describe('Or the exact service name, when you do not have the id.'),
+      rule: z.string().nullable().describe('The rule, up to 1000 characters. Send null to remove this service\'s rule.'),
+      confirm_token: CONFIRM_TOKEN,
+    },
+    async (args) => {
+      const r = await call('PUT', '/knowledge/service-rules', defined(args));
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+}