@kivimedia/kmhub 2.0.0 → 2.9.1

package/tools/sourcing.mjs

@@ -95,6 +95,18 @@ export function register(server, call, { out, text, qs }) {
       keywords: z.array(z.string()).optional().describe('Extra words that should show up on the person or the business.'),
       company_sizes: z.array(z.string()).optional().describe('Company head-count bands, only if the person asked for a size. For example ["1,10", "11,50"].'),
       seniorities: z.array(z.string()).optional().describe('Seniority levels, only if the person asked. For example ["owner", "founder", "director"].'),
+      avoid_keywords: z
+        .array(z.string())
+        .optional()
+        .describe('Words that disqualify a lead, matched whole-word against the company name, job title and snippet. For example ["ticketing", "parking", "dean"]. This narrows a search, it cannot be the only filter.'),
+      keep_keywords: z
+        .array(z.string())
+        .optional()
+        .describe('Words that rescue a lead from an avoid word, but only for the avoid words listed in rescuable_avoid_keywords. For example ["events", "homecoming", "graduation"].'),
+      rescuable_avoid_keywords: z
+        .array(z.string())
+        .optional()
+        .describe('Which avoid_keywords a keep_keyword is allowed to override. Use for avoid words that name a DEPARTMENT rather than a job, since those also catch that department\'s event desk - who is usually the buyer. For example ["director of athletics", "chancellor"]. Leave out to make every avoid word absolute.'),
       outreach_context: z
         .string()
         .optional()
@@ -112,6 +124,15 @@ export function register(server, call, { out, text, qs }) {
         .boolean()
         .optional()
         .describe('Leave this out on the first call: you get the price back and nothing is charged. Set it to true ONLY after the person has been told the price and has agreed to it.'),
+      confirm_token: z
+        .string()
+        .optional()
+        .describe(
+          'Leave this out on the first call. This action needs an explicit yes from the person you are working with: '
+            + 'KM Hub answers 409 with a plain description of exactly what would happen, plus a token. Show them that '
+            + 'description in those words, wait for a real answer, and only then call again with the token and the SAME '
+            + 'arguments. A yes for one action never authorises a different one.',
+        ),
     },
     async (args) => {
       const r = await call('POST', '/sourcing/missions', args);
@@ -157,11 +178,20 @@ export function register(server, call, { out, text, qs }) {
     'Stop a lead scout that is queued or already running. Reach for it the moment someone says stop, cancel, that is enough, or realises the search was set up wrong. Stopping is the money-saving move and is always safe: the workspace is only charged for the lookups already made, never for the work the scout did not do. Anything it already found stays in the pipeline, and any message it already wrote stays as a draft in the Approval Queue. It cannot stop a scout that has already finished, and it will say so plainly rather than pretending. It does not delete anything.',
     {
       mission_id: z.string().describe('The id of the scout to stop, from km_list_lead_scouts or from when it was started.'),
+      confirm_token: z
+        .string()
+        .optional()
+        .describe(
+          'Leave this out on the first call. This action needs an explicit yes from the person you are working with: '
+            + 'KM Hub answers 409 with a plain description of exactly what would happen, plus a token. Show them that '
+            + 'description in those words, wait for a real answer, and only then call again with the token and the SAME '
+            + 'arguments. A yes for one action never authorises a different one.',
+        ),
     },
-    async ({ mission_id }) => {
+    async ({ mission_id, confirm_token }) => {
       const id = String(mission_id || '').trim();
       if (!id) return text('I need the id of the scout to stop it. km_list_lead_scouts will show you which ones are still running.');
-      const r = await call('POST', `/sourcing/missions/${encodeURIComponent(id)}/cancel`, {});
+      const r = await call('POST', `/sourcing/missions/${encodeURIComponent(id)}/cancel`, { confirm_token });
       if (routeMissing(r)) return text(NOT_SUPPORTED);
       return out(r);
     },
@@ -186,6 +216,15 @@ export function register(server, call, { out, text, qs }) {
         .boolean()
         .optional()
         .describe('Leave this out on the first call: you get the price back and nothing is charged. Set it to true ONLY after the person has agreed to the cost.'),
+      confirm_token: z
+        .string()
+        .optional()
+        .describe(
+          'Leave this out on the first call. This action needs an explicit yes from the person you are working with: '
+            + 'KM Hub answers 409 with a plain description of exactly what would happen, plus a token. Show them that '
+            + 'description in those words, wait for a real answer, and only then call again with the token and the SAME '
+            + 'arguments. A yes for one action never authorises a different one.',
+        ),
     },
     async (args) => {
       const r = await call('POST', '/sourcing/company-contacts', args);
@@ -210,6 +249,15 @@ export function register(server, call, { out, text, qs }) {
         .boolean()
         .optional()
         .describe('Leave this out to see the price first without being charged. Set it to true to actually run the check.'),
+      confirm_token: z
+        .string()
+        .optional()
+        .describe(
+          'Leave this out on the first call. This action needs an explicit yes from the person you are working with: '
+            + 'KM Hub answers 409 with a plain description of exactly what would happen, plus a token. Show them that '
+            + 'description in those words, wait for a real answer, and only then call again with the token and the SAME '
+            + 'arguments. A yes for one action never authorises a different one.',
+        ),
     },
     async (args) => {
       const r = await call('POST', '/sourcing/verify-email', args);

package/tools/strategy.mjs

@@ -0,0 +1,146 @@
+/**
+ * Tool family: strategy - the officers, what they proposed, and what was done.
+ *
+ * Workstream B6. Strategy was 2 of 8: the pillar that makes "a COO and beyond"
+ * true rather than aspirational had almost no terminal reach. A connector that
+ * reads the pipeline but cannot see the decisions waiting on the owner, or what was
+ * already done in their name, is a reporting tool rather than an operator.
+ *
+ *   km_list_decisions        -> GET /strategy/decisions
+ *   km_list_ai_officers      -> GET /strategy/officers
+ *   km_list_recommendations  -> GET /strategy/advice
+ *   km_list_ai_activity      -> GET /strategy/activity
+ *   km_list_weekly_interviews-> GET /strategy/interviews
+ *
+ * 🚨 READ ONLY, and approval especially so. Approving a COO proposal executes real
+ * work against real records: it is the most consequential button in the product and
+ * it deserves its own decision when B8 settles write scope, not to inherit a general
+ * one. Never imply you can approve something.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'strategy';
+
+export const TOOLS = [
+  'km_list_decisions',
+  'km_list_ai_officers',
+  'km_list_recommendations',
+  'km_list_ai_activity',
+  'km_list_weekly_interviews',
+];
+
+export const PROFILES = ['*'];
+
+function routeMissing(r) {
+  return r.status === 404 || r.status === 405 || r.status === 501;
+}
+
+const NOT_SUPPORTED =
+  'Your KM Hub does not expose the AI Team surface to the terminal yet. That is not a fault: the workspace is fine ' +
+  'and every other tool works as normal. The officers, decisions and activity log are all there in the web app at ' +
+  'https://hub.kivimedia.co, and this connector will start reading them once your KM Hub is on a build that publishes them.';
+
+export function register(server, call, { out, text, qs }) {
+  server.tool(
+    'km_list_decisions',
+    'The proposals the COO has put up for a human decision, what each one would actually DO, and how long it has been ' +
+      'waiting. ' +
+      'Call this whenever the user asks what needs them, what is outstanding, or what the AI has suggested, and any time ' +
+      'you are summarising the state of the business. A decision sitting unmade is different from a task not done: ' +
+      'nothing moves until somebody says yes, and the workspace will not chase them for it. ' +
+      '🚨 Lead with `waiting_on_you` and `oldest_waiting_days`. A proposal that has been pending for weeks is usually one ' +
+      'the owner never saw rather than one they decided against, and saying the number out loud is the whole value here. ' +
+      'Read `risk` and `what_it_would_do` before describing anything: they are not all equivalent, and a high-risk ' +
+      'proposal deserves to be presented as one. ' +
+      'Nothing here can approve or reject. That happens in KM Hub, deliberately, because approval executes real work. ' +
+      'Read only.',
+    {
+      status: z
+        .enum(['pending', 'approved', 'rejected', 'executed', 'failed', 'expired'])
+        .optional()
+        .describe('Narrow to one state. "pending" is what is waiting on a person, which is usually the real question.'),
+      limit: z.number().int().min(1).max(100).optional().describe('How many, newest first. Default 30.'),
+    },
+    async ({ status, limit }) => {
+      const r = await call('GET', `/strategy/decisions${qs({ status, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_ai_officers',
+    'Which AI officers this workspace has customised: their key, the name the owner gave them and the personality they ' +
+      'were given. Use it when the user refers to an officer by name and you do not recognise it, or asks who is on ' +
+      'their AI team. An empty list is normal and means they are running the defaults, not that something is missing. ' +
+      'Useful mainly so you address an officer the way the workspace does rather than inventing your own label. Read only.',
+    {},
+    async () => {
+      const r = await call('GET', '/strategy/officers');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_recommendations',
+    'Standing recommendations and insights the workspace has generated for itself, each with its category, impact and ' +
+      'effort where they were recorded. ' +
+      'Use it when the user asks what they should be doing, or before you offer advice of your own: the workspace may ' +
+      'already have said the same thing, and repeating it as though it were new is worse than agreeing with it. ' +
+      '🚨 These are suggestions, not instructions, and some will be stale. Weigh them against what the owner has actually ' +
+      'said they want, and check the date before presenting one as current. Read only.',
+    {
+      limit: z.number().int().min(1).max(100).optional().describe('How many of each, newest or highest priority first. Default 25.'),
+    },
+    async ({ limit }) => {
+      const r = await call('GET', `/strategy/advice${qs({ limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_ai_activity',
+    'What has actually been done in this workspace and by which surface: the app, a worker, a cron, the API or this ' +
+      'terminal. Each entry names the action, the record it touched, and whether it was later UNDONE. ' +
+      'Use it when the user asks what changed, who did something, or whether the AI has been acting on its own. It is ' +
+      'also the right call before you claim nothing has happened: a quiet inbox does not mean a quiet workspace. ' +
+      '🚨 `undone_count` is the honest number and it must not be skipped to look competent. A pattern of undos says ' +
+      'something real about how far a particular automation should be trusted, and the owner is better served knowing it. ' +
+      'Undo itself lives in KM Hub. Read only.',
+    {
+      source: z
+        .string()
+        .optional()
+        .describe('Narrow to one surface, for example app, worker, cron, api or desk. Leave it out for everything.'),
+      limit: z.number().int().min(1).max(200).optional().describe('How many entries, newest first. Default 40.'),
+    },
+    async ({ source, limit }) => {
+      const r = await call('GET', `/strategy/activity${qs({ source, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_weekly_interviews',
+    'The weekly interview sessions: which week, who, what topics were covered, the digest of what the session concluded ' +
+      'and what it wants to ask about next. ' +
+      'Use it when the user mentions their weekly check-in or sit-down, or when you want to know what has recently been ' +
+      'learned about how this business is running. The digests are one of the richest sources of context in the ' +
+      'workspace and almost nothing else reads them. ' +
+      'Full transcripts are deliberately not returned: they are long, and the digest is the part that carries the ' +
+      'conclusion. Read only.',
+    {
+      limit: z.number().int().min(1).max(60).optional().describe('How many sessions, most recent week first. Default 15.'),
+    },
+    async ({ limit }) => {
+      const r = await call('GET', `/strategy/interviews${qs({ limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+}

package/tools/studio.mjs

@@ -0,0 +1,132 @@
+/**
+ * Tool family: studio - what the creation surfaces have actually produced.
+ *
+ * The last seven pages. I argued these could not be closed by reading, on the
+ * grounds that a studio is a place you make things rather than a place with state.
+ * That was wrong. A studio has OUTPUT, and the output is exactly what an owner
+ * wants to know about: what has been made, what is waiting on them, what is
+ * scheduled to go out.
+ *
+ *   km_list_design_assets    -> GET /studio/assets
+ *   km_list_galleries        -> GET /studio/galleries
+ *   km_list_linkedin_content -> GET /studio/linkedin
+ *   km_list_balloon_work     -> GET /studio/balloon
+ *   km_review_queue          -> GET /studio/review
+ *
+ * 🚨 READ ONLY. Generating an image or a post spends money with a provider, and
+ * approving one publishes in the client's name.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'studio';
+
+export const TOOLS = [
+  'km_list_design_assets',
+  'km_list_galleries',
+  'km_list_linkedin_content',
+  'km_list_balloon_work',
+  'km_review_queue',
+];
+
+export const PROFILES = ['content', 'outreach'];
+
+function routeMissing(r) {
+  return r.status === 404 || r.status === 405 || r.status === 501;
+}
+
+const NOT_SUPPORTED =
+  'Your KM Hub does not expose the studios to the terminal yet. That is not a fault: the workspace is fine and every ' +
+  'other tool works as normal. They are there in the web app at https://hub.kivimedia.co.';
+
+export function register(server, call, { out, text, qs }) {
+  server.tool(
+    'km_review_queue',
+    'EVERYTHING across the whole product that is waiting on a human: outreach drafts, SEO posts, LinkedIn posts, COO ' +
+      'proposals and proposed business facts, each with a count and how old the oldest one is. ' +
+      'Call this in any catch-up, any status question, and before telling somebody they are on top of things. ' +
+      '🚨 No single page in KM Hub shows all of this, because every surface owns its own queue. Approval queues are ' +
+      'where work goes to die quietly: nothing sends until a person releases it, nothing chases them, and the owner ' +
+      'usually finds out when a client asks why they never heard back. ' +
+      '🚨 LEAD WITH THE OLDEST, NOT THE LARGEST. Forty drafts written this morning are fine. One draft that has been ' +
+      'waiting six weeks is a client who was ignored. Read only.',
+    {},
+    async () => {
+      const r = await call('GET', '/studio/review');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_design_assets',
+    'Images and design assets the studios have generated, with the template and provider behind each and a link to the ' +
+      'file. ' +
+      'Use it when the user asks what has been made, wants something to reuse, or before generating anything new: ' +
+      'regenerating something that already exists spends money twice for the same picture. ' +
+      'The prompt and inputs are not returned, because they are long and what a person wants is what exists and where. ' +
+      'Read only.',
+    {
+      limit: z.number().int().min(1).max(200).optional().describe('How many assets, newest first. Default 40.'),
+    },
+    async ({ limit }) => {
+      const r = await call('GET', `/studio/assets${qs({ limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_galleries',
+    'The galleries this business publishes, whether each is active, and how many items are in them. ' +
+      '🚨 An ACTIVE gallery with no active items is a public page showing nothing, which is worse than not having one ' +
+      'at all, and nobody notices because the page still loads. That combination is worth raising unprompted. ' +
+      'Use it before advising anything about what buyers see before they enquire. Building a gallery happens in KM Hub. ' +
+      '🚨 These are the PUBLIC gallery pages on the website, and they have nothing to do with the photos that ride inside ' +
+      'an outreach email. If the question is about pictures in an email, this is the wrong tool and an empty answer here ' +
+      'means nothing: use km_list_work_photos and km_attach_draft_photos. ' +
+      'Read only.',
+    {},
+    async () => {
+      const r = await call('GET', '/studio/galleries');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_linkedin_content',
+    'LinkedIn posts the workspace has produced: the hook archetype each uses, its status, when it is scheduled, and a ' +
+      'preview of the body. ' +
+      'Use it when the user asks about their LinkedIn presence, what is going out, or what is waiting on them. ' +
+      '🚨 Read `by_hook`. A workspace using one hook archetype for everything becomes predictable, and predictable is ' +
+      'invisible on LinkedIn. That is a more useful observation than the post count. `awaiting_approval` is the other ' +
+      'number worth naming: those are written and going nowhere. Publishing happens in KM Hub. Read only.',
+    {
+      limit: z.number().int().min(1).max(200).optional().describe('How many posts, newest first. Default 40.'),
+    },
+    async ({ limit }) => {
+      const r = await call('GET', `/studio/linkedin${qs({ limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_balloon_work',
+    'Balloon designs and the render runs behind them: the event, the guest count, the status, and whether each design ' +
+      'ever reached a proposal. ' +
+      '🚨 `designs_on_a_proposal` against the design count is the number that matters. A design that never reached a ' +
+      'proposal is work that was done and never sold, and that gap is invisible on any single screen. ' +
+      'Rendering costs money with an image provider and happens in KM Hub. Read only.',
+    {
+      limit: z.number().int().min(1).max(100).optional().describe('How many designs and runs, newest first. Default 30.'),
+    },
+    async ({ limit }) => {
+      const r = await call('GET', `/studio/balloon${qs({ limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+}

package/tools/venueradar.mjs

@@ -0,0 +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);
+    },
+  );
+}

package/tools/voice.mjs

@@ -0,0 +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);
+    },
+  );
+}