@kivimedia/kmhub 2.0.0

package/tools/core.mjs

@@ -0,0 +1,223 @@
+/**
+ * Tool family: core - orientation plus the CRM essentials.
+ *
+ * These are the original ten kmhub-mcp tools (server 1.2.0), moved here verbatim
+ * when the tool set was split into families. Tool names, descriptions, zod schemas,
+ * call paths and registration order are all unchanged, so a client that was already
+ * connected sees exactly the same ten tools it saw before the split.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'core';
+
+/**
+ * Order preserved from the original tools.mjs TOOL_NAMES export, so the health
+ * endpoint and the startup log keep printing the same list in the same order.
+ */
+export const TOOLS = [
+  'km_me',
+  'km_waiting',
+  'km_list_clients',
+  'km_create_lead',
+  'km_list_deals',
+  'km_list_events',
+  'km_list_bookings',
+  'km_create_inquiry',
+  'km_create_booking',
+  'km_create_outreach_draft',
+];
+
+// Orientation and the CRM floor belong in every profile: you always need to know
+// whose workspace this is and what is waiting, whatever else you loaded.
+export const PROFILES = ['*'];
+
+/**
+ * @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 }} helpers shared response helpers from ../tools.mjs
+ */
+export function register(server, call, { out }) {
+  server.tool(
+    'km_me',
+    'Which KM Hub workspace this connection actually points at: its id, the business name on it, and the plan it is on. ' +
+      'Call it once at the start of a session so you know whose business you are speaking about, and call it again the moment anything looks wrong - an empty client list, a diary with nothing in it, figures that do not match what the user is describing - because the commonest cause of all three is a key pointing at a different workspace than the one they mean. ' +
+      'It does not tell you which human is at the keyboard, it does not list the users on the account, and the plan it reports is the subscription, not how much of this month\'s allowance is left. ' +
+      'It is cheap, it reads, and it changes nothing.',
+    {},
+    async () => out(await call('GET', '/me')),
+  );
+
+  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. ' +
+      'Do NOT reach for this on the broad question. If the user says "what needs me today", "catch me up", "where are we", "what should I do first", "anything urgent", "what did I miss", or opens a session with no specific task, km_briefing is the tool: it returns these same counts AND the actual items behind them, in one list ranked in the order a person should deal with them, each with the reason it is there. Answering the broad question from a set of counts means guessing which of the numbers mattered, which is exactly the guess km_briefing exists to remove. ' +
+      'Reach for km_waiting only when you genuinely want the bare numbers on their own: to say whether anything has changed since earlier in the same conversation, or when km_briefing has told you it is not available on this workspace. ' +
+      'A count tells you something is waiting. It never tells you which one is worth doing first, and it carries no client, no amount, no date and no id, so nothing here can be opened or acted on without a second call. Read only.',
+    {},
+    async () => out(await call('GET', '/waiting')),
+  );
+
+  server.tool(
+    'km_list_clients',
+    'The most recently ADDED clients and leads, newest first. This is a recency window, NOT a search. ' +
+      'It walks back from the newest record and stops, so a contact added a year ago will not appear whatever you set limit to, and even at the maximum of 100 it shows the newest 100 and nothing behind them. ' +
+      'That means it CANNOT answer "do I have X", "find me the person at Y" or "what is that magician called", and treating a miss here as proof somebody is not in the workspace is the easiest way to tell a user something false about their own business. km_find_contact is the tool for finding a named person, a company or part of an email, and it searches all of them rather than the newest few. ' +
+      'Reach for km_list_clients only for the genuinely recency-shaped question: who has come in lately, what do the last few enquiries look like, has anything landed since we spoke. ' +
+      'It returns the record as it stands, not the history behind it: km_get_client opens one in full. Read only.',
+    { limit: z.number().int().min(1).max(100).optional() },
+    async ({ limit }) => out(await call('GET', `/clients?limit=${limit ?? 25}`)),
+  );
+
+  server.tool(
+    'km_create_lead',
+    'Put a person on file as a contact with nothing attached to them: no enquiry, no deal, no date, no money. ' +
+      'Reach for it when the user has met somebody and wants them kept - a card from a convention, a name off a phone call - and there is nothing being sold yet. ' +
+      'Search with km_find_contact FIRST. This tool will happily create a second Sarah Jones alongside the one already there, and a split contact is worse than no contact: half her history sits on a record nobody opens. ' +
+      'It is the wrong tool when there is actually something to sell. If the person is asking about a date, use km_create_inquiry, which creates the contact AND opens the pipeline deal behind it. If the gig is already agreed, use km_create_booking. ' +
+      'Every field is optional, but a contact with no email and no phone can never be written to, so ask for one rather than saving a bare name. ' +
+      'This WRITES: it needs the API key to carry the write scope, and it lands in the AI activity log where the owner can see and undo it.',
+    {
+      first_name: z.string().optional(),
+      last_name: z.string().optional(),
+      company: z.string().optional(),
+      email: z.string().optional(),
+      phone: z.string().optional(),
+      notes: z.string().optional(),
+    },
+    async (args) => out(await call('POST', '/clients', args)),
+  );
+
+  server.tool(
+    'km_list_bookings',
+    'The real jobs: the bookings on this business, each with its client, its date, its venue and the money on it. ' +
+      'Reach for it for the book of business rather than for the diary - what has been booked lately, what is still only pending a confirmation, every gig inside a date range so you can see the shape of a season, what this business has actually done before. ' +
+      'from and to filter on the EVENT date, not on when the booking was taken, so from today forward is the work ahead and to yesterday is the history. Use status to separate the confirmed work from what is still pending. ' +
+      'It caps at 100 rows and does not report the true total, so a busy year needs a narrower window rather than a bigger limit, and if you asked for 100 and got 100, say the picture is partial instead of presenting a slice as the whole book. ' +
+      'It tells you what is BOOKED. It says nothing about whether a new date could be sold, because a free-looking day can still be blocked, out of area or already pencilled in by a live lead: km_check_availability is the only honest answer to that question. km_get_booking opens one booking in full, where that tool is loaded. Read only.',
+    {
+      limit: z.number().int().min(1).max(100).optional(),
+      status: z.string().optional().describe('e.g. confirmed, pending'),
+      from: z.string().optional().describe('Earliest event date, YYYY-MM-DD.'),
+      to: z.string().optional().describe('Latest event date, YYYY-MM-DD.'),
+    },
+    async ({ limit, status, from, to }) => {
+      const q = new URLSearchParams();
+      q.set('limit', String(limit ?? 25));
+      if (status) q.set('status', status);
+      if (from) q.set('from', from);
+      if (to) q.set('to', to);
+      return out(await call('GET', `/bookings?${q.toString()}`));
+    },
+  );
+
+  server.tool(
+    'km_list_deals',
+    'The pipeline: the live opportunities in this workspace and how far each one has got, newest first. ' +
+      'Reach for it for the shape of the funnel - what is open, what is stuck in quoting, what has been won, what was lost - and to get the deal_id that km_get_deal, km_create_outreach_draft and a play run all need before they can attach anything to the right opportunity. ' +
+      'stage narrows to one column of the board. status is the coarse open, won, lost, abandoned split. status lost, then km_get_deal on the big ones, is how you read WHY work was lost, which is almost always worth more than the count: a large deal lost on timing is a live target, a large deal lost on price is evidence about the rate. ' +
+      'It caps at 100 rows and does not report the true total, so if you asked for 100 and got 100, say the pipeline you are describing is partial. ' +
+      'It cannot search by a client\'s name: find the person with km_find_contact first, then work from their record. Read only.',
+    {
+      limit: z.number().int().min(1).max(100).optional(),
+      stage: z
+        .enum([
+          'inbound',
+          'qualifying',
+          'quoting',
+          'proposal_sent',
+          'booked',
+          'in_progress',
+          'completed',
+          'lost',
+          'abandoned',
+        ])
+        .optional(),
+      status: z.enum(['open', 'won', 'lost', 'abandoned']).optional(),
+    },
+    async ({ limit, stage, status }) => {
+      const q = new URLSearchParams();
+      q.set('limit', String(limit ?? 25));
+      if (stage) q.set('stage', stage);
+      if (status) q.set('status', status);
+      return out(await call('GET', `/deals?${q.toString()}`));
+    },
+  );
+
+  server.tool(
+    'km_list_events',
+    'The raw contents of the KM Hub calendar over a date window, in start order: the gigs and everything else that has been put in the diary alongside them. ' +
+      'Always set from and to. With no window it returns whatever is most recent, which is almost never the question anybody asked. ' +
+      'Reach for it when the user wants the literal contents of a range: what is in September, is there anything at all on that weekend, how full does next month look. ' +
+      'For the ordinary "what have I got on" question, km_my_schedule is the better answer wherever it is loaded, because it groups the days and names the client, venue, times and fee on each gig rather than handing back a flat list. For whether ONE date can be sold, km_check_availability is the only honest source: this tool shows what already exists, and an empty-looking day is not the same as an available one. ' +
+      'Read only: it never adds, moves or cancels anything in the diary.',
+    {
+      from: z.string().optional().describe('Earliest start date, YYYY-MM-DD.'),
+      to: z.string().optional().describe('Latest start date, YYYY-MM-DD.'),
+      limit: z.number().int().min(1).max(200).optional(),
+    },
+    async ({ from, to, limit }) => {
+      const q = new URLSearchParams();
+      q.set('limit', String(limit ?? 50));
+      if (from) q.set('from', from);
+      if (to) q.set('to', to);
+      return out(await call('GET', `/events?${q.toString()}`));
+    },
+  );
+
+  server.tool(
+    'km_create_outreach_draft',
+    'Queue an outreach message as a DRAFT in KM Hub. This tool NEVER sends anything - the draft lands in the Approval Queue and a human approves it before any send happens. Audited in the AI activity log.',
+    {
+      body: z.string().describe('The message text (required).'),
+      subject: z.string().optional().describe('Subject line (email channel).'),
+      channel: z.enum(['email', 'linkedin', 'ig', 'sms_whatsapp']).optional().describe('Default email.'),
+      deal_id: z.string().optional().describe('UUID of the deal this draft belongs to (see km_list_deals).'),
+      contact_id: z.string().optional().describe('UUID of the client/contact (see km_find_contact).'),
+    },
+    async (args) => out(await call('POST', '/outreach-drafts', args)),
+  );
+
+  server.tool(
+    'km_create_inquiry',
+    'Log a new inquiry (lead + enquiry) in KM Hub - creates the client if needed and opens a pipeline deal. Audited and undoable from the AI activity log.',
+    {
+      client_name: z.string().describe('Full name of the person enquiring.'),
+      client_email: z.string().optional(),
+      client_phone: z.string().optional(),
+      event_type: z.string().optional().describe('e.g. wedding, corporate, birthday.'),
+      event_date: z.string().optional().describe('YYYY-MM-DD.'),
+      event_start_time: z.string().optional().describe('HH:MM 24h.'),
+      event_end_time: z.string().optional().describe('HH:MM 24h.'),
+      venue_name: z.string().optional(),
+      guest_count: z.number().optional(),
+      budget_cents: z.number().optional().describe('Budget in CENTS.'),
+      notes: z.string().optional(),
+    },
+    async (args) => out(await call('POST', '/inquiries', args)),
+  );
+
+  server.tool(
+    'km_create_booking',
+    'Create a REAL confirmed booking on the KM Hub calendar - creates the client if needed and opens a pipeline deal at booked/won. Requires an event_date. Only use when the gig is definitely booked; otherwise use km_create_inquiry.',
+    {
+      client_name: z.string().describe('Full name of the client.'),
+      client_email: z.string().optional(),
+      client_phone: z.string().optional(),
+      title: z.string().optional().describe('Booking title shown on the calendar.'),
+      event_type: z.string().optional(),
+      event_date: z.string().describe('YYYY-MM-DD (required for a real booking).'),
+      event_start_time: z.string().optional().describe('HH:MM 24h.'),
+      event_end_time: z.string().optional().describe('HH:MM 24h.'),
+      venue_name: z.string().optional(),
+      guest_count: z.number().optional(),
+      total_cents: z.number().optional().describe('Total in CENTS.'),
+      status: z
+        .enum(['pending', 'confirmed'])
+        .optional()
+        .describe('Default pending (owner reviews); confirmed puts it straight on the calendar.'),
+    },
+    async (args) => out(await call('POST', '/bookings', args)),
+  );
+}

