@kivimedia/kmhub 2.9.1 → 2.11.0

package/tools/forms.mjs

@@ -1,158 +1,158 @@
-/**
- * forms.mjs - reading and editing the questions on a public booking form.
- *
- * WHY THIS FAMILY EXISTS. km_list_forms in the flows family says which forms are
- * live and then stops: "Field configuration is not returned; editing happens in
- * KM Hub." On 27-Aug-2026 Mark Fuller found his live booking form asking every
- * customer for a phone number twice, tried to fix it from the terminal, and could
- * not. There was no tool that could even SEE a form's fields. Worse, the web app
- * has no editor for the built-in required flags at all, so for half of this there
- * was nowhere to go.
- *
- * 🚨 A BOOKING FORM IS A PAGE ON THE OPEN INTERNET. Every other write reachable
- * from the terminal changes something internal that a person can quietly correct.
- * This one changes what a stranger is asked. That is why the edit is a confirmed
- * write: KM Hub answers 409 with a sentence naming the questions being changed,
- * and nothing happens until a human has said yes to that sentence.
- *
- * The family contract this file follows is documented in ./README.md.
- */
-import { z } from 'zod';
-
-export const FAMILY = 'forms';
-
-export const TOOLS = ['km_get_form_fields', 'km_update_form_fields'];
-
-export const PROFILES = ['outreach'];
-
-/**
- * Is this a 404 because the ROUTE does not exist, or because the FORM does not?
- *
- * Both families of 404 come back on the same wire, and conflating them would tell
- * an owner "your KM Hub is too old" when the truth is "you gave me the wrong id".
- * The route table's own 404 is the one that carries a `routes` list (index.ts
- * generates it so the list can never drift); a handler's not_found never does.
- */
-function routeMissing(r) {
-  if (r.status === 405 || r.status === 501) return true;
-  return r.status === 404 && Array.isArray(r.data?.routes);
-}
-
-const NOT_SUPPORTED =
-  'This KM Hub is running a version that cannot read or edit form fields from the terminal yet. The workspace is fine ' +
-  'and every other tool works as normal. Form fields are editable in the web app at https://hub.kivimedia.co.';
-
-const optionSchema = z.union([
-  z.string().min(1).max(200),
-  z.object({
-    value: z.string().min(1).max(200).describe('What gets stored and, if tag_answer is on, becomes the tag.'),
-    label: z.string().min(1).max(200).optional().describe('What the customer reads. Defaults to the value.'),
-  }),
-]);
-
-const FIELD_TYPES = ['text', 'textarea', 'select', 'radio', 'checkbox', 'date', 'phone', 'email'];
-
-export function register(server, call, { out, text }) {
-  server.tool(
-    'km_get_form_fields',
-    'Every question one booking form asks: the built-in ones the page renders itself (phone, zip, surface type, ' +
-      'preferred date and time, how they heard about you, guests of honour) with whether each is required, plus this ' +
-      "workspace's own custom questions with their type, options and keys. Also returns a warnings list for anything " +
-      'the form asks TWICE, which is invisible in the data because a built-in question and a custom one live in ' +
-      'different places and only meet on the rendered page. Use it before advising anything about a form, and always ' +
-      'before editing one, because the keys you need for an edit are only here. Get the form id from km_list_forms. ' +
-      'Read only.',
-    {
-      form_id: z.string().describe('UUID of the form. km_list_forms returns it. A slug will not work here.'),
-    },
-    async ({ form_id }) => {
-      const r = await call('GET', `/forms/${encodeURIComponent(String(form_id || '').trim())}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_update_form_fields',
-    'Change the questions on a booking form: remove a custom question, add one, edit one, or make a built-in question ' +
-      'required or optional. Use it when the owner says the form asks something twice, asks for the wrong thing, is ' +
-      'missing a question, or should stop making something compulsory. ' +
-      '🚨 THIS FORM IS A PUBLIC PAGE. Whatever you change here is what the next customer is asked. Making a field ' +
-      'required blocks every submission that leaves it blank, so a careless required flag is an outage nobody sees ' +
-      'until enquiries stop arriving. Run km_get_form_fields first and work from the real keys: this tool refuses a ' +
-      'key that is not on the form rather than quietly doing nothing. ' +
-      'Removing a custom field stops the question being asked from now on and does NOT delete answers already ' +
-      'collected. Only the built-in phone question reaches the client record in the CRM; a custom phone field is ' +
-      'stored on the submission and nowhere else, which is usually the reason a form has two of them.',
-    {
-      form_id: z.string().describe('UUID of the form, from km_list_forms or km_get_form_fields.'),
-      remove: z
-        .array(z.string())
-        .optional()
-        .describe('Keys of custom fields to stop asking, e.g. ["field_3"]. Keys come from km_get_form_fields.'),
-      add: z
-        .array(
-          z.object({
-            label: z.string().min(1).max(200).describe('The question the customer reads.'),
-            type: z.enum(FIELD_TYPES).describe('select, radio and checkbox need options. phone renders a tel input.'),
-            required: z.boolean().optional().describe('True makes it compulsory. Leave it out for optional.'),
-            placeholder: z.string().max(200).optional().describe('Grey hint text inside the box.'),
-            options: z.array(optionSchema).optional().describe('The choices, for select, radio and checkbox.'),
-            tag_answer: z
-              .boolean()
-              .optional()
-              .describe(
-                "Turn the customer's answer into a tag on their client record, so that segment can be emailed later. " +
-                  'Only allowed on select, radio and checkbox: on free text it would create a new tag for every ' +
-                  'spelling a customer uses.',
-              ),
-          }),
-        )
-        .optional()
-        .describe('New questions. Keys are assigned automatically unless you supply one.'),
-      update: z
-        .array(
-          z.object({
-            key: z.string().describe('Key of the existing custom field to change.'),
-            label: z.string().min(1).max(200).optional(),
-            type: z.enum(FIELD_TYPES).optional(),
-            required: z.boolean().optional(),
-            placeholder: z.string().max(200).nullable().optional().describe('Send null to clear it.'),
-            options: z.array(optionSchema).optional(),
-            tag_answer: z.boolean().optional(),
-          }),
-        )
-        .optional()
-        .describe('Changes to existing custom questions. Anything you leave out stays as it is.'),
-      built_in_required: z
-        .object({
-          phone: z.boolean().optional(),
-          zip: z.boolean().optional(),
-          surface: z.boolean().optional(),
-          preferredDate: z.boolean().optional(),
-          preferredTime: z.boolean().optional(),
-          heardAbout: z.boolean().optional(),
-          guestOfHonor: z.boolean().optional(),
-        })
-        .optional()
-        .describe(
-          'Make the page\'s own questions compulsory or not, e.g. {"phone": true}. These are the only built-in fields ' +
-            'that exist; any other name is refused rather than saved where nothing would read it.',
-        ),
-      confirm_token: z
-        .string()
-        .optional()
-        .describe(
-          'Leave this out on the first call. This action changes a public page, so it needs an explicit yes from the '
-            + 'person you are working with: KM Hub answers 409 with a plain description of exactly which questions '
-            + 'would change, 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 change never authorises a different one.',
-        ),
-    },
-    async ({ form_id, ...changes }) => {
-      const r = await call('PATCH', `/forms/${encodeURIComponent(String(form_id || '').trim())}/fields`, changes);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-}
+/**
+ * forms.mjs - reading and editing the questions on a public booking form.
+ *
+ * WHY THIS FAMILY EXISTS. km_list_forms in the flows family says which forms are
+ * live and then stops: "Field configuration is not returned; editing happens in
+ * KM Hub." On 27-Aug-2026 Mark Fuller found his live booking form asking every
+ * customer for a phone number twice, tried to fix it from the terminal, and could
+ * not. There was no tool that could even SEE a form's fields. Worse, the web app
+ * has no editor for the built-in required flags at all, so for half of this there
+ * was nowhere to go.
+ *
+ * 🚨 A BOOKING FORM IS A PAGE ON THE OPEN INTERNET. Every other write reachable
+ * from the terminal changes something internal that a person can quietly correct.
+ * This one changes what a stranger is asked. That is why the edit is a confirmed
+ * write: KM Hub answers 409 with a sentence naming the questions being changed,
+ * and nothing happens until a human has said yes to that sentence.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'forms';
+
+export const TOOLS = ['km_get_form_fields', 'km_update_form_fields'];
+
+export const PROFILES = ['outreach'];
+
+/**
+ * Is this a 404 because the ROUTE does not exist, or because the FORM does not?
+ *
+ * Both families of 404 come back on the same wire, and conflating them would tell
+ * an owner "your KM Hub is too old" when the truth is "you gave me the wrong id".
+ * The route table's own 404 is the one that carries a `routes` list (index.ts
+ * generates it so the list can never drift); a handler's not_found never does.
+ */
+function routeMissing(r) {
+  if (r.status === 405 || r.status === 501) return true;
+  return r.status === 404 && Array.isArray(r.data?.routes);
+}
+
+const NOT_SUPPORTED =
+  'This KM Hub is running a version that cannot read or edit form fields from the terminal yet. The workspace is fine ' +
+  'and every other tool works as normal. Form fields are editable in the web app at https://hub.kivimedia.co.';
+
+const optionSchema = z.union([
+  z.string().min(1).max(200),
+  z.object({
+    value: z.string().min(1).max(200).describe('What gets stored and, if tag_answer is on, becomes the tag.'),
+    label: z.string().min(1).max(200).optional().describe('What the customer reads. Defaults to the value.'),
+  }),
+]);
+
+const FIELD_TYPES = ['text', 'textarea', 'select', 'radio', 'checkbox', 'date', 'phone', 'email'];
+
+export function register(server, call, { out, text }) {
+  server.tool(
+    'km_get_form_fields',
+    'Every question one booking form asks: the built-in ones the page renders itself (phone, zip, surface type, ' +
+      'preferred date and time, how they heard about you, guests of honour) with whether each is required, plus this ' +
+      "workspace's own custom questions with their type, options and keys. Also returns a warnings list for anything " +
+      'the form asks TWICE, which is invisible in the data because a built-in question and a custom one live in ' +
+      'different places and only meet on the rendered page. Use it before advising anything about a form, and always ' +
+      'before editing one, because the keys you need for an edit are only here. Get the form id from km_list_forms. ' +
+      'Read only.',
+    {
+      form_id: z.string().describe('UUID of the form. km_list_forms returns it. A slug will not work here.'),
+    },
+    async ({ form_id }) => {
+      const r = await call('GET', `/forms/${encodeURIComponent(String(form_id || '').trim())}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_update_form_fields',
+    'Change the questions on a booking form: remove a custom question, add one, edit one, or make a built-in question ' +
+      'required or optional. Use it when the owner says the form asks something twice, asks for the wrong thing, is ' +
+      'missing a question, or should stop making something compulsory. ' +
+      '🚨 THIS FORM IS A PUBLIC PAGE. Whatever you change here is what the next customer is asked. Making a field ' +
+      'required blocks every submission that leaves it blank, so a careless required flag is an outage nobody sees ' +
+      'until enquiries stop arriving. Run km_get_form_fields first and work from the real keys: this tool refuses a ' +
+      'key that is not on the form rather than quietly doing nothing. ' +
+      'Removing a custom field stops the question being asked from now on and does NOT delete answers already ' +
+      'collected. Only the built-in phone question reaches the client record in the CRM; a custom phone field is ' +
+      'stored on the submission and nowhere else, which is usually the reason a form has two of them.',
+    {
+      form_id: z.string().describe('UUID of the form, from km_list_forms or km_get_form_fields.'),
+      remove: z
+        .array(z.string())
+        .optional()
+        .describe('Keys of custom fields to stop asking, e.g. ["field_3"]. Keys come from km_get_form_fields.'),
+      add: z
+        .array(
+          z.object({
+            label: z.string().min(1).max(200).describe('The question the customer reads.'),
+            type: z.enum(FIELD_TYPES).describe('select, radio and checkbox need options. phone renders a tel input.'),
+            required: z.boolean().optional().describe('True makes it compulsory. Leave it out for optional.'),
+            placeholder: z.string().max(200).optional().describe('Grey hint text inside the box.'),
+            options: z.array(optionSchema).optional().describe('The choices, for select, radio and checkbox.'),
+            tag_answer: z
+              .boolean()
+              .optional()
+              .describe(
+                "Turn the customer's answer into a tag on their client record, so that segment can be emailed later. " +
+                  'Only allowed on select, radio and checkbox: on free text it would create a new tag for every ' +
+                  'spelling a customer uses.',
+              ),
+          }),
+        )
+        .optional()
+        .describe('New questions. Keys are assigned automatically unless you supply one.'),
+      update: z
+        .array(
+          z.object({
+            key: z.string().describe('Key of the existing custom field to change.'),
+            label: z.string().min(1).max(200).optional(),
+            type: z.enum(FIELD_TYPES).optional(),
+            required: z.boolean().optional(),
+            placeholder: z.string().max(200).nullable().optional().describe('Send null to clear it.'),
+            options: z.array(optionSchema).optional(),
+            tag_answer: z.boolean().optional(),
+          }),
+        )
+        .optional()
+        .describe('Changes to existing custom questions. Anything you leave out stays as it is.'),
+      built_in_required: z
+        .object({
+          phone: z.boolean().optional(),
+          zip: z.boolean().optional(),
+          surface: z.boolean().optional(),
+          preferredDate: z.boolean().optional(),
+          preferredTime: z.boolean().optional(),
+          heardAbout: z.boolean().optional(),
+          guestOfHonor: z.boolean().optional(),
+        })
+        .optional()
+        .describe(
+          'Make the page\'s own questions compulsory or not, e.g. {"phone": true}. These are the only built-in fields ' +
+            'that exist; any other name is refused rather than saved where nothing would read it.',
+        ),
+      confirm_token: z
+        .string()
+        .optional()
+        .describe(
+          'Leave this out on the first call. This action changes a public page, so it needs an explicit yes from the '
+            + 'person you are working with: KM Hub answers 409 with a plain description of exactly which questions '
+            + 'would change, 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 change never authorises a different one.',
+        ),
+    },
+    async ({ form_id, ...changes }) => {
+      const r = await call('PATCH', `/forms/${encodeURIComponent(String(form_id || '').trim())}/fields`, changes);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+}

package/tools/gols.mjs

@@ -1,134 +1,144 @@
-/**
- * Tool family: gols - GOLS, the Grand Opening / Event Scout, read and write.
- *
- *   km_gols_finds       -> GET  /gols/finds              (free)
- *   km_gols_scan        -> POST /gols/scan               (AI-metered: price first, then a confirm)
- *   km_gols_push_find   -> POST /gols/finds/:id/push     (confirm: creates a deal + queues a draft)
- *   km_gols_dismiss     -> POST /gols/finds/:id/dismiss  (free)
- *
- * Owners call it "GOLS", "gols", "grand openings", "new businesses opening near
- * me". Every description below says all of those, because on 22-Sep-26 a session
- * asked about "gols" found nothing matching and asked the owner to choose between
- * three guesses.
- *
- * Nothing here contacts anybody. A pushed find's first message is a DRAFT in the
- * Approval Queue. The family contract this file follows is documented in ./README.md.
- */
-import { z } from 'zod';
-
-export const FAMILY = 'gols';
-
-export const TOOLS = ['km_gols_finds', 'km_gols_scan', 'km_gols_push_find', 'km_gols_dismiss'];
-
-export const PROFILES = ['outreach'];
-
-function routeMissing(r) {
-  return r.status === 404 || r.status === 405 || r.status === 501;
-}
-
-const NOT_SUPPORTED =
-  'This KM Hub does not expose GOLS (the grand-opening scout) to the terminal yet. Nothing is broken; it is in the ' +
-  'web app at https://hub.kivimedia.co/gols. Nothing was charged.';
-
-const CONFIRM_TOKEN = z
-  .string()
-  .optional()
-  .describe(
-    'Leave this out on the first call. KM Hub answers 409 with a plain description of exactly what would happen, ' +
-      'plus a token. Show the person that description in those words, wait for a real yes, then call again with the ' +
-      'token and the SAME arguments.',
-  );
-
-export function register(server, call, { out, text, qs }) {
-  server.tool(
-    'km_gols_finds',
-    'GOLS (the Grand Opening / Event Scout, also written "gols"): the businesses KM Hub has found that just opened or ' +
-      'have announced an opening near the owner, each scored hot / warm / cold for how likely it is to book event ' +
-      'services for a grand opening, launch or ribbon cutting. Best first. Reach for it when the owner asks about ' +
-      'GOLS, grand openings, new businesses near them, or "who is opening soon". `when` says "Opens <date>" only ' +
-      'for a date the announcement stated; "In the news <date>" is just the article date, so never call that an ' +
-      'opening date. Free, read only. To find more, use km_gols_scan; to act on one, km_gols_push_find.',
-    {
-      status: z
-        .enum(['new', 'pushed', 'dismissed', 'all'])
-        .optional()
-        .describe('Which finds. Default "new" = not yet acted on. "pushed" = already in the pipeline.'),
-      tier: z.enum(['hot', 'warm', 'cold']).optional().describe('Only this fit tier. Leave out for all.'),
-      city: z.string().optional().describe('Only finds from scans of this city, as the scan was run.'),
-      limit: z.number().int().min(1).max(100).optional().describe('How many. Default 30.'),
-    },
-    async ({ status, tier, city, limit }) => {
-      const r = await call('GET', `/gols/finds${qs({ status, tier, city, limit })}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_gols_scan',
-    [
-      'Run a GOLS scan (grand-opening scout): search the news (and Google Places when connected) for businesses that',
-      'just opened near a city, or with ahead=true for ones that have ANNOUNCED an opening that has not happened yet,',
-      'then score each one for event-services fit and save it. It takes about a minute and returns the finds.',
-      'THIS COSTS MONEY (AI time, billed to the workspace). Call it FIRST without confirm_spend: nothing runs and you',
-      'get the price. Tell the person the price, and on a yes call again with confirm_spend true; KM Hub then answers',
-      '409 with the exact action and a confirm_token, which you show them and send back with the same arguments.',
-      'Never start one on your own initiative. It contacts nobody.',
-    ].join(' '),
-    {
-      city: z.string().describe('The city to scan around, as the person said it. For example "Southfield".'),
-      state: z.string().describe('State or province, for example "MI" or "Ontario".'),
-      radius_miles: z.number().int().min(1).max(200).optional().describe('How far around the city. Default 25.'),
-      lookback_days: z.number().int().min(1).max(120).optional().describe('How far back in the news to look. Default 30.'),
-      ahead: z
-        .boolean()
-        .optional()
-        .describe('true = announced openings that have NOT happened yet (the best time to pitch). Default false = already opened.'),
-      vertical: z.string().optional().describe('The trade to score fit for, only if it differs from the workspace, e.g. "balloon decor".'),
-      zip: z.string().optional().describe('ZIP code, only if the person gave one.'),
-      confirm_spend: z
-        .boolean()
-        .optional()
-        .describe('Leave out on the first call (price only, nothing runs). true ONLY after the person agreed to the price.'),
-      confirm_token: CONFIRM_TOKEN,
-    },
-    async (args) => {
-      const r = await call('POST', '/gols/scan', args);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_gols_push_find',
-    'Take one GOLS grand-opening find into the pipeline: it becomes a deal at Inbound, and KM Hub finds a contact ' +
-      'email for the business and writes a grand-opening approach as a DRAFT in the Approval Queue (a small AI and ' +
-      'lookup cost). Nobody is contacted until a person approves the draft. Needs an explicit yes: the first call ' +
-      'returns 409 with what would happen and a confirm_token. Pushing a find that is already pushed changes nothing.',
-    {
-      find_id: z.string().describe('The find id from km_gols_finds or km_gols_scan.'),
-      confirm_token: CONFIRM_TOKEN,
-    },
-    async ({ find_id, confirm_token }) => {
-      const id = String(find_id || '').trim();
-      if (!id) return text('I need the find id. km_gols_finds lists them.');
-      const r = await call('POST', `/gols/finds/${encodeURIComponent(id)}/push`, { confirm_token });
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_gols_dismiss',
-    'Hide a GOLS grand-opening find the owner does not want, so it stops showing in the working list. Nothing is ' +
-      'deleted and nobody is contacted. Only works on finds still marked new.',
-    { find_id: z.string().describe('The find id from km_gols_finds.') },
-    async ({ find_id }) => {
-      const id = String(find_id || '').trim();
-      if (!id) return text('I need the find id. km_gols_finds lists them.');
-      const r = await call('POST', `/gols/finds/${encodeURIComponent(id)}/dismiss`, {});
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-}
+/**
+ * Tool family: gols - GOLS, the Grand Opening / Event Scout, read and write.
+ *
+ *   km_gols_finds       -> GET  /gols/finds              (free)
+ *   km_gols_scan        -> POST /gols/scan               (AI-metered: price first, then a confirm)
+ *   km_gols_push_find   -> POST /gols/finds/:id/push     (confirm: creates a deal + queues a draft)
+ *   km_gols_dismiss     -> POST /gols/finds/:id/dismiss  (free)
+ *
+ * Owners call it "GOLS", "gols", "grand openings", "new businesses opening near
+ * me". Every description below says all of those, because on 22-Sep-26 a session
+ * asked about "gols" found nothing matching and asked the owner to choose between
+ * three guesses.
+ *
+ * Nothing here contacts anybody. A pushed find's first message is a DRAFT in the
+ * Approval Queue. The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'gols';
+
+export const TOOLS = ['km_gols_finds', 'km_gols_scan', 'km_gols_push_find', 'km_gols_dismiss'];
+
+export const PROFILES = ['outreach'];
+
+function routeMissing(r) {
+  return r.status === 404 || r.status === 405 || r.status === 501;
+}
+
+const NOT_SUPPORTED =
+  'This KM Hub does not expose GOLS (the grand-opening scout) to the terminal yet. Nothing is broken; it is in the ' +
+  'web app at https://hub.kivimedia.co/?page=gols. Nothing was charged.';
+
+const CONFIRM_TOKEN = z
+  .string()
+  .optional()
+  .describe(
+    'Leave this out on the first call. KM Hub answers 409 with a plain description of exactly what would happen, ' +
+      'plus a token. Show the person that description in those words, wait for a real yes, then call again with the ' +
+      'token and the SAME arguments.',
+  );
+
+export function register(server, call, { out, text, qs }) {
+  server.tool(
+    'km_gols_finds',
+    'GOLS (the Grand Opening / Event Scout, also written "gols"): businesses near the owner that announced an opening ' +
+      'and have NOT opened yet, each scored hot / warm / cold for how likely it is to book event services for its ' +
+      'grand opening, launch or ribbon cutting. By default only openings at least 2 weeks away or with the date not ' +
+      'announced, soonest dated first; the reply counts what it hid (already opened, under 2 weeks away, not an ' +
+      'opening) and when "all" shows them. Reach for it when the owner asks about GOLS, grand openings, new businesses ' +
+      'near them, or "who is opening soon". `when` says "Opens <date>" only for a date the announcement stated; ' +
+      '"Announced, opening date not stated" means the article gave no date, so never invent one. `location` is the ' +
+      "business's own town, or null when the article did not say. Free, read only. To find more, use km_gols_scan; " +
+      'to act on one, km_gols_push_find.',
+    {
+      status: z
+        .enum(['new', 'pushed', 'dismissed', 'all'])
+        .optional()
+        .describe('Which finds. Default "new" = not yet acted on. "pushed" = already in the pipeline.'),
+      when: z
+        .enum(['upcoming', 'all'])
+        .optional()
+        .describe('Default "upcoming" = not open yet and at least 2 weeks out (or date not announced). "all" = every row, including past ones.'),
+      tier: z.enum(['hot', 'warm', 'cold']).optional().describe('Only this fit tier. Leave out for all.'),
+      city: z.string().optional().describe('Only finds from scans of this city, as the scan was run.'),
+      limit: z.number().int().min(1).max(100).optional().describe('How many. Default 30.'),
+    },
+    async ({ status, when, tier, city, limit }) => {
+      const r = await call('GET', `/gols/finds${qs({ status, when, tier, city, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_gols_scan',
+    [
+      'Run a GOLS scan (grand-opening scout): read the last 90 days of opening announcements in the news for ONE US',
+      'county (county + state: the county by name plus its biggest towns) or near a city (city + state), keep only',
+      'businesses that have NOT opened yet (finds that already opened, or that are outside the county, are dropped',
+      'and counted), score each one for event-services fit and save it. A business already on the list is updated,',
+      'not added twice. For several counties, call it once per county; each county is priced on its own. For a place',
+      'outside the US, such as Windsor, Ontario, scan the city. There is no look-back setting and no "recently',
+      'opened" mode. It takes about a minute and returns the finds.',
+      'THIS COSTS MONEY (AI time, billed to the workspace). Call it FIRST without confirm_spend: nothing runs and you',
+      'get the price. Tell the person the price, and on a yes call again with confirm_spend true; KM Hub then answers',
+      '409 with the exact action and a confirm_token, which you show them and send back with the same arguments.',
+      'Never start one on your own initiative. It contacts nobody.',
+    ].join(' '),
+    {
+      county: z
+        .string()
+        .optional()
+        .describe('A US county to scan, as the person said it, for example "Oakland" or "Oakland County". Needs state. Leave out to scan around a city.'),
+      city: z.string().optional().describe('The city to scan around, for example "Southfield". Leave out when you pass county.'),
+      state: z.string().describe('State or province, for example "MI" or "Ontario".'),
+      radius_miles: z.number().int().min(1).max(200).optional().describe('How far around the city (city scans only). Default 25.'),
+      vertical: z.string().optional().describe('The trade to score fit for, only if it differs from the workspace, e.g. "balloon decor".'),
+      zip: z.string().optional().describe('ZIP code, only if the person gave one.'),
+      confirm_spend: z
+        .boolean()
+        .optional()
+        .describe('Leave out on the first call (price only, nothing runs). true ONLY after the person agreed to the price.'),
+      confirm_token: CONFIRM_TOKEN,
+    },
+    async (args) => {
+      const r = await call('POST', '/gols/scan', args);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_gols_push_find',
+    'Take one GOLS grand-opening find into the pipeline: it becomes a deal at Inbound, and KM Hub finds a contact ' +
+      'email for the business and writes a grand-opening approach as a DRAFT in the Approval Queue (a small AI and ' +
+      'lookup cost). Nobody is contacted until a person approves the draft. Needs an explicit yes: the first call ' +
+      'returns 409 with what would happen and a confirm_token. Pushing a find that is already pushed changes nothing.',
+    {
+      find_id: z.string().describe('The find id from km_gols_finds or km_gols_scan.'),
+      confirm_token: CONFIRM_TOKEN,
+    },
+    async ({ find_id, confirm_token }) => {
+      const id = String(find_id || '').trim();
+      if (!id) return text('I need the find id. km_gols_finds lists them.');
+      const r = await call('POST', `/gols/finds/${encodeURIComponent(id)}/push`, { confirm_token });
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_gols_dismiss',
+    'Hide a GOLS grand-opening find the owner does not want, so it stops showing in the working list. Nothing is ' +
+      'deleted and nobody is contacted. Only works on finds still marked new.',
+    { find_id: z.string().describe('The find id from km_gols_finds.') },
+    async ({ find_id }) => {
+      const id = String(find_id || '').trim();
+      if (!id) return text('I need the find id. km_gols_finds lists them.');
+      const r = await call('POST', `/gols/finds/${encodeURIComponent(id)}/dismiss`, {});
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+}