@kivimedia/kmhub 2.0.0 → 2.9.0

package/tools/compare.mjs

@@ -0,0 +1,76 @@
+/**
+ * Tool family: compare - the honest, computed comparison.
+ *
+ * Workstream E1. A comparison in a slide is out of date the day after it is
+ * written. This counts KM Hub's side at the moment somebody asks, from the same
+ * sources the product runs on.
+ *
+ * 🚨 IT COUNTS KM HUB ONLY, ON PURPOSE. The API cannot see a competitor's product,
+ * and a stored figure about somebody else's software is a claim nobody can
+ * re-verify and nobody notices going stale. Booked is counted from the plugin
+ * actually installed on the reader's machine, by the /kmhub:vs-booked command, or
+ * it is reported as not installed. Never fill the gap from memory.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { readFileSync } from 'node:fs';
+
+export const FAMILY = 'compare';
+
+export const TOOLS = ['km_vs_booked'];
+
+export const PROFILES = ['*'];
+
+function routeMissing(r) {
+  return r.status === 404 || r.status === 405 || r.status === 501;
+}
+
+const NOT_SUPPORTED =
+  'Your KM Hub does not publish the comparison route yet. That is not a fault: the workspace is fine and every ' +
+  'other tool works as normal.';
+
+/** The connector owns the tool and reach numbers, so they are read here, not fetched. */
+function localCounts() {
+  try {
+    const caps = JSON.parse(readFileSync(new URL('../capabilities.json', import.meta.url), 'utf8'));
+    return {
+      gui_pages: caps?.counts?.pages ?? null,
+      pages_reachable_from_terminal: caps?.counts?.reachable_from_terminal ?? null,
+      pages_web_only_by_design: caps?.counts?.web_only_by_design ?? null,
+      pages_not_built_yet: caps?.counts?.web_only_not_built_yet ?? null,
+      pillars: caps?.counts?.pillars ?? null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function register(server, call, { out, text }) {
+  server.tool(
+    'km_vs_booked',
+    'The live, counted comparison of KM Hub Terminal Mode against Booked Solid, for when the user asks how the two ' +
+      'compare, whether to switch, or which does more. ' +
+      'Everything it returns about KM Hub is counted at the moment you ask, from the play catalogue, the active play ' +
+      'library and the connector capability map. Nothing is a stored marketing figure. ' +
+      '🚨 IT RETURNS NOTHING ABOUT BOOKED, and `booked` comes back null on purpose. To count Booked, use the installed ' +
+      'Booked Solid client\'s own capability inventory and CLI when that client is available on the same machine. ' +
+      'Treat its documented tool names and play identifiers as the source of the count. If Booked is not installed, ' +
+      'SAY SO and give KM Hub numbers alone. Never quote a Booked ' +
+      'figure from memory: an uncounted number is worse than an absent one, because nobody can tell afterwards which ' +
+      'it was. ' +
+      '🚨 Read `what_booked_does_better` and say at least one true thing in its favour BEFORE anything in KM Hub\'s. ' +
+      'It works with no internet, nothing leaves the client machine, and no subscription sits between somebody and ' +
+      'their own records. A model that produces an all-green comparison is a brochure, and the reader discounts ' +
+      'everything after the first one-sided line. ' +
+      'Read `the_honest_framing` too: these are different SHAPES of product, so a play count alone misleads in both ' +
+      'directions. Read only, sends nothing, changes nothing.',
+    {},
+    async () => {
+      const r = await call('GET', '/compare/terminal');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      if (!r.ok) return out(r);
+      const body = { ...(r.data || {}), kmhub_connector: localCounts() };
+      return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }] };
+    },
+  );
+}

package/tools/core.mjs