package/tools/crm.mjs

@@ -0,0 +1,200 @@
+/**
+ * Tool family: crm - opening a record, changing it, and keeping the follow-ups.
+ *
+ * core gives you the lists: clients, deals, bookings. This family gives you the
+ * one record behind a list row, the small edits that keep a CRM honest, the deal
+ * board move, and tasks (which core cannot see at all).
+ *
+ * One tool per route in supabase/functions/kmhub-api/routes/crm.ts. Nothing here
+ * deletes anything, and nothing here sends anything to a client of the workspace.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'crm';
+
+export const TOOLS = [
+  'km_find_contact',
+  'km_get_client',
+  'km_update_client',
+  'km_get_deal',
+  'km_move_deal_stage',
+  'km_set_deal_status',
+  'km_list_tasks',
+  'km_create_task',
+  'km_complete_task',
+  'km_log_touch',
+];
+
+/**
+ * Every profile. core already puts km_list_clients and km_list_deals in front of
+ * every caller, so a profile that can list records but cannot open one of them is
+ * a broken profile, whatever else it was narrowed to.
+ */
+export const PROFILES = ['*'];
+
+/**
+ * @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, qs: Function }} helpers shared response helpers from ../tools.mjs
+ */
+export function register(server, call, { out, qs }) {
+  server.tool(
+    'km_find_contact',
+    'THE way to turn a name a person says out loud into a record you can act on. Search contacts by first name, last name, company, or part of an email, or filter by a tag. Reach for this the moment someone says "the ABRA Auto Body draft" or "that magician from the fair" or "the motorsport people" - you cannot act on a name until you have the record. Do NOT reach for km_list_clients to find a named person: that one returns only the most recently added contacts, so anyone added a while ago will not be in it and you will wrongly conclude they do not exist. If this comes back empty, the contact genuinely is not in the workspace under that spelling: say so and offer to create them, rather than guessing. Read only.',
+    {
+      q: z.string().optional().describe('A name, company, or part of an email. Partial and case-insensitive, so "abra" finds "ABRA Auto Body & Glass".'),
+      tag: z.string().optional().describe('Filter by an exact tag, which is how a group like a market segment was labelled. Combine with q to search inside a group.'),
+      limit: z.number().int().min(1).max(100).optional().describe('Default 25.'),
+    },
+    async ({ q, tag, limit }) => out(await call('GET', `/clients/search${qs({ q, tag, limit })}`)),
+  );
+
+  server.tool(
+    'km_get_client',
+    'Open ONE client or lead and see everything you would want in front of you before you contact them: their details, the deals they are in, their bookings, anything still open on your side, and the last few conversations anyone recorded. Reach for this whenever you are about to write to someone, quote someone, or answer "what is going on with X", so you are working from their real history rather than from memory. Get the id from km_find_contact. If the record was merged into another contact the answer says so, and the surviving contact is the one to use. Read only: it changes nothing.',
+    {
+      client_id: z.string().describe('The client UUID, from km_find_contact.'),
+    },
+    async ({ client_id }) => out(await call('GET', `/clients/${encodeURIComponent(String(client_id ?? '').trim())}`)),
+  );
+
+  server.tool(
+    'km_update_client',
+    'Correct or fill in the details on an existing client: a new phone number, a spelling, a company name, an address, a note to self. Use it when the person tells you something has changed, or when you spot something wrong while looking at their record. Send only the fields you actually want to change; everything you leave out stays exactly as it is, and passing null to a field clears it. It will NOT touch anything the workspace works out for itself, like their lifetime value, their booking count or their billing links, and it cannot move a client to another workspace. There is no way to delete a client from here. The change is recorded in the AI activity log so the owner can see what you did, but unlike a newly created record it cannot be auto-undone, so read the current details back with km_get_client first if you are not certain.',
+    {
+      client_id: z.string().describe('The client UUID, from km_find_contact or km_get_client.'),
+      first_name: z.string().optional().describe('Cannot be emptied - every contact needs at least a first name.'),
+      last_name: z.string().nullable().optional(),
+      company_name: z.string().nullable().optional(),
+      email: z.string().nullable().optional(),
+      phone: z.string().nullable().optional(),
+      job_title: z.string().nullable().optional(),
+      website: z.string().nullable().optional(),
+      linkedin_url: z.string().nullable().optional(),
+      address_line_1: z.string().nullable().optional(),
+      city: z.string().nullable().optional(),
+      state: z.string().nullable().optional(),
+      postal_code: z.string().nullable().optional(),
+      country_code: z.string().nullable().optional(),
+      type: z.string().nullable().optional().describe('What kind of contact this is, e.g. individual or company.'),
+      notes: z.string().nullable().optional().describe('Free notes on the contact. This REPLACES the existing notes, so read them first if you mean to add to them.'),
+      // tags deliberately absent: a tag can arm an automation that emails or texts
+      // the client, so it stays a human action in KM Hub. See routes/crm.ts.
+    },
+    async ({ client_id, ...fields }) =>
+      out(await call('PATCH', `/clients/${encodeURIComponent(String(client_id ?? '').trim())}`, fields)),
+  );
+
+  server.tool(
+    'km_get_deal',
+    'Open ONE deal from the sales board and see where it stands: the money, the event, who the contact is, every stage it has moved through and when, and the exact list of stages it is allowed to move to next. Reach for this before moving a deal, before quoting on it, or when someone asks what is happening with a particular job. The available_stages in the answer are that board\'s real columns, which may be customised for this workspace, so use them rather than guessing stage names. Read only: it changes nothing.',
+    {
+      deal_id: z.string().describe('The deal UUID, from km_list_deals.'),
+    },
+    async ({ deal_id }) => out(await call('GET', `/deals/${encodeURIComponent(String(deal_id ?? '').trim())}`)),
+  );
+
+  server.tool(
+    'km_move_deal_stage',
+    'Move a deal to a different column on the sales board, for example from Qualifying to Quoting when a price has gone out. The deal\'s open / won / lost standing follows the stage automatically, so the board and the reporting can never disagree. The move is reversible: you can move it back the same way, and every move is kept on the deal\'s own history. IMPORTANT: moving a deal into a stage that marks it WON or LOST is not routine bookkeeping, it changes what this workspace believes about its own money and its own pipeline. Confirm with the person first, in plain words, before you make that particular move, and never infer it from an ambiguous message. Call km_get_deal first to see the stages this board actually has.',
+    {
+      deal_id: z.string().describe('The deal UUID, from km_list_deals or km_get_deal.'),
+      stage: z
+        .string()
+        .describe('The stage slug to move into. Use one of the available_stages from km_get_deal. On a standard board those are inbound, qualifying, quoting, proposal_sent, booked, in_progress, completed, lost, abandoned.'),
+      reason: z
+        .string()
+        .optional()
+        .describe('A short plain-language reason, kept on the deal history so the owner can see why it moved.'),
+    },
+    async ({ deal_id, stage, reason }) =>
+      out(await call('PATCH', `/deals/${encodeURIComponent(String(deal_id ?? '').trim())}/stage`, { stage, reason })),
+  );
+
+  server.tool(
+    'km_set_deal_status',
+    'Set whether a deal counts as open, won, lost or abandoned WITHOUT moving it to another column. Use this in the narrow case where the deal is already sitting in the right place on the board but the answer has finally come back, for example a proposal that was declined. In every other case prefer km_move_deal_stage, which keeps the board and the standing in step for you. Marking a deal won or lost changes what this workspace believes about its own money, so confirm with the person first and never infer it. Nothing here is auto-undoable, though the change is kept on the deal history and in the AI activity log.',
+    {
+      deal_id: z.string().describe('The deal UUID, from km_list_deals or km_get_deal.'),
+      status: z
+        .enum(['open', 'won', 'lost', 'abandoned'])
+        .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.'),
+    },
+    async ({ deal_id, status, lost_reason, reason }) =>
+      out(await call('PATCH', `/deals/${encodeURIComponent(String(deal_id ?? '').trim())}/status`, { status, lost_reason, reason })),
+  );
+
+  server.tool(
+    'km_list_tasks',
+    'List the jobs on the workspace to-do list. Use it to answer "what do I owe anyone", "what is late", or "what is outstanding on the Henderson wedding". Set overdue to true for the things that were due and are still not done, which is usually what someone actually means when they ask what is late. You can also narrow to one client or one booking. By default it shows the soonest due dates first, and tasks with no date at the end. Read only: it changes nothing.',
+    {
+      limit: z.number().int().min(1).max(100).optional().describe('How many to return. Default 25.'),
+      overdue: z.boolean().optional().describe('True = only work that is past its due date and still not done.'),
+      status: z
+        .enum(['pending', 'in_progress', 'completed', 'cancelled'])
+        .optional()
+        .describe('Narrow to one state. With overdue this must be pending or in_progress, because finished work cannot be late.'),
+      client_id: z.string().optional().describe('Only tasks tied to this client (UUID).'),
+      booking_id: z.string().optional().describe('Only tasks tied to this booking (UUID).'),
+    },
+    async ({ limit, overdue, status, client_id, booking_id }) =>
+      out(
+        await call(
+          'GET',
+          `/tasks${qs({
+            limit: limit ?? 25,
+            overdue: overdue ? 'true' : '',
+            status,
+            client_id,
+            booking_id,
+          })}`,
+        ),
+      ),
+  );
+
+  server.tool(
+    'km_create_task',
+    '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.'),
+      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.'),
+    },
+    async (args) => out(await call('POST', '/tasks', args)),
+  );
+
+  server.tool(
+    'km_complete_task',
+    'Tick a task off the list once the person tells you it is done. Get the id from km_list_tasks. If it was already ticked off, this says so and changes nothing, so it is safe to call twice. It does not delete the task: completed work stays on the record where it can be seen. There is no way to delete a task from here, and no way to un-complete one, so only call it when you have been told the work is actually finished.',
+    {
+      task_id: z.string().describe('The task UUID, from km_list_tasks.'),
+    },
+    async ({ task_id }) =>
+      out(await call('POST', `/tasks/${encodeURIComponent(String(task_id ?? '').trim())}/complete`)),
+  );
+
+  server.tool(
+    'km_log_touch',
+    'Write down something that ALREADY happened with a client, so it lands on their timeline in date order next to everything else: a phone call, running into them at a venue, a DM, a card in the post. This is the place for anything that happened off the rails, which the workspace cannot see by itself. Use it whenever the person tells you about a conversation, and quote them rather than summarising, because the detail is the whole point. This tool NEVER contacts anybody: it is a private note in the workspace, not a message, and there is no path from here to one. If you only know the deal, pass deal_id and the note goes on that deal\'s contact; the answer tells you which contact it landed on. Use occurred_at when the conversation happened on a different day from the one you are typing on.',
+    {
+      note: z.string().describe('What happened, in the person\'s own words. Free text, and the more specific the better.'),
+      client_id: z.string().optional().describe('The client UUID this happened with. Give this or deal_id.'),
+      deal_id: z.string().optional().describe('A deal UUID, when you only know the job. The note goes on that deal\'s contact.'),
+      channel: z
+        .enum(['call', 'email', 'text', 'in_person', 'social', 'mail', 'other'])
+        .optional()
+        .describe('How it happened. Default other.'),
+      occurred_at: z
+        .string()
+        .optional()
+        .describe('When it actually happened, YYYY-MM-DD or a full ISO timestamp. Default now. Use it when logging a conversation from a previous day.'),
+    },
+    async (args) => out(await call('POST', '/touches', args)),
+  );
+}

