@kivimedia/kmhub 2.0.0 → 2.9.1

package/tools/flows.mjs

@@ -0,0 +1,261 @@
+/**
+ * Tool family: flows - the automation that runs whether anybody is watching.
+ *
+ * Workstreams B2, B3 and B4. Sequences, workflows, enquiry capture, gambits,
+ * forms, questionnaires, SMS, spend and job costing all ran invisibly to the
+ * terminal.
+ *
+ * 🚨 The worst gap here was collision. A connector that cannot see a running
+ * sequence will happily propose writing to somebody it is already emailing, and two
+ * messages from one business on one day is how a good prospect is lost.
+ *
+ * 🚨 READ ONLY, except km_send_sms: one text the owner approved word for word, gated
+ * server-side by a confirm token. Enrolling, pausing and firing automation act on real
+ * people and stay in the web app.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'flows';
+
+export const TOOLS = [
+  'km_list_sequences',
+  'km_list_workflows',
+  'km_inquiry_sources',
+  'km_list_gambits',
+  'km_list_forms',
+  'km_list_questionnaires',
+  'km_list_sms',
+  'km_send_sms',
+  'km_list_expenses',
+  'km_list_job_costs',
+  'km_list_rentals',
+  'km_music_settings',
+];
+
+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_sequences',
+    'Who is enrolled in an automated sequence, which step they are on, when the next message goes, and why anybody ' +
+      'stopped. ' +
+      '🚨 CALL THIS BEFORE DRAFTING TO ANYONE. `actively_enrolled` is the number that matters: those contacts are ' +
+      'already being messaged automatically. Writing to somebody a sequence is mid-way through means two messages from ' +
+      'one business on one day, which reads as chaotic and loses good prospects. It is the single most valuable check ' +
+      'in this family and it is invisible everywhere else. ' +
+      '`stop_reason` is worth reading too: the same reason recurring is a sequence problem, not bad luck. Read only.',
+    {
+      status: z.string().optional().describe('Narrow to one state, for example active, stopped or completed.'),
+      limit: z.number().int().min(1).max(200).optional().describe('How many enrolments, newest first. Default 50.'),
+    },
+    async ({ status, limit }) => {
+      const r = await call('GET', `/flows/sequences${qs({ status, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_workflows',
+    'The automations configured on this workspace, what triggers each one, and whether it is switched on. ' +
+      'Use it before telling anybody that nothing will happen automatically, and when something occurred that nobody ' +
+      'remembers doing. An active workflow acts without a human present, so "I did not send that" and "nothing was ' +
+      'sent" are different claims and this tool separates them. ' +
+      'Step definitions are not returned: what matters is what fires and whether it is on. Read only.',
+    {},
+    async () => {
+      const r = await call('GET', '/flows/workflows');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_inquiry_sources',
+    'Where enquiries actually came from, counted by source and by status. ' +
+      'Use it whenever the user asks where their work comes from, or before recommending they spend more effort ' +
+      'anywhere. 🚨 The answer is very often different from what the owner believes, and that gap is one of the more ' +
+      'valuable things you can show them. Read only.',
+    {
+      limit: z.number().int().min(1).max(200).optional().describe('How many enquiries to count over, newest first. Default 50.'),
+    },
+    async ({ limit }) => {
+      const r = await call('GET', `/flows/inquiries${qs({ limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_gambits',
+    'The lead gambits configured on this workspace. Use it when the user mentions a gambit by name or asks what is set ' +
+      'up. Configuring one happens in KM Hub. Read only.',
+    {},
+    async () => {
+      const r = await call('GET', '/flows/gambits');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_forms',
+    'The booking and lead forms on this workspace and which are actually live. ' +
+      'A live form is a public front door, so `live_count` of zero is worth saying out loud: it means there is no route ' +
+      'for somebody to enquire through, however good the marketing is. Use it before advising anything about capturing ' +
+      'leads. Field configuration is not returned; editing happens in KM Hub. Read only.',
+    {},
+    async () => {
+      const r = await call('GET', '/flows/forms');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_questionnaires',
+    'Questionnaires sent to clients, and whether they were viewed and answered. ' +
+      '🚨 `sent_but_unanswered` is the number to lead with. Each one is event detail nobody has, and missing detail ' +
+      'does not stay quiet: it surfaces on the day rather than politely in advance. Answers themselves live in KM Hub. ' +
+      'Read only.',
+    {
+      limit: z.number().int().min(1).max(200).optional().describe('How many, newest first. Default 50.'),
+    },
+    async ({ limit }) => {
+      const r = await call('GET', `/flows/questionnaires${qs({ limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_sms',
+    'Text messages in and out of the business line, grouped into threads, with who each is with, direction and the ' +
+      'words. Texts the owner typed in the Quo app on their phone are included, so a thread is the whole exchange. ' +
+      'Use it when the user asks what came in by text, what a client texted, or whether somebody was actually reached. ' +
+      'Without arguments you get the latest texts plus `threads`, where `awaiting_your_reply: true` means the customer ' +
+      'had the last word. To read one conversation in order, pass `thread_of` with any message id from it, or ' +
+      '`client_id`. ' +
+      '🚨 An inbound text nobody answered is the fastest-decaying message a business gets: people who text expect a ' +
+      'text back, and an hour is already late. Phone numbers are deliberately not returned. To answer, use km_send_sms.',
+    {
+      limit: z.number().int().min(1).max(200).optional().describe('How many messages. Default 50.'),
+      thread_of: z.string().optional().describe('Any message id in a conversation: returns that whole thread, oldest first.'),
+      client_id: z.string().optional().describe('A client id: returns the texts linked to that client, oldest first.'),
+    },
+    async ({ limit, thread_of, client_id }) => {
+      const r = await call('GET', `/flows/sms${qs({ limit, thread_of, client_id })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_send_sms',
+    'Send ONE text message to a customer from the business line. It is a real text on their phone and cannot be ' +
+      'unsent, and it is logged on the client\'s timeline and in km_list_sms automatically. ' +
+      'Pick the recipient ONE way: `reply_to_message_id` (a message id from km_list_sms - answers that thread without ' +
+      'the number ever passing through this chat), `client_id`, or `to` (a phone number the user gave you). ' +
+      '🚨 Write the text, show the user the exact words, and send only the words they approved. The first call returns ' +
+      'a confirmation carrying a sentence written by the server about what will happen, plus a token. Read that ' +
+      'sentence to the user as it is, get a yes to THIS text, then call again with the same arguments and ' +
+      'confirm_token. Any change to the words needs a new confirmation. Keep it short and human: a text, not an email.',
+    {
+      text: z.string().describe('The exact words to send, as the user approved them.'),
+      reply_to_message_id: z.string().optional().describe('Answer this thread: a message id from km_list_sms.'),
+      client_id: z.string().optional().describe('Text this client at the phone number on their record.'),
+      to: z.string().optional().describe('A phone number the user gave you, when there is no thread or client.'),
+      confirm_token: z
+        .string()
+        .optional()
+        .describe('Only on the second call, after the user read the confirmation sentence and said yes. Never invent one.'),
+    },
+    async ({ text: words, reply_to_message_id, client_id, to, confirm_token }) => {
+      const body = { text: words };
+      if (reply_to_message_id) body.reply_to_message_id = String(reply_to_message_id);
+      if (client_id) body.client_id = String(client_id);
+      if (to) body.to = String(to);
+      if (confirm_token) body.confirm_token = String(confirm_token);
+      const r = await call('POST', '/flows/sms/send', body);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_expenses',
+    'What has been spent in a window, split into what is billable to a client and what the business absorbs, with ' +
+      'totals by category. Defaults to the last 90 days. ' +
+      '🚨 `absorbed` is the number that decides whether a busy month was a profitable one, and it is the one nobody ' +
+      'looks at. The money tools answer what came IN; without this you can describe a healthy-looking month with no idea ' +
+      'whether any of it was kept. All amounts are in CENTS. 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 entries. Default 100. Check `truncated` before trusting a total.'),
+    },
+    async ({ from, to, limit }) => {
+      const r = await call('GET', `/ops/expenses${qs({ from, to, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_job_costs',
+    'Jobs that have been costed, with the overhead and target profit assumptions behind each. ' +
+      '🚨 Those percentages are ASSUMPTIONS the owner set when costing the job, NOT margin achieved. Describing an ' +
+      'intended margin as a delivered one is the most misleading thing you could do with this data, so say "targeted" ' +
+      'rather than "made". Line-item detail lives in KM Hub. Read only.',
+    {
+      limit: z.number().int().min(1).max(100).optional().describe('How many costed jobs, newest first. Default 25.'),
+    },
+    async ({ limit }) => {
+      const r = await call('GET', `/ops/job-costing${qs({ limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_rentals',
+    'Stock holds and the rental lines sitting on proposals: what is held, for whom, between which dates, and what is ' +
+      'reserved. ' +
+      '🚨 A HOLD is stock promised to somebody who has NOT committed. An expiring hold that nobody chases ' +
+      'silently releases kit a buyer still believes is theirs, which is worse than never holding it, so ' +
+      '`holds_with_an_expiry` is worth raising. Amounts are in CENTS. Releasing or extending a hold happens in KM Hub. ' +
+      'Read only.',
+    {
+      limit: z.number().int().min(1).max(200).optional().describe('How many holds and rental lines. Default 50.'),
+    },
+    async ({ limit }) => {
+      const r = await call('GET', `/ops/rentals${qs({ limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_music_settings',
+    'What clients may request on the public music page: the per-event request limit, whether off-catalogue requests are ' +
+      'allowed, whether remaining requests are shown, and whether Spotify is connected. ' +
+      'Use it before advising anything about music requests for an event. Off-catalogue requests are the ones that create ' +
+      'work on the day, so whether they are allowed matters more than the limit itself. Read only.',
+    {},
+    async () => {
+      const r = await call('GET', '/ops/music');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+}

package/tools/forms.mjs

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

package/tools/gols.mjs

@@ -0,0 +1,134 @@
+/**
+ * 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);
+    },
+  );
+}