@kivimedia/kmhub 2.9.1 → 2.11.0

package/tools/profile.mjs

@@ -1,118 +1,118 @@
-/**
- * Tool family: profile - who this business IS, and correcting it when it is wrong.
- *
- *   km_get_profile    -> GET   /profile
- *   km_update_profile -> PATCH /profile
- *
- * WHY THIS EXISTS. A connector could already READ enough to notice that a profile
- * was wrong and had no way to fix it. The nearest write was km_propose_business_fact,
- * which lands a PENDING proposal: it does not change the talent category, the
- * timezone or the sending identity, and nothing downstream reads it until a human
- * approves it in the web app. A model that answers "I have recorded that you are a
- * mentalist" on the back of a proposal has told the user something untrue.
- *
- * 🚨 The talent category (verticals) is the field that matters. It decides the
- * flavour every AI writer and every lead scout works in. A magician's workspace
- * that is really a mentalist's produces subtly wrong copy in every direction, and
- * the owner usually cannot tell WHY it sounds off.
- *
- * 🚨 km_update_profile is a confirmed write. KM Hub answers 409 with the exact
- * before -> after sentence it wants approved, written server-side from the live
- * values. Show that sentence and wait for a real answer.
- *
- * The family contract this file follows is documented in ./README.md.
- */
-import { z } from 'zod';
-
-export const FAMILY = 'profile';
-
-export const TOOLS = ['km_get_profile', 'km_update_profile'];
-
-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 business profile to the terminal yet. That is not a fault: the workspace is fine ' +
-  'and every other tool works as normal. The profile is in the web app at https://hub.kivimedia.co under Settings, ' +
-  'and this connector will read and edit it once your KM Hub is on a build that publishes it.';
-
-export function register(server, call, { out, text }) {
-  server.tool(
-    'km_get_profile',
-    'Who this business actually is, as the software understands it: its name, its talent category, the timezone and ' +
-      'currency it works in, the language the AI writes in, and the public email, phone, website and address clients ' +
-      'see on quotes and invoices. This is the live row the web app Settings page reads, not a cached copy. ' +
-      'Call it before writing anything in the business\'s own voice, before quoting a price, and before saying anything ' +
-      'about what they do. ' +
-      '🚨 The talent category is the one to look at hardest. It decides the flavour every AI writer and every lead scout ' +
-      'works in, so a workspace still set to Magician when the person is a Mentalist produces subtly wrong copy ' +
-      'everywhere, and the owner usually cannot tell why it sounds off. If what you see does not match what the person ' +
-      'has told you, say so plainly and offer to correct it with km_update_profile. Do not quietly work around it, and ' +
-      'do not file it as a business-knowledge fact instead: a proposed fact does not change the profile. Read only.',
-    {},
-    async () => {
-      const r = await call('GET', '/profile');
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_update_profile',
-    'Correct the live business profile: the talent category, the business name, the timezone, the currency, the ' +
-      'language the AI writes in, or the public email, phone, website and address. Send only the fields that are wrong. ' +
-      'This is a real change to the live workspace and it takes effect immediately - the web app Settings page will show ' +
-      'the same values a second later. ' +
-      'Call km_get_profile first so you are changing from a value you have actually seen, and so you use vertical keys ' +
-      'from the vocabulary it returns rather than inventing one. ' +
-      '🚨 This needs an explicit yes from the person, in this turn. KM Hub answers 409 with a plain sentence naming ' +
-      'exactly what would change, from what, to what, written by the server from the live values. Put that sentence to ' +
-      'them in those words, wait for a real answer, and only then call again with the confirm_token and the SAME ' +
-      'arguments. Do not treat something said earlier in the conversation as agreement. ' +
-      '🚨 Changing the currency does NOT convert any money already recorded: every stored amount keeps its number and is ' +
-      'simply re-labelled. Changing the talent category does not rewrite anything already written, only work that comes ' +
-      'after it. ' +
-      'The account type (solo or agency), the logo, the default tax rate and the portal colour are NOT editable from ' +
-      'here and no argument unlocks them - they are money, an upload, or something you cannot see the result of from a ' +
-      'terminal. Those stay in KM Hub.',
-    {
-      name: z.string().optional().describe('The business name, as it should appear to clients.'),
-      verticals: z
-        .array(z.string())
-        .optional()
-        .describe(
-          'What this business does, as a list of KM Hub vertical keys, most important first. The valid keys come back '
-            + 'from km_get_profile under editable.verticals_vocabulary - use those exact strings and never invent one. '
-            + 'It cannot be an empty list.',
-        ),
-      timezone: z.string().optional().describe('An IANA zone name, for example Asia/Jerusalem or America/New_York.'),
-      currency: z.string().optional().describe('A three-letter code KM Hub supports: USD, CAD, GBP, EUR, AUD or ILS.'),
-      language: z.string().optional().describe('The language the AI writes to customers in by default: en, he or es.'),
-      public_email: z.string().nullable().optional().describe('The address clients see. Send null to clear it.'),
-      public_phone: z.string().nullable().optional().describe('The number clients see. Send null to clear it.'),
-      website_url: z.string().nullable().optional().describe('Must start with http:// or https://. Send null to clear it.'),
-      address: z.string().nullable().optional().describe('The business address on one line. Send null to clear it.'),
-      confirm_token: z
-        .string()
-        .optional()
-        .describe(
-          'Leave this out on the first call. KM Hub will answer 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.',
-        ),
-    },
-    async (args) => {
-      // Only forward what the caller actually set: an undefined key would be sent
-      // as an absent field anyway, but a null one MEANS "clear this", so the two
-      // must not be flattened together.
-      const body = {};
-      for (const [k, v] of Object.entries(args)) if (v !== undefined) body[k] = v;
-      const r = await call('PATCH', '/profile', body);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-}
+/**
+ * Tool family: profile - who this business IS, and correcting it when it is wrong.
+ *
+ *   km_get_profile    -> GET   /profile
+ *   km_update_profile -> PATCH /profile
+ *
+ * WHY THIS EXISTS. A connector could already READ enough to notice that a profile
+ * was wrong and had no way to fix it. The nearest write was km_propose_business_fact,
+ * which lands a PENDING proposal: it does not change the talent category, the
+ * timezone or the sending identity, and nothing downstream reads it until a human
+ * approves it in the web app. A model that answers "I have recorded that you are a
+ * mentalist" on the back of a proposal has told the user something untrue.
+ *
+ * 🚨 The talent category (verticals) is the field that matters. It decides the
+ * flavour every AI writer and every lead scout works in. A magician's workspace
+ * that is really a mentalist's produces subtly wrong copy in every direction, and
+ * the owner usually cannot tell WHY it sounds off.
+ *
+ * 🚨 km_update_profile is a confirmed write. KM Hub answers 409 with the exact
+ * before -> after sentence it wants approved, written server-side from the live
+ * values. Show that sentence and wait for a real answer.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'profile';
+
+export const TOOLS = ['km_get_profile', 'km_update_profile'];
+
+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 business profile to the terminal yet. That is not a fault: the workspace is fine ' +
+  'and every other tool works as normal. The profile is in the web app at https://hub.kivimedia.co under Settings, ' +
+  'and this connector will read and edit it once your KM Hub is on a build that publishes it.';
+
+export function register(server, call, { out, text }) {
+  server.tool(
+    'km_get_profile',
+    'Who this business actually is, as the software understands it: its name, its talent category, the timezone and ' +
+      'currency it works in, the language the AI writes in, and the public email, phone, website and address clients ' +
+      'see on quotes and invoices. This is the live row the web app Settings page reads, not a cached copy. ' +
+      'Call it before writing anything in the business\'s own voice, before quoting a price, and before saying anything ' +
+      'about what they do. ' +
+      '🚨 The talent category is the one to look at hardest. It decides the flavour every AI writer and every lead scout ' +
+      'works in, so a workspace still set to Magician when the person is a Mentalist produces subtly wrong copy ' +
+      'everywhere, and the owner usually cannot tell why it sounds off. If what you see does not match what the person ' +
+      'has told you, say so plainly and offer to correct it with km_update_profile. Do not quietly work around it, and ' +
+      'do not file it as a business-knowledge fact instead: a proposed fact does not change the profile. Read only.',
+    {},
+    async () => {
+      const r = await call('GET', '/profile');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_update_profile',
+    'Correct the live business profile: the talent category, the business name, the timezone, the currency, the ' +
+      'language the AI writes in, or the public email, phone, website and address. Send only the fields that are wrong. ' +
+      'This is a real change to the live workspace and it takes effect immediately - the web app Settings page will show ' +
+      'the same values a second later. ' +
+      'Call km_get_profile first so you are changing from a value you have actually seen, and so you use vertical keys ' +
+      'from the vocabulary it returns rather than inventing one. ' +
+      '🚨 This needs an explicit yes from the person, in this turn. KM Hub answers 409 with a plain sentence naming ' +
+      'exactly what would change, from what, to what, written by the server from the live values. Put that sentence to ' +
+      'them in those words, wait for a real answer, and only then call again with the confirm_token and the SAME ' +
+      'arguments. Do not treat something said earlier in the conversation as agreement. ' +
+      '🚨 Changing the currency does NOT convert any money already recorded: every stored amount keeps its number and is ' +
+      'simply re-labelled. Changing the talent category does not rewrite anything already written, only work that comes ' +
+      'after it. ' +
+      'The account type (solo or agency), the logo, the default tax rate and the portal colour are NOT editable from ' +
+      'here and no argument unlocks them - they are money, an upload, or something you cannot see the result of from a ' +
+      'terminal. Those stay in KM Hub.',
+    {
+      name: z.string().optional().describe('The business name, as it should appear to clients.'),
+      verticals: z
+        .array(z.string())
+        .optional()
+        .describe(
+          'What this business does, as a list of KM Hub vertical keys, most important first. The valid keys come back '
+            + 'from km_get_profile under editable.verticals_vocabulary - use those exact strings and never invent one. '
+            + 'It cannot be an empty list.',
+        ),
+      timezone: z.string().optional().describe('An IANA zone name, for example Asia/Jerusalem or America/New_York.'),
+      currency: z.string().optional().describe('A three-letter code KM Hub supports: USD, CAD, GBP, EUR, AUD or ILS.'),
+      language: z.string().optional().describe('The language the AI writes to customers in by default: en, he or es.'),
+      public_email: z.string().nullable().optional().describe('The address clients see. Send null to clear it.'),
+      public_phone: z.string().nullable().optional().describe('The number clients see. Send null to clear it.'),
+      website_url: z.string().nullable().optional().describe('Must start with http:// or https://. Send null to clear it.'),
+      address: z.string().nullable().optional().describe('The business address on one line. Send null to clear it.'),
+      confirm_token: z
+        .string()
+        .optional()
+        .describe(
+          'Leave this out on the first call. KM Hub will answer 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.',
+        ),
+    },
+    async (args) => {
+      // Only forward what the caller actually set: an undefined key would be sent
+      // as an absent field anyway, but a null one MEANS "clear this", so the two
+      // must not be flattened together.
+      const body = {};
+      for (const [k, v] of Object.entries(args)) if (v !== undefined) body[k] = v;
+      const r = await call('PATCH', '/profile', body);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+}

package/tools/radar.mjs

@@ -1,173 +1,173 @@
-/**
- * Tool family: radar - the scanners that go looking for work, plus the tail.
- *
- * The last of the parity sweep. KM Hub runs a family of radars: new business
- * openings, milestones, schools, libraries, property, races, conferences, events
- * and the gig marketplaces. They looked like nine separate gaps and they are not:
- * every one is a scout mission with a different kind, so two tools reach all of
- * them, and a radar added next year is readable the day it ships.
- *
- *   km_list_radar_scans     -> GET /radar/missions
- *   km_property_scan        -> GET /radar/communities
- *   km_list_marketplace_leads -> GET /radar/finds
- *   km_list_reviews         -> GET /ops/reviews
- *   km_list_trips           -> GET /ops/trips
- *   km_list_catalogs        -> GET /ops/catalogs
- *
- * 🚨 READ ONLY. Starting a scan spends the client's money on lead-sourcing
- * providers. That already exists as km_start_lead_scout, which was built with cost
- * disclosure around it, and this family deliberately adds no second quieter way
- * to spend.
- *
- * The family contract this file follows is documented in ./README.md.
- */
-import { z } from 'zod';
-
-export const FAMILY = 'radar';
-
-export const TOOLS = [
-  'km_list_radar_scans',
-  'km_property_scan',
-  'km_list_marketplace_leads',
-  'km_list_reviews',
-  'km_list_trips',
-  'km_list_catalogs',
-];
-
-export const PROFILES = ['outreach', 'money'];
-
-function routeMissing(r) {
-  return r.status === 404 || r.status === 405 || r.status === 501;
-}
-
-const NOT_SUPPORTED =
-  'Your KM Hub does not expose this surface to the terminal yet. That is not a fault: the workspace is fine and ' +
-  'every other tool works as normal. It is there in the web app at https://hub.kivimedia.co.';
-
-export function register(server, call, { out, text, qs }) {
-  server.tool(
-    'km_list_radar_scans',
-    'Every automated scan KM Hub has run looking for work, whatever kind: new business openings, milestones, schools, ' +
-      'libraries, property, races, conferences, events and marketplace sweeps. Each returns its kind, phase, progress, ' +
-      'a summary of what it found and any error. ' +
-      'Use it when the user asks whether the lead finding is working, why no new leads have appeared, or what the ' +
-      'radars are doing. ' +
-      '🚨 `failed` is the number to lead with. A radar that quietly stopped is a lead SOURCE that stopped, and nothing ' +
-      'else in the workspace will ever mention it: the pipeline just gets thinner for reasons nobody connects to a ' +
-      'broken scan weeks earlier. ' +
-      'Full result blobs are summarised rather than returned whole. Starting a scan costs real money and is done with ' +
-      'km_start_lead_scout or in KM Hub, never here. Read only.',
-    {
-      kind: z.string().optional().describe('Narrow to one radar type, for example the job_type a previous call returned.'),
-      status: z.string().optional().describe('Narrow to one state, for example running, failed or completed.'),
-      limit: z.number().int().min(1).max(150).optional().describe('How many scans, newest first. Default 30.'),
-    },
-    async ({ kind, status, limit }) => {
-      const r = await call('GET', `/radar/missions${qs({ kind, status, limit })}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_property_scan',
-    'The residential communities and owner associations Property Radar has on record for one market: apartment ' +
-      'communities, homeowner and property owner associations (HOA and POA), condo associations and 55+ active adult ' +
-      'communities. Each returns its size, tier, management company, any resident events already evidenced, and how ' +
-      'many reachable STAFF contacts it has. ' +
-      'Two ways in, because the two buyers are filed differently: give a `city` for apartment communities, or a ' +
-      '`county` for associations, which is how the state registries publish them. ' +
-      '🚨 `staff_contacts` is the number that decides whether a row is actionable, not the contact field. An ' +
-      'association is run by paid staff (a lifestyle director, an activities director, a community manager) and by ' +
-      'unpaid volunteers on its board. Only the staff are a lawful outreach target: a board member\'s address is a ' +
-      'personal one, it changes at every annual meeting, and several states forbid the association from releasing it ' +
-      'even to a fellow owner. A row with zero staff contacts needs enrichment before anyone writes to it. ' +
-      '🚨 Timing is the other thing to say out loud. Around nine in ten associations run a calendar fiscal year: the ' +
-      'events budget is drafted from late July, bids close through October and the board votes in November. A pitch ' +
-      'in August is inside the number being written; the same pitch in February is arguing with one already fixed for ' +
-      'twelve months. ' +
-      'Starting a sweep costs real money and is done with km_start_lead_scout or in KM Hub, never here. Read only.',
-    {
-      state: z.string().describe('Two-letter US state code, like TX or VA.'),
-      city: z.string().optional().describe('For apartment communities. Case insensitive.'),
-      county: z.string().optional().describe('For homeowner and property owner associations, which are filed by county. Name only, without the word County.'),
-      assoc_kind: z.string().optional().describe('Narrow to one kind: hoa, poa, condo_assoc, master_assoc, sub_assoc, or any_association for all of them.'),
-      limit: z.number().int().min(1).max(200).optional().describe('How many communities. Default 40.'),
-    },
-    async ({ state, city, county, assoc_kind, limit }) => {
-      const r = await call('GET', `/radar/communities${qs({ state, city, county, assoc_kind, limit })}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_list_marketplace_leads',
-    'Leads swept from the gig marketplaces this business sells on, each with its portal, the event, a fit score, a ' +
-      'margin verdict and whether anybody turned it into a deal or skipped it. ' +
-      '🚨 `unactioned` is the important number: leads that are neither a deal nor skipped. On gig portals speed decides ' +
-      'who gets the work, so an unactioned lead is almost always a LOST one rather than a waiting one, and saying that ' +
-      'plainly is more useful than listing them neutrally. ' +
-      '`skip_reason` is worth reading in bulk: the same reason recurring usually means the sweep is aimed slightly wrong. ' +
-      'Replying happens in KM Hub. Read only.',
-    {
-      limit: z.number().int().min(1).max(200).optional().describe('How many leads, newest first. Default 40.'),
-    },
-    async ({ limit }) => {
-      const r = await call('GET', `/radar/finds${qs({ limit })}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_list_reviews',
-    'Reviews this business has received and requested, with platform, rating, the text, and whether each was replied to. ' +
-      'Use it when the user asks about their reputation, what clients are saying, or before any play that leans on ' +
-      'social proof. ' +
-      '🚨 Lead with `unreplied`. An unanswered review, good or bad, is read by every future buyer who finds it, and a ' +
-      'reply is the cheapest reputation work available. `requested_but_not_received` is the other useful number: those ' +
-      'are asks that went nowhere. Requesting and replying happen in KM Hub. Read only.',
-    {
-      limit: z.number().int().min(1).max(200).optional().describe('How many reviews, newest first. Default 40.'),
-    },
-    async ({ limit }) => {
-      const r = await call('GET', `/ops/reviews${qs({ limit })}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_list_trips',
-    'Mileage logged in a window, with distance and what is reimbursable. Defaults to the last 90 days. ' +
-      'Use it when the user asks about travel, vehicle costs or expenses tied to getting to jobs. ' +
-      'Reimbursement is in CENTS. Unclaimed mileage is money the business is entitled to and routinely does not take, ' +
-      'so a large reimbursable total that never appears in the accounts is worth mentioning. Read only.',
-    {
-      from: z.string().optional().describe('Start date, YYYY-MM-DD. Default 90 days ago.'),
-      to: z.string().optional().describe('End date, YYYY-MM-DD. Default tomorrow.'),
-      limit: z.number().int().min(1).max(500).optional().describe('How many trips. Default 100. Check `truncated` before trusting a total.'),
-    },
-    async ({ from, to, limit }) => {
-      const r = await call('GET', `/ops/trips${qs({ from, to, limit })}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_list_catalogs',
-    'The booking catalogues that decide what a buyer is offered on the public booking pages, which is default, and ' +
-      'which customer types each is aimed at. ' +
-      'Use it before describing what this business sells publicly, because the catalogue and the internal price list ' +
-      'are not the same thing and a buyer only ever sees the catalogue. Prices come from km_get_offers_and_pricing, ' +
-      'never from here. Editing happens in KM Hub. Read only.',
-    {},
-    async () => {
-      const r = await call('GET', '/ops/catalogs');
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-}
+/**
+ * Tool family: radar - the scanners that go looking for work, plus the tail.
+ *
+ * The last of the parity sweep. KM Hub runs a family of radars: new business
+ * openings, milestones, schools, libraries, property, races, conferences, events
+ * and the gig marketplaces. They looked like nine separate gaps and they are not:
+ * every one is a scout mission with a different kind, so two tools reach all of
+ * them, and a radar added next year is readable the day it ships.
+ *
+ *   km_list_radar_scans     -> GET /radar/missions
+ *   km_property_scan        -> GET /radar/communities
+ *   km_list_marketplace_leads -> GET /radar/finds
+ *   km_list_reviews         -> GET /ops/reviews
+ *   km_list_trips           -> GET /ops/trips
+ *   km_list_catalogs        -> GET /ops/catalogs
+ *
+ * 🚨 READ ONLY. Starting a scan spends the client's money on lead-sourcing
+ * providers. That already exists as km_start_lead_scout, which was built with cost
+ * disclosure around it, and this family deliberately adds no second quieter way
+ * to spend.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'radar';
+
+export const TOOLS = [
+  'km_list_radar_scans',
+  'km_property_scan',
+  'km_list_marketplace_leads',
+  'km_list_reviews',
+  'km_list_trips',
+  'km_list_catalogs',
+];
+
+export const PROFILES = ['outreach', 'money'];
+
+function routeMissing(r) {
+  return r.status === 404 || r.status === 405 || r.status === 501;
+}
+
+const NOT_SUPPORTED =
+  'Your KM Hub does not expose this surface to the terminal yet. That is not a fault: the workspace is fine and ' +
+  'every other tool works as normal. It is there in the web app at https://hub.kivimedia.co.';
+
+export function register(server, call, { out, text, qs }) {
+  server.tool(
+    'km_list_radar_scans',
+    'Every automated scan KM Hub has run looking for work, whatever kind: new business openings, milestones, schools, ' +
+      'libraries, property, races, conferences, events and marketplace sweeps. Each returns its kind, phase, progress, ' +
+      'a summary of what it found and any error. ' +
+      'Use it when the user asks whether the lead finding is working, why no new leads have appeared, or what the ' +
+      'radars are doing. ' +
+      '🚨 `failed` is the number to lead with. A radar that quietly stopped is a lead SOURCE that stopped, and nothing ' +
+      'else in the workspace will ever mention it: the pipeline just gets thinner for reasons nobody connects to a ' +
+      'broken scan weeks earlier. ' +
+      'Full result blobs are summarised rather than returned whole. Starting a scan costs real money and is done with ' +
+      'km_start_lead_scout or in KM Hub, never here. Read only.',
+    {
+      kind: z.string().optional().describe('Narrow to one radar type, for example the job_type a previous call returned.'),
+      status: z.string().optional().describe('Narrow to one state, for example running, failed or completed.'),
+      limit: z.number().int().min(1).max(150).optional().describe('How many scans, newest first. Default 30.'),
+    },
+    async ({ kind, status, limit }) => {
+      const r = await call('GET', `/radar/missions${qs({ kind, status, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_property_scan',
+    'The residential communities and owner associations Property Radar has on record for one market: apartment ' +
+      'communities, homeowner and property owner associations (HOA and POA), condo associations and 55+ active adult ' +
+      'communities. Each returns its size, tier, management company, any resident events already evidenced, and how ' +
+      'many reachable STAFF contacts it has. ' +
+      'Two ways in, because the two buyers are filed differently: give a `city` for apartment communities, or a ' +
+      '`county` for associations, which is how the state registries publish them. ' +
+      '🚨 `staff_contacts` is the number that decides whether a row is actionable, not the contact field. An ' +
+      'association is run by paid staff (a lifestyle director, an activities director, a community manager) and by ' +
+      'unpaid volunteers on its board. Only the staff are a lawful outreach target: a board member\'s address is a ' +
+      'personal one, it changes at every annual meeting, and several states forbid the association from releasing it ' +
+      'even to a fellow owner. A row with zero staff contacts needs enrichment before anyone writes to it. ' +
+      '🚨 Timing is the other thing to say out loud. Around nine in ten associations run a calendar fiscal year: the ' +
+      'events budget is drafted from late July, bids close through October and the board votes in November. A pitch ' +
+      'in August is inside the number being written; the same pitch in February is arguing with one already fixed for ' +
+      'twelve months. ' +
+      'Starting a sweep costs real money and is done with km_start_lead_scout or in KM Hub, never here. Read only.',
+    {
+      state: z.string().describe('Two-letter US state code, like TX or VA.'),
+      city: z.string().optional().describe('For apartment communities. Case insensitive.'),
+      county: z.string().optional().describe('For homeowner and property owner associations, which are filed by county. Name only, without the word County.'),
+      assoc_kind: z.string().optional().describe('Narrow to one kind: hoa, poa, condo_assoc, master_assoc, sub_assoc, or any_association for all of them.'),
+      limit: z.number().int().min(1).max(200).optional().describe('How many communities. Default 40.'),
+    },
+    async ({ state, city, county, assoc_kind, limit }) => {
+      const r = await call('GET', `/radar/communities${qs({ state, city, county, assoc_kind, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_marketplace_leads',
+    'Leads swept from the gig marketplaces this business sells on, each with its portal, the event, a fit score, a ' +
+      'margin verdict and whether anybody turned it into a deal or skipped it. ' +
+      '🚨 `unactioned` is the important number: leads that are neither a deal nor skipped. On gig portals speed decides ' +
+      'who gets the work, so an unactioned lead is almost always a LOST one rather than a waiting one, and saying that ' +
+      'plainly is more useful than listing them neutrally. ' +
+      '`skip_reason` is worth reading in bulk: the same reason recurring usually means the sweep is aimed slightly wrong. ' +
+      'Replying happens in KM Hub. Read only.',
+    {
+      limit: z.number().int().min(1).max(200).optional().describe('How many leads, newest first. Default 40.'),
+    },
+    async ({ limit }) => {
+      const r = await call('GET', `/radar/finds${qs({ limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_reviews',
+    'Reviews this business has received and requested, with platform, rating, the text, and whether each was replied to. ' +
+      'Use it when the user asks about their reputation, what clients are saying, or before any play that leans on ' +
+      'social proof. ' +
+      '🚨 Lead with `unreplied`. An unanswered review, good or bad, is read by every future buyer who finds it, and a ' +
+      'reply is the cheapest reputation work available. `requested_but_not_received` is the other useful number: those ' +
+      'are asks that went nowhere. Requesting and replying happen in KM Hub. Read only.',
+    {
+      limit: z.number().int().min(1).max(200).optional().describe('How many reviews, newest first. Default 40.'),
+    },
+    async ({ limit }) => {
+      const r = await call('GET', `/ops/reviews${qs({ limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_trips',
+    'Mileage logged in a window, with distance and what is reimbursable. Defaults to the last 90 days. ' +
+      'Use it when the user asks about travel, vehicle costs or expenses tied to getting to jobs. ' +
+      'Reimbursement is in CENTS. Unclaimed mileage is money the business is entitled to and routinely does not take, ' +
+      'so a large reimbursable total that never appears in the accounts is worth mentioning. Read only.',
+    {
+      from: z.string().optional().describe('Start date, YYYY-MM-DD. Default 90 days ago.'),
+      to: z.string().optional().describe('End date, YYYY-MM-DD. Default tomorrow.'),
+      limit: z.number().int().min(1).max(500).optional().describe('How many trips. Default 100. Check `truncated` before trusting a total.'),
+    },
+    async ({ from, to, limit }) => {
+      const r = await call('GET', `/ops/trips${qs({ from, to, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_catalogs',
+    'The booking catalogues that decide what a buyer is offered on the public booking pages, which is default, and ' +
+      'which customer types each is aimed at. ' +
+      'Use it before describing what this business sells publicly, because the catalogue and the internal price list ' +
+      'are not the same thing and a buyer only ever sees the catalogue. Prices come from km_get_offers_and_pricing, ' +
+      'never from here. Editing happens in KM Hub. Read only.',
+    {},
+    async () => {
+      const r = await call('GET', '/ops/catalogs');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+}