package/tools/knowledge.mjs

@@ -0,0 +1,124 @@
+/**
+ * Tool family: knowledge - what the business knows about itself.
+ *
+ * Every other family answers "what is on the books". This one answers "who are
+ * we, what do we sell, at what price, and how do we sound", which is what turns
+ * a draft from something a generic assistant would write into something the
+ * owner would have written. The intended shape of a session is: pull the person
+ * from the CRM tools, pull offers + voice from here, then draft.
+ *
+ * One tool writes, and what it writes is a PROPOSAL: it lands in KM Hub as a
+ * pending fact that the owner confirms before anything uses it. Nothing in this
+ * family sends a message, confirms a fact, sets a price, or removes anything.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'knowledge';
+
+export const TOOLS = [
+  'km_search_knowledge',
+  'km_get_business_facts',
+  'km_get_brand_voice',
+  'km_get_offers_and_pricing',
+  'km_search_conversations',
+  'km_propose_business_fact',
+];
+
+// Any profile whose job is producing words or numbers for a real person needs
+// the grounding: outreach and content write the words, money quotes the prices.
+export const PROFILES = ['outreach', 'content', 'money'];
+
+/** Comma-joined query value, or undefined when the caller passed nothing. */
+function csv(list) {
+  if (!Array.isArray(list) || list.length === 0) return undefined;
+  return list.join(',');
+}
+
+/**
+ * @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, qs: Function }} helpers shared response helpers from ../tools.mjs
+ */
+export function register(server, call, { out, qs }) {
+  server.tool(
+    'km_search_knowledge',
+    'Search everything written down in this KM Hub workspace by meaning rather than by exact words: notes on a client, what someone asked for last time, access and setup details, special requirements, the stray line somebody typed into a booking. Reach for it when you need something that is not a tidy field on a record, for example before writing to a lead, or when you are asked what was agreed with somebody. It searches only this workspace and only what has been indexed, so an empty result means nobody wrote it down here, NOT that it is untrue: ask the person instead of filling the gap. It does not search the public internet, it does not read a live inbox, and it changes nothing.',
+    {
+      q: z.string().describe('What you are looking for, in plain words. A question works better than a keyword.'),
+      entity_types: z
+        .array(z.enum(['clients', 'bookings', 'invoices', 'contacts', 'projects']))
+        .optional()
+        .describe('Narrow the search when you already know where the answer lives. Leave it out to search everything.'),
+      limit: z.number().int().min(1).max(20).optional().describe('How many passages to return. Default 5.'),
+    },
+    async ({ q, entity_types, limit }) =>
+      out(await call('GET', `/knowledge/search${qs({ q, entity_types: csv(entity_types), limit })}`)),
+  );
+
+  server.tool(
+    'km_get_business_facts',
+    'What this business has told KM Hub about itself: the facts its owner has CONFIRMED, the standing facts they asked to be remembered permanently, and the knowledge distilled from documents they uploaded such as past proposals, pricing sheets and contracts. Read it before you write anything in the business name, so you work from what is actually true here instead of from a generic idea of the trade. Everything it returns is owner-approved and safe to rely on. Facts that are still waiting for the owner are counted but deliberately not shown, because nobody has confirmed them yet - if that count is above zero it is worth telling the person they have some waiting. Read only.',
+    {
+      kind: z
+        .enum(['business', 'service', 'price', 'voice', 'vertical_craft'])
+        .optional()
+        .describe('Narrow to one sort of fact. Leave it out for all of them.'),
+      topic: z
+        .string()
+        .optional()
+        .describe('What the task is about. Used only to pick the most relevant uploaded documents, for example "wedding proposal" or "cancellation policy".'),
+      limit: z.number().int().min(1).max(100).optional().describe('How many facts to return. Default 40.'),
+    },
+    async ({ kind, topic, limit }) => out(await call('GET', `/knowledge/facts${qs({ kind, topic, limit })}`)),
+  );
+
+  server.tool(
+    'km_get_brand_voice',
+    'How this business sounds: the owner own words about their values and tone, the writing sample they saved, the phrases they actually use, how they sign off, their positioning and brand messages, and the house rules any outgoing message has to obey. Read it before drafting an email, a message, a post or a proposal so the draft sounds like them rather than like an assistant. Treat all of it as STYLE: match the rhythm, the vocabulary and the level of formality, never paste a saved sample sentence into a real message, and never treat a phrase from it as a fact about a client. If the workspace has no voice recorded yet the tool says so plainly, and the right move then is to write simply and ask the owner rather than invent a house style. Read only: drafting still goes through km_create_outreach_draft, which queues the message for a human and never sends.',
+    {},
+    async () => out(await call('GET', '/knowledge/voice')),
+  );
+
+  server.tool(
+    'km_get_offers_and_pricing',
+    'Everything this business sells and every price it has actually published: the service price list, the packages and their add-ons, the packages used in proposals, the bookable offerings with their deposit and contract rules, and the price ladder the owner set. This is the ONLY place a price may come from. Quote a figure from here exactly, in the currency it returns, and respect the units it labels for you, because some fields are in cents and some are in whole currency units. Never average two prices, never round one up, never blend them into a number of your own, and if there is no published price for what is being asked, say the owner will confirm it rather than guessing. Call this before any message, quote or proposal that mentions money. It reads only: it cannot set a price and it cannot commit the business to one.',
+    {
+      limit: z.number().int().min(1).max(100).optional().describe('How many rows per list. Default 50.'),
+    },
+    async ({ limit }) => out(await call('GET', `/knowledge/offers${qs({ limit })}`)),
+  );
+
+  server.tool(
+    'km_search_conversations',
+    'Search the email history recorded in this workspace: what a person actually wrote, what was already promised them, what was last sent. Reach for it before replying to somebody or drafting a follow up, so you pick up the thread instead of starting the conversation again and asking for something they already told you. Search by words, or read one person history with their contact id from km_find_contact, or both together. It returns short snippets rather than whole emails, so open the thread in KM Hub when you need the full text. It only reads mail already recorded in KM Hub, and it never sends, replies to, or changes anything.',
+    {
+      q: z.string().optional().describe('Words to look for in the subject or the body. Leave it out when you are reading one person history.'),
+      contact_id: z.string().optional().describe('UUID of the client or contact whose mail you want (see km_find_contact).'),
+      direction: z
+        .enum(['inbound', 'outbound'])
+        .optional()
+        .describe('inbound is what they sent us, outbound is what we sent them. Leave it out for both.'),
+      limit: z.number().int().min(1).max(50).optional().describe('How many messages to return. Default 20.'),
+    },
+    async ({ q, contact_id, direction, limit }) =>
+      out(await call('GET', `/knowledge/conversations${qs({ q, contact_id, direction, limit })}`)),
+  );
+
+  server.tool(
+    'km_propose_business_fact',
+    'Write down something durable this business has learned about itself, for example that they no longer travel more than two hours, or that their busy season starts in March, or that they always need a stage of a certain size. It is saved as a PROPOSAL and not as truth: it waits in KM Hub under Business Knowledge until the owner confirms it, and no draft, quote or answer will use it before then. Use it only for something that will still be true next month. A detail about ONE client or ONE booking is not a business fact and belongs on that record instead. Always say in source_note where the fact came from, in one line, because that is what the owner reads when deciding whether to accept it. After calling this, tell the person plainly that it is waiting for their approval. This tool cannot confirm a fact, cannot edit or replace an existing one, and cannot remove one.',
+    {
+      text: z.string().describe('The fact itself, in one plain sentence, written the way the owner would say it.'),
+      source_note: z
+        .string()
+        .describe('Where this came from, in one line, for example "the owner said so in this conversation on 4 March" or "from the venue email they forwarded".'),
+      kind: z
+        .enum(['business', 'service', 'price', 'voice', 'vertical_craft'])
+        .optional()
+        .describe('What sort of fact it is. business is the default and covers how they operate. Use price only for a real published price, service for something they offer, voice for how they sound.'),
+    },
+    async (args) => out(await call('POST', '/knowledge/facts', args)),
+  );
+}