@kivimedia/kmhub 2.9.1 → 2.11.0

package/tools/hr.mjs

@@ -1,162 +1,162 @@
-/**
- * Tool family: hr - the people who actually do the work.
- *
- * Workstream B5. The HR pillar was the starkest zero in the parity map: eight
- * navigable pages, no terminal reach at all. For a talent business that is not an
- * edge case, it is the department that delivers every booking.
- *
- *   km_list_team            -> GET /hr/team
- *   km_get_team_member      -> GET /hr/team/:userId
- *   km_list_crew_assignments-> GET /hr/assignments
- *   km_list_time_entries    -> GET /hr/time
- *   km_list_payroll         -> GET /hr/payroll
- *
- * 🚨 EVERY TOOL HERE READS. Assigning somebody to a gig, approving time and marking
- * payroll paid all either move money or commit a human being to a date. The
- * write-scope policy (B8) is not settled, so none of that is reachable from here and
- * a model must say so rather than hunting for another route.
- *
- * 🚨 PERSONAL DATA IS NARROW ON PURPOSE. The users table holds home address,
- * coordinates, emergency contacts and a bio. None of it comes back. Name, email and
- * phone are the working contact set. Payroll payment references and notes are
- * withheld too: knowing a run is paid is operational, knowing the account it went to
- * is a liability sitting in a transcript.
- *
- * 🚨 ALL MONEY IS IN CENTS and named as cents. Nothing is silently divided.
- *
- * The family contract this file follows is documented in ./README.md.
- */
-import { z } from 'zod';
-
-export const FAMILY = 'hr';
-
-export const TOOLS = [
-  'km_list_team',
-  'km_get_team_member',
-  'km_list_crew_assignments',
-  'km_list_time_entries',
-  'km_list_payroll',
-];
-
-// Placed by hand in tools.mjs. Its own listing here is the fallback.
-export const PROFILES = ['money'];
-
-function routeMissing(r) {
-  return r.status === 404 || r.status === 405 || r.status === 501;
-}
-
-const NOT_SUPPORTED =
-  'Your KM Hub does not expose the HR surface to the terminal yet. That is not a fault: the workspace is fine and ' +
-  'every other tool works as normal. Your team, time and payroll are all there in the web app at ' +
-  'https://hub.kivimedia.co, and this connector will start reading them once your KM Hub is on a build that publishes them.';
-
-export function register(server, call, { out, text, qs }) {
-  server.tool(
-    'km_list_team',
-    'Who is on this workspace: their name, working contact details, access level, the roles they actually perform and ' +
-      'the skills recorded against them. ' +
-      'Call it whenever the user talks about their team, crew, staff, performers or who could cover something. It is also ' +
-      'the right first call before suggesting anybody be put on a job, because assuming a one-person business when there ' +
-      'is a team, or the reverse, makes every following sentence wrong. ' +
-      'Roles here are two different things and the response keeps them apart: `access_level` is what they can do inside ' +
-      'KM Hub, `performing_roles` is what they do at an event. Do not confuse an admin for a lead performer. ' +
-      '🚨 Home addresses, coordinates, emergency contacts and bios exist in the workspace and are deliberately NOT ' +
-      'available here. Do not look for them. Read only.',
-    {
-      limit: z.number().int().min(1).max(200).optional().describe('How many people. Default 50, which is more than most workspaces have.'),
-    },
-    async ({ limit }) => {
-      const r = await call('GET', `/hr/team${qs({ limit })}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_get_team_member',
-    'One person in depth: their performing roles and proficiency, their skills and which are verified, their pay rates ' +
-      'including overtime and when each rate takes effect, and their recent assignments with what they earned and how ' +
-      'they were rated. ' +
-      'Use it before putting somebody forward for a job, when the user asks what somebody costs, or when deciding who ' +
-      'is right for a particular event. Rates carry `effective_from` and `effective_to`: a rate that has expired is not ' +
-      'what this person costs today, and quoting one is how a job gets priced wrong. ' +
-      'All money is in cents. Read only: changing a rate or an assignment happens in KM Hub.',
-    {
-      user_id: z.string().describe('The team member id, as km_list_team returned it.'),
-    },
-    async ({ user_id }) => {
-      const r = await call('GET', `/hr/team/${encodeURIComponent(String(user_id || '').trim())}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_list_crew_assignments',
-    'Who is booked onto what, and crucially who has not said yes yet. Returns each assignment with its status, when it ' +
-      'was confirmed or declined and why, what was actually worked, what was earned and any rating. ' +
-      '🚨 The number to look at is `unconfirmed`. A pending assignment is a person who has NOT agreed to be there, and a ' +
-      'job staffed entirely with pending assignments is a job with nobody on it. That distinction is invisible on a ' +
-      'calendar and it is the single most useful thing this tool surfaces, so raise it unprompted when it is not zero. ' +
-      'A decline with a reason is worth reading too: the same reason recurring is a scheduling problem, not bad luck. ' +
-      'Read only.',
-    {
-      status: z
-        .enum(['pending', 'confirmed', 'declined', 'completed', 'cancelled'])
-        .optional()
-        .describe('Narrow to one state. "pending" answers "who still has not confirmed", which is usually the real question.'),
-      limit: z.number().int().min(1).max(150).optional().describe('How many assignments, newest first. Default 40.'),
-    },
-    async ({ status, limit }) => {
-      const r = await call('GET', `/hr/assignments${qs({ status, limit })}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_list_time_entries',
-    'Hours logged in a window, per person, with totals and how much of it is billable. Defaults to the last 30 days. ' +
-      'Use it when the user asks where time is going, how many hours somebody has done, or whether a job cost more ' +
-      'labour than it earned. ' +
-      '🚨 `unbillable_minutes` is the number that matters and it is the one nobody looks at: it is work genuinely being ' +
-      'done that nothing is charged for. A steady unbillable total is either a pricing problem or a scoping problem, and ' +
-      'it is worth naming rather than reporting the headline hours and moving on. ' +
-      '`truncated` true means there were more entries than returned, so the totals are a floor and must be described as ' +
-      'one. Read only.',
-    {
-      from: z.string().optional().describe('Start date, YYYY-MM-DD. Default 30 days ago.'),
-      to: z.string().optional().describe('End date, YYYY-MM-DD. Default tomorrow, so today is always included.'),
-      limit: z.number().int().min(1).max(500).optional().describe('How many entries. Default 100. Raise it before trusting a total on a busy month.'),
-    },
-    async ({ from, to, limit }) => {
-      const r = await call('GET', `/hr/time${qs({ from, to, limit })}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_list_payroll',
-    'Payroll periods and where each one stands: who, which period, gross, deductions, net, status and when it was paid, ' +
-      'plus a total of what is still outstanding. ' +
-      'Use it when the user asks what they owe their team, whether payroll has been run, or what a period cost. Money ' +
-      'owed to the people who did the work is a different and more urgent obligation than money owed by a client, and it ' +
-      'should be treated that way in anything you say. ' +
-      '🚨 Everything is in CENTS. 🚨 Payment references and payroll notes are deliberately NOT returned: knowing a run ' +
-      'is paid is operational, knowing the account it went to is a liability in a transcript. Do not look for them. ' +
-      'Nothing here can run, approve or pay payroll. Read only.',
-    {
-      status: z
-        .enum(['draft', 'pending', 'approved', 'paid', 'cancelled'])
-        .optional()
-        .describe('Narrow to one state. Leaving it out and reading `outstanding` is usually the faster answer.'),
-      limit: z.number().int().min(1).max(100).optional().describe('How many records, most recent period first. Default 25.'),
-    },
-    async ({ status, limit }) => {
-      const r = await call('GET', `/hr/payroll${qs({ status, limit })}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-}
+/**
+ * Tool family: hr - the people who actually do the work.
+ *
+ * Workstream B5. The HR pillar was the starkest zero in the parity map: eight
+ * navigable pages, no terminal reach at all. For a talent business that is not an
+ * edge case, it is the department that delivers every booking.
+ *
+ *   km_list_team            -> GET /hr/team
+ *   km_get_team_member      -> GET /hr/team/:userId
+ *   km_list_crew_assignments-> GET /hr/assignments
+ *   km_list_time_entries    -> GET /hr/time
+ *   km_list_payroll         -> GET /hr/payroll
+ *
+ * 🚨 EVERY TOOL HERE READS. Assigning somebody to a gig, approving time and marking
+ * payroll paid all either move money or commit a human being to a date. The
+ * write-scope policy (B8) is not settled, so none of that is reachable from here and
+ * a model must say so rather than hunting for another route.
+ *
+ * 🚨 PERSONAL DATA IS NARROW ON PURPOSE. The users table holds home address,
+ * coordinates, emergency contacts and a bio. None of it comes back. Name, email and
+ * phone are the working contact set. Payroll payment references and notes are
+ * withheld too: knowing a run is paid is operational, knowing the account it went to
+ * is a liability sitting in a transcript.
+ *
+ * 🚨 ALL MONEY IS IN CENTS and named as cents. Nothing is silently divided.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'hr';
+
+export const TOOLS = [
+  'km_list_team',
+  'km_get_team_member',
+  'km_list_crew_assignments',
+  'km_list_time_entries',
+  'km_list_payroll',
+];
+
+// Placed by hand in tools.mjs. Its own listing here is the fallback.
+export const PROFILES = ['money'];
+
+function routeMissing(r) {
+  return r.status === 404 || r.status === 405 || r.status === 501;
+}
+
+const NOT_SUPPORTED =
+  'Your KM Hub does not expose the HR surface to the terminal yet. That is not a fault: the workspace is fine and ' +
+  'every other tool works as normal. Your team, time and payroll are all there in the web app at ' +
+  'https://hub.kivimedia.co, and this connector will start reading them once your KM Hub is on a build that publishes them.';
+
+export function register(server, call, { out, text, qs }) {
+  server.tool(
+    'km_list_team',
+    'Who is on this workspace: their name, working contact details, access level, the roles they actually perform and ' +
+      'the skills recorded against them. ' +
+      'Call it whenever the user talks about their team, crew, staff, performers or who could cover something. It is also ' +
+      'the right first call before suggesting anybody be put on a job, because assuming a one-person business when there ' +
+      'is a team, or the reverse, makes every following sentence wrong. ' +
+      'Roles here are two different things and the response keeps them apart: `access_level` is what they can do inside ' +
+      'KM Hub, `performing_roles` is what they do at an event. Do not confuse an admin for a lead performer. ' +
+      '🚨 Home addresses, coordinates, emergency contacts and bios exist in the workspace and are deliberately NOT ' +
+      'available here. Do not look for them. Read only.',
+    {
+      limit: z.number().int().min(1).max(200).optional().describe('How many people. Default 50, which is more than most workspaces have.'),
+    },
+    async ({ limit }) => {
+      const r = await call('GET', `/hr/team${qs({ limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_get_team_member',
+    'One person in depth: their performing roles and proficiency, their skills and which are verified, their pay rates ' +
+      'including overtime and when each rate takes effect, and their recent assignments with what they earned and how ' +
+      'they were rated. ' +
+      'Use it before putting somebody forward for a job, when the user asks what somebody costs, or when deciding who ' +
+      'is right for a particular event. Rates carry `effective_from` and `effective_to`: a rate that has expired is not ' +
+      'what this person costs today, and quoting one is how a job gets priced wrong. ' +
+      'All money is in cents. Read only: changing a rate or an assignment happens in KM Hub.',
+    {
+      user_id: z.string().describe('The team member id, as km_list_team returned it.'),
+    },
+    async ({ user_id }) => {
+      const r = await call('GET', `/hr/team/${encodeURIComponent(String(user_id || '').trim())}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_crew_assignments',
+    'Who is booked onto what, and crucially who has not said yes yet. Returns each assignment with its status, when it ' +
+      'was confirmed or declined and why, what was actually worked, what was earned and any rating. ' +
+      '🚨 The number to look at is `unconfirmed`. A pending assignment is a person who has NOT agreed to be there, and a ' +
+      'job staffed entirely with pending assignments is a job with nobody on it. That distinction is invisible on a ' +
+      'calendar and it is the single most useful thing this tool surfaces, so raise it unprompted when it is not zero. ' +
+      'A decline with a reason is worth reading too: the same reason recurring is a scheduling problem, not bad luck. ' +
+      'Read only.',
+    {
+      status: z
+        .enum(['pending', 'confirmed', 'declined', 'completed', 'cancelled'])
+        .optional()
+        .describe('Narrow to one state. "pending" answers "who still has not confirmed", which is usually the real question.'),
+      limit: z.number().int().min(1).max(150).optional().describe('How many assignments, newest first. Default 40.'),
+    },
+    async ({ status, limit }) => {
+      const r = await call('GET', `/hr/assignments${qs({ status, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_time_entries',
+    'Hours logged in a window, per person, with totals and how much of it is billable. Defaults to the last 30 days. ' +
+      'Use it when the user asks where time is going, how many hours somebody has done, or whether a job cost more ' +
+      'labour than it earned. ' +
+      '🚨 `unbillable_minutes` is the number that matters and it is the one nobody looks at: it is work genuinely being ' +
+      'done that nothing is charged for. A steady unbillable total is either a pricing problem or a scoping problem, and ' +
+      'it is worth naming rather than reporting the headline hours and moving on. ' +
+      '`truncated` true means there were more entries than returned, so the totals are a floor and must be described as ' +
+      'one. Read only.',
+    {
+      from: z.string().optional().describe('Start date, YYYY-MM-DD. Default 30 days ago.'),
+      to: z.string().optional().describe('End date, YYYY-MM-DD. Default tomorrow, so today is always included.'),
+      limit: z.number().int().min(1).max(500).optional().describe('How many entries. Default 100. Raise it before trusting a total on a busy month.'),
+    },
+    async ({ from, to, limit }) => {
+      const r = await call('GET', `/hr/time${qs({ from, to, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_payroll',
+    'Payroll periods and where each one stands: who, which period, gross, deductions, net, status and when it was paid, ' +
+      'plus a total of what is still outstanding. ' +
+      'Use it when the user asks what they owe their team, whether payroll has been run, or what a period cost. Money ' +
+      'owed to the people who did the work is a different and more urgent obligation than money owed by a client, and it ' +
+      'should be treated that way in anything you say. ' +
+      '🚨 Everything is in CENTS. 🚨 Payment references and payroll notes are deliberately NOT returned: knowing a run ' +
+      'is paid is operational, knowing the account it went to is a liability in a transcript. Do not look for them. ' +
+      'Nothing here can run, approve or pay payroll. Read only.',
+    {
+      status: z
+        .enum(['draft', 'pending', 'approved', 'paid', 'cancelled'])
+        .optional()
+        .describe('Narrow to one state. Leaving it out and reading `outstanding` is usually the faster answer.'),
+      limit: z.number().int().min(1).max(100).optional().describe('How many records, most recent period first. Default 25.'),
+    },
+    async ({ status, limit }) => {
+      const r = await call('GET', `/hr/payroll${qs({ status, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+}

package/tools/knowledge.mjs

@@ -1,125 +1,129 @@
-/**
- * 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.
- * Confirming and rejecting live in fact-review.mjs.
- *
- * 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: km_list_pending_business_facts shows them, and km_confirm_business_facts confirms the ones the owner says are right. 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, the add-on menu attached to each package with what every choice adds to the bill, 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, and a supplement on an add-on choice is added to the package price rather than replacing it. The add-on lists come back as a sample with the true totals beside them, so read price_points and choice_count rather than counting the choices you can see. 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; when they say it is right, km_confirm_business_facts confirms it with the fact_id this returns. This tool itself 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)),
-  );
-}
+/**
+ * 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.
+ * Confirming and rejecting live in fact-review.mjs.
+ *
+ * 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. A confirmed fact marked internal: true (a cost, a margin, a goal) is for the owner only: use it to advise them, but never quote it to a customer and never put it in a draft. 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: km_list_pending_business_facts shows them, and km_confirm_business_facts confirms the ones the owner says are right. 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, the add-on menu attached to each package with what every choice adds to the bill, 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, and a supplement on an add-on choice is added to the package price rather than replacing it. The add-on lists come back as a sample with the true totals beside them, so read price_points and choice_count rather than counting the choices you can see. 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 nothing uses it before then. Once the owner confirms it, KM Hub\'s AI writers use it: business, service and craft facts in the drafts, replies and messages they write, a price fact only in replies and quotes and never in a first cold email, and a voice fact as style for every writer. Set audience to internal for anything that must never reach a customer, such as what something costs the business, a margin, or a sales goal: an internal fact never reaches any AI writer or any customer, and stays visible to the owner and to you. 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; when they say it is right, km_confirm_business_facts confirms it with the fact_id this returns. This tool itself 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.'),
+      audience: z
+        .enum(['customer', 'internal'])
+        .optional()
+        .describe('Who the fact is for. customer is the default. internal keeps it away from every AI writer and every customer: use it for costs, margins, goals and anything the owner said never to quote. Text that starts with INTERNAL is treated as internal anyway.'),
+    },
+    async (args) => out(await call('POST', '/knowledge/facts', args)),
+  );
+}