@@ -18,6 +18,7 @@ export const FAMILY = 'core';
  */
 export const TOOLS = [
   'km_me',
+  'km_workspaces',
   'km_waiting',
   'km_list_clients',
   'km_create_lead',
@@ -49,6 +50,17 @@ export function register(server, call, { out }) {
     async () => out(await call('GET', '/me')),
   );
 
+  server.tool(
+    'km_workspaces',
+    'Every KM Hub workspace the person at this keyboard belongs to, which single one this connector actually opens, and how to reach the others. ' +
+      'Call it the moment someone talks about a second brand, expects data that is not here, says they switched workspace in the web app, or asks why the numbers look like the wrong business. ' +
+      'The thing it exists to explain: an API key is welded to ONE workspace, so switching brand in the KM Hub web app does not move this connection and never will - the key carries the workspace, not the browser session. Someone can restart Claude all day and still be in the same brand. ' +
+      'It hands out no access and no keys: names and ids only. Reaching another workspace means installing a second connector with a key from that workspace, which the note in the response explains. ' +
+      'It is cheap, it reads, and it changes nothing.',
+    {},
+    async () => out(await call('GET', '/workspaces')),
+  );
+
   server.tool(
     'km_waiting',
     'Raw gate counts and nothing else: how many approvals, new enquiries, open tasks, unpaid invoices and unsigned contracts are sitting in the workspace right now. It is a gauge, not an answer. ' +
@@ -217,6 +229,15 @@ export function register(server, call, { out }) {
         .enum(['pending', 'confirmed'])
         .optional()
         .describe('Default pending (owner reviews); confirmed puts it straight on the calendar.'),
+      confirm_token: z
+        .string()
+        .optional()
+        .describe(
+          'Leave this out on the first call. This action needs an explicit yes from the person you are working with: '
+            + 'KM Hub answers 409 with a plain description of exactly what would happen, plus a token. Show them that '
+            + 'description in those words, wait for a real answer, and only then call again with the token and the SAME '
+            + 'arguments. A yes for one action never authorises a different one.',
+        ),
     },
     async (args) => out(await call('POST', '/bookings', args)),
   );

package/tools/crm.mjs

@@ -123,9 +123,18 @@ export function register(server, call, { out, qs }) {
         .describe('open = still live, won = the work is theirs, lost = they said no, abandoned = it went quiet and is not coming back.'),
       lost_reason: z.string().optional().describe('Why it was lost, in the person\'s own words. Only kept for lost or abandoned.'),
       reason: z.string().optional().describe('A short note kept on the deal history explaining the change.'),
+      confirm_token: z
+        .string()
+        .optional()
+        .describe(
+          'Leave this out on the first call. This action needs an explicit yes from the person you are working with: '
+            + 'KM Hub answers 409 with a plain description of exactly what would happen, plus a token. Show them that '
+            + 'description in those words, wait for a real answer, and only then call again with the token and the SAME '
+            + 'arguments. A yes for one action never authorises a different one.',
+        ),
     },
-    async ({ deal_id, status, lost_reason, reason }) =>
-      out(await call('PATCH', `/deals/${encodeURIComponent(String(deal_id ?? '').trim())}/status`, { status, lost_reason, reason })),
+    async ({ deal_id, status, lost_reason, reason, confirm_token }) =>
+      out(await call('PATCH', `/deals/${encodeURIComponent(String(deal_id ?? '').trim())}/status`, { status, lost_reason, reason, confirm_token })),
   );
 
   server.tool(
@@ -161,7 +170,7 @@ export function register(server, call, { out, qs }) {
     'Add a job to the workspace to-do list, optionally tied to a client or a booking, so a follow-up someone mentioned in passing does not get lost. Good for "chase the deposit on Friday", "send the Hendersons their timeline", "call the venue back". A new task always starts as not done and is never assigned to a particular person, because who does the work is the owner\'s call and not yours. A bare date like 2026-09-14 means the END of that day, so a task due today does not read as late until tomorrow. Creating a task is fully undoable from the AI activity log.',
     {
       name: z.string().describe('What the task is, in one line. This is what the owner will read on their list.'),
-      description: z.string().optional().describe('Any detail that will not fit in the name.'),
+      description: z.string().optional().describe('Any detail that will not fit in the name. Up to 20,000 characters, and a longer one is refused with its length rather than stored short.'),
       due_date: z.string().optional().describe('YYYY-MM-DD, or a full ISO timestamp when the time of day matters.'),
       client_id: z.string().optional().describe('Tie it to a client (UUID), so it shows on their record.'),
       booking_id: z.string().optional().describe('Tie it to a booking (UUID), so it shows against that job.'),

package/tools/dubsado.mjs

@@ -0,0 +1,137 @@
+/**
+ * Tool family: dubsado - the Dubsado lead reply loop.
+ *
+ * For workspaces whose Dubsado account is wired through the Kivi dubsado-bridge
+ * (today: Dazzling Balloons). The bridge polls Dubsado every 5 minutes, LeadIQ
+ * stores each lead and writes an AI reply draft, and the send goes back out
+ * through Dubsado itself so the reply sits in the real project email thread and
+ * comes from the business's own sender.
+ *
+ * The terminal is the editor: there is no regenerate machinery here. Read the
+ * draft, rework the wording with the person in chat, send the final text.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+export const FAMILY = 'dubsado';
+
+export const TOOLS = [
+  'km_dubsado_status',
+  'km_dubsado_leads',
+  'km_dubsado_lead',
+  'km_dubsado_send_reply',
+  'km_dubsado_sync',
+];
+
+export const PROFILES = ['*'];
+
+function routeMissing(r) {
+  return r.status === 404 || r.status === 405 || r.status === 501;
+}
+
+const NOT_SUPPORTED =
+  'This workspace does not have the Dubsado connection yet. That is not a fault: every other tool works as ' +
+  'normal. Connecting a Dubsado account is done by the Kivi Media team.';
+
+export function register(server, call, { out, text, qs, z }) {
+  server.tool(
+    'km_dubsado_status',
+    'Health check for the Dubsado connection: whether the bridge that syncs leads from Dubsado is alive, when ' +
+      'the last sync happened, and the newest lead it has. Call it first in a session about Dubsado leads, and ' +
+      'whenever a lead the person expects to see is missing. If bridge.alive is false, say plainly that syncing ' +
+      'and sending are down until the Kivi Media team revives the session, and do not attempt a send.',
+    {},
+    async () => {
+      const r = await call('GET', '/dubsado/status');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_dubsado_leads',
+    'The Dubsado leads in this workspace, newest first, each with its reply_state: no_draft_yet, ' +
+      'draft_ready_for_review (the AI already wrote a reply nobody approved), approved_awaiting_send, or ' +
+      'reply_sent. Use it to answer "any new inquiries?", to find a lead by name, or to sweep for ' +
+      'draft_ready_for_review leads that deserve attention. New inquiries land here up to ~5 minutes after ' +
+      'they hit Dubsado. This lists; read one lead in full with km_dubsado_lead before judging any draft.',
+    {
+      q: z.string().optional().describe('Search by client name, email, or event type.'),
+      status: z.string().optional().describe('Filter by pipeline stage, e.g. inquiry, qualified, proposal_sent, booked.'),
+      limit: z.number().int().min(1).max(100).optional().describe('How many leads, default 20.'),
+    },
+    async ({ q, status, limit }) => {
+      const r = await call('GET', `/dubsado/leads${qs({ q, status, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_dubsado_lead',
+    'One Dubsado lead in full: contact details, event info, the form answers they submitted, the whole email ' +
+      'thread so far, and every AI reply draft with its state. Accepts the lead_id from km_dubsado_leads (or a ' +
+      '24 character Dubsado job id). Read this BEFORE proposing any reply: the thread and form answers are the ' +
+      'context that makes a reply sound informed instead of canned. Show the newest unsent draft to the person, ' +
+      'take their edits in chat, and only then reach for km_dubsado_send_reply.',
+    {
+      lead_id: z.string().describe('Lead UUID from km_dubsado_leads, or the Dubsado job id.'),
+    },
+    async ({ lead_id }) => {
+      const r = await call('GET', `/dubsado/leads/${encodeURIComponent(String(lead_id || '').trim())}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_dubsado_send_reply',
+    'Send a reply email to a Dubsado lead, through Dubsado, from the business\'s own sender. It lands in the ' +
+      'lead\'s real Dubsado project thread and cannot be unsent, so the person must have seen and approved the ' +
+      'exact final wording first. Pass draft_id for an existing AI draft, with subject and body carrying the ' +
+      'final wording after any edits; or pass just subject + body for a reply written here in the terminal. ' +
+      'The recipient is always the lead\'s own email on file and cannot be changed here. Plain text is fine: ' +
+      'blank lines become paragraphs. The send is refused for leads whose follow-ups were halted and for leads ' +
+      'in a terminal stage like booked or lost. ' +
+      'On success, tell the person it went out, to whom, and with what subject.',
+    {
+      lead_id: z.string().describe('Lead UUID from km_dubsado_leads, or the Dubsado job id.'),
+      draft_id: z.string().optional().describe('UUID of the AI draft being approved (from km_dubsado_lead).'),
+      subject: z.string().optional().describe('Final subject line. Overrides the draft subject when draft_id is given.'),
+      body: z.string().optional().describe('Final reply text. Overrides the draft text when draft_id is given.'),
+      confirm_token: z
+        .string()
+        .optional()
+        .describe(
+          'Leave this out on the first call. This action needs an explicit yes from the person you are working ' +
+            'with: KM Hub answers 409 with a plain description of exactly what would happen, plus a token. Show ' +
+            'them that description in those words, wait for a real answer, and only then call again with the ' +
+            'token and the SAME arguments. A yes for one action never authorises a different one.',
+        ),
+    },
+    async ({ lead_id, ...rest }) => {
+      const r = await call(
+        'POST',
+        `/dubsado/leads/${encodeURIComponent(String(lead_id || '').trim())}/send`,
+        rest,
+      );
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_dubsado_sync',
+    'Ask the bridge to re-pull recent leads from Dubsado now instead of waiting for the next 5 minute poll. ' +
+      'Use it when a lead the person can see in Dubsado has not appeared in km_dubsado_leads. Re-pulled leads ' +
+      'land within about 5 minutes of this call, so check the list again after that, not immediately. ' +
+      'days_back widens how far back the re-pull looks.',
+    {
+      days_back: z.number().int().min(1).max(90).optional().describe('Re-pull leads updated in the last N days.'),
+    },
+    async ({ days_back }) => {
+      const r = await call('POST', '/dubsado/sync', days_back ? { days_back } : {});
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+}

package/tools/exports.mjs

@@ -0,0 +1,128 @@
+/**
+ * Tool family: exports - getting your own data back out, from a terminal.
+ *
+ * This family exists because of one email. A customer with three workspaces asked
+ * for "a full export of all my data, including the most recent", said the system
+ * was hard to navigate, and said he could not work out how to see his invoices.
+ * Everything he asked for was already in KM Hub and already exportable, and there
+ * was still no way to answer him without telling him to go and click through a
+ * screen he had just told us he could not find. A person asking for their own
+ * records should never be handed a navigation problem.
+ *
+ * Four tools:
+ *   km_export_data        one dataset, csv or xlsx
+ *   km_export_everything  the whole workspace, one ZIP of readable CSVs
+ *   km_export_status      how far an export got, and its link once ready
+ *   km_list_exports       what has been exported lately
+ *
+ * These do not build files. They queue the same job the Export Data screen
+ * queues, and the same worker builds it, so an export started here and an export
+ * started in the browser are byte-for-byte the same file.
+ *
+ * 🚨 A DOWNLOAD LINK IS A CREDENTIAL. The signed URL needs no login and lives for
+ * seven days. Hand it to the person who asked, use it to fetch the file, and do
+ * not write it into a document, a commit, a ticket or a chat log that outlives
+ * the download.
+ *
+ * No PROFILES export on purpose. Exporting is not the job of the narrow money,
+ * outreach or content profiles, and a family that pins itself into every profile
+ * makes the profiles meaningless. It ships in `full`, which is the default.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'exports';
+
+export const TOOLS = [
+  'km_export_data',
+  'km_export_everything',
+  'km_export_status',
+  'km_list_exports',
+];
+
+const LINK_WARNING =
+  'The download link that comes back is a signed URL: anyone holding it can fetch the file without signing in, and it expires after seven days. Give it to the person who asked for it and do not paste it anywhere it will be stored.';
+
+const NOT_INSTANT =
+  'The file is built in the background. This returns an export id straight away; call km_export_status with that id until it says ready, which is usually a few seconds and can be a couple of minutes for a large workspace.';
+
+/**
+ * @param {{ tool: Function }} server guarded registrar (see ./README.md)
+ * @param {(method: string, path: string, body?: any) => Promise<{ok:boolean,status:number,data:any}>} call
+ * @param {{ out: Function, text: Function, qs: Function }} helpers
+ */
+export function register(server, call, { out, qs }) {
+  server.tool(
+    'km_export_data',
+    'Export one set of records from this workspace to a spreadsheet file: invoices, bookings, clients, payments, quotes, leads, expenses, gigs, venues, vendors, equipment, team members, or the outreach tables. ' +
+      'Reach for this whenever someone asks to be sent, given, or shown their data outside KM Hub: "send me my invoices", "export the client list", "I need last year in a spreadsheet", "can I get all of this out", "my accountant wants the payments". ' +
+      'It exports every column of the chosen dataset. Narrow it by date with date_from and date_to when the person named a period, and leave both off when they asked for everything. ' +
+      'If they want the whole workspace rather than one dataset, use km_export_everything instead. ' +
+      NOT_INSTANT + ' ' + LINK_WARNING,
+    {
+      dataset: z
+        .string()
+        .describe(
+          'What to export. One of: invoices, bookings, clients, payments, quotes, inquiries, expenses, gigs, venues, vendors, equipment_items, kmhub_export_team_members, outreach_campaigns, outreach_campaign_prospect_status, outreach_replies, outreach_drafts, booking_drafts. Everyday words are understood too: events, jobs and projects mean bookings, contacts and customers mean clients, bills means invoices, leads and enquiries mean inquiries, equipment, team and crew are understood.',
+        ),
+      format: z
+        .enum(['csv', 'xlsx'])
+        .optional()
+        .describe('csv (the default, opens anywhere) or xlsx for Excel.'),
+      date_from: z.string().optional().describe('Only records from this date onward, as YYYY-MM-DD. Leave off for everything.'),
+      date_to: z.string().optional().describe('Only records before this date, as YYYY-MM-DD. Leave off for everything.'),
+      date_field: z
+        .string()
+        .optional()
+        .describe('Which date the range applies to. Defaults to created_at. For bookings, event_date is usually what a person means by "last year".'),
+      label: z.string().optional().describe('A name for this export, shown in the export history. Say what it is, for instance "2025 invoices for the accountant".'),
+    },
+    async ({ dataset, format, date_from, date_to, date_field, label }) =>
+      out(await call('POST', '/exports', { dataset, format, date_from, date_to, date_field, label })),
+  );
+
+  server.tool(
+    'km_export_everything',
+    'Export the ENTIRE workspace as one ZIP file: every booking, lead, deal, client, quote, invoice, payment, venue, vendor, expense, gig, team member, email history, outreach record and Booking Brain artifact, each as its own readable CSV inside the archive. ' +
+      'This is the one to reach for when someone asks for "all my data", "a full export", "everything you have on us", or is leaving and wants their records. ' +
+      'Prefer km_export_data when they named one thing: a person who asked for their invoices does not want a forty-file archive to dig through. ' +
+      'This is a confirmed action. The first call comes back with a sentence describing exactly what will be packaged and a confirm_token. Put that sentence to the person, wait for an explicit yes, then call again with the same inputs plus that token. Never send the token without asking. ' +
+      NOT_INSTANT + ' ' + LINK_WARNING,
+    {
+      label: z.string().optional().describe('A name for this export, shown in the export history.'),
+      confirm_token: z
+        .string()
+        .min(1)
+        .max(4096)
+        .optional()
+        .describe('Only ever the exact token returned in the 409 response, and only after the person has said yes to the sentence that came with it.'),
+    },
+    async ({ label, confirm_token }) =>
+      out(await call('POST', '/exports/everything', { label, ...(confirm_token ? { confirm_token } : {}) })),
+  );
+
+  server.tool(
+    'km_export_status',
+    'Check one export: whether it is still building, what it is doing right now, how many rows it has read, and once it is ready the file size, the row count and the download link. ' +
+      'Call this after km_export_data or km_export_everything, using the export_id they returned. If it is still building, say what it is doing rather than just "working on it", and check again in a few seconds. ' +
+      'A failed export comes back with the reason in error_message, which is usually a date range that matched too many rows. ' +
+      LINK_WARNING,
+    {
+      export_id: z.string().describe('The export_id returned when the export was started.'),
+    },
+    async ({ export_id }) => out(await call('GET', `/exports/${encodeURIComponent(export_id)}`)),
+  );
+
+  server.tool(
+    'km_list_exports',
+    'List the exports built from this workspace recently: what was exported, when, in what format, how big it was and whether it is still available. ' +
+      'Useful when someone asks "did I already pull that", "what did we send the accountant", or when an earlier export id has been lost. ' +
+      'Download links are deliberately not included here. Ask for one export by id with km_export_status to get its link. ' +
+      'This tool only reads. It cannot start or delete an export.',
+    {
+      limit: z.number().int().min(1).max(100).optional().describe('How many to list. Defaults to 20.'),
+    },
+    async ({ limit }) => out(await call('GET', `/exports${qs({ limit })}`)),
+  );
+}

package/tools/fact-review.mjs

@@ -0,0 +1,125 @@
+/**
+ * Tool family: fact-review - the owner confirms or rejects business facts from the terminal.
+ *
+ *   km_list_pending_business_facts -> GET  /knowledge/facts/pending
+ *   km_confirm_business_facts      -> POST /knowledge/facts/confirm  (confirmed write)
+ *   km_reject_business_facts       -> POST /knowledge/facts/reject   (confirmed write)
+ *
+ * WHY THIS EXISTS. km_propose_business_fact could only put a fact in the queue, so
+ * a conversation where the owner said "confirmed, these three are correct" still
+ * ended with "go and click confirm in the web app" (Brant Matthews, 23-Sep-26).
+ * Ziv: "you need to be able to confirm for me". The read and propose tools stay in
+ * knowledge.mjs, untouched in shape; this is the review half in its own family.
+ *
+ * 🚨 Both writes are confirmed writes. KM Hub answers 409 with a server-written
+ * list of the exact facts; put that to the person, wait for a real yes, then call
+ * again with the confirm_token and the SAME fact_ids. Reject is gated too because
+ * a rejection cannot be undone.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'fact-review';
+
+export const TOOLS = ['km_list_pending_business_facts', 'km_confirm_business_facts', 'km_reject_business_facts'];
+
+// Same profiles as the knowledge family that proposes and reads these facts.
+export const PROFILES = ['outreach', 'content', 'money'];
+
+function routeMissing(r) {
+  return r.status === 404 || r.status === 405 || r.status === 501;
+}
+
+const NOT_SUPPORTED =
+  'Your KM Hub cannot review business facts from the terminal yet. Nothing is wrong with the workspace and nothing ' +
+  'was changed. The owner can confirm or reject them in the web app at https://hub.kivimedia.co under Settings, ' +
+  'Connect, Business Knowledge.';
+
+const FACT_IDS = z
+  .array(z.string())
+  .min(1)
+  .max(25)
+  .describe('The ids of the facts, from km_list_pending_business_facts. Up to 25 at once.');
+
+const CONFIRM_TOKEN = z
+  .string()
+  .optional()
+  .describe(
+    'Leave this out on the first call. KM Hub answers 409 with the list to put to the person and a token. Only ' +
+      'after they actually say yes, call again with the token and the SAME fact_ids and reason. A yes for one ' +
+      'list never authorises a different one.',
+  );
+
+const REASON = z
+  .string()
+  .optional()
+  .describe('Optional, one line, in the owner\'s words, for example "Brant confirmed on the call". Kept with the decision.');
+
+/** A 404 from a route that does not exist yet, as opposed to a fact that does not exist. */
+function unsupported(r) {
+  if (!routeMissing(r)) return false;
+  const err = r.data && typeof r.data === 'object' ? r.data.error : undefined;
+  return err !== 'not_found' || /Unknown route/i.test(String(r.data?.message || ''));
+}
+
+export function register(server, call, { out, text }) {
+  server.tool(
+    'km_list_pending_business_facts',
+    'The business facts that are waiting for the owner to say yes or no: things somebody proposed with ' +
+      'km_propose_business_fact, or that KM Hub picked up from an uploaded document or the owner\'s emails. Each one ' +
+      'comes with its id, its exact text and where it came from. Call it when km_get_business_facts reports ' +
+      'pending_proposals above zero, when the person asks what is waiting for them, or before confirming anything, so ' +
+      'you have the ids. NONE of these is confirmed: never use one in a draft, a quote or an answer. Read each to the ' +
+      'owner in its exact words and let them decide. Read only.',
+    {},
+    async () => {
+      const r = await call('GET', '/knowledge/facts/pending');
+      if (unsupported(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_confirm_business_facts',
+    'Confirm business facts the owner says are TRUE, the same as the confirm button in KM Hub under Business ' +
+      'Knowledge. Once confirmed, every draft, quote, play and scout relies on the fact, so a wrong one ends up in ' +
+      'real messages to real clients. Use it when the person has read the facts and says they are right. Several ' +
+      'can go in one call, so the person answers once for the whole list. It is recorded as confirmed by the person ' +
+      'this connector belongs to, who has to be an owner or admin of the workspace. ' +
+      'Get the ids from km_list_pending_business_facts, and pass only the ones they actually said yes to. ' +
+      '🚨 A confirmed write. The first call, without confirm_token, returns 409 with `what_would_happen`: the list ' +
+      'of exact facts, written by KM Hub. Show it in those words, wait for a real yes, then call again with the ' +
+      'confirm_token and the SAME fact_ids. Once confirmed, a fact cannot be changed or withdrawn from the terminal, ' +
+      'and confirming a corrected wording later does NOT retire the old one (both would be in use), so confirm only ' +
+      'what the owner has read and said is right.',
+    { fact_ids: FACT_IDS, reason: REASON, confirm_token: CONFIRM_TOKEN },
+    review('/knowledge/facts/confirm'),
+  );
+
+  server.tool(
+    'km_reject_business_facts',
+    'Reject business facts the owner says are WRONG, the same as the reject button in KM Hub under Business ' +
+      'Knowledge, so nothing ever uses them. Only on the owner\'s word about these specific facts, never on your own ' +
+      'judgement that one looks doubtful: if you think one is wrong, say so and let them decide. A rejected fact ' +
+      'cannot be reopened, and the same wording cannot be proposed again; if the owner wants a corrected version, ' +
+      'propose the corrected wording with km_propose_business_fact. ' +
+      '🚨 A confirmed write, because it cannot be undone: the first call returns 409 with the exact facts; show them, ' +
+      'wait for a real yes, then call again with the confirm_token and the SAME fact_ids. Afterwards, say plainly ' +
+      'which facts were rejected.',
+    { fact_ids: FACT_IDS, reason: REASON, confirm_token: CONFIRM_TOKEN },
+    review('/knowledge/facts/reject'),
+  );
+
+  /** Same body on the ask and on the answer, so the confirm token's fingerprint matches. */
+  function review(path) {
+    return async ({ fact_ids, reason, confirm_token }) => {
+      const body = { fact_ids };
+      if (reason !== undefined) body.reason = reason;
+      if (confirm_token) body.confirm_token = String(confirm_token);
+      const r = await call('POST', path, body);
+      if (unsupported(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    };
+  }
+}