@kivimedia/kmhub 2.0.0 → 2.9.1

package/tools/hr.mjs

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

package/tools/knowledge.mjs

@@ -10,6 +10,7 @@
  * 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.
  */
@@ -59,7 +60,7 @@ export function register(server, call, { out, qs }) {
 
   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.',
+    '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'])
@@ -83,7 +84,7 @@ export function register(server, call, { out, qs }) {
 
   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.',
+    '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.'),
     },
@@ -108,7 +109,7 @@ export function register(server, call, { out, qs }) {
 
   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.',
+    '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

package/tools/marketing.mjs

@@ -0,0 +1,396 @@
+/**
+ * Tool family: marketing - being found, and the list you already own.
+ *
+ * Workstream B1. Before this family a client's Claude could see their pipeline,
+ * their diary and their money, and had no idea KM Hub also ran their search
+ * visibility and their newsletter. Asked "does it do my newsletter" it answered
+ * from its tool list and understated the product by a whole department.
+ *
+ *   km_list_seo_sites    -> GET /marketing/seo/sites
+ *   km_list_seo_posts    -> GET /marketing/seo/posts
+ *   km_get_seo_post      -> GET /marketing/seo/posts/:id
+ *   km_list_newsletters  -> GET /marketing/newsletters
+ *   km_get_newsletter    -> GET /marketing/newsletters/:id
+ *   km_newsletter_audience -> GET /marketing/audience
+ *   km_list_broadcasts   -> GET /marketing/broadcasts
+ *   km_lists             -> GET /marketing/lists
+ *   km_import_list       -> POST /marketing/lists/import   (free)
+ *
+ * 🚨 NOTHING HERE SENDS. No tool in this family sends a newsletter, publishes a
+ * post, or changes a schedule: a send is irreversible against a list somebody
+ * spent years building. When a user asks to send, say plainly that it happens
+ * in KM Hub and do not look for another route to it.
+ *
+ * BUILDING a list is allowed (16-Sep-2026). "If I give you a CSV can you create
+ * lists for me inside kmhub" was being answered "no" from the tool list, and the
+ * answer is yes: km_import_list takes the file's rows, files each person as a
+ * client tagged with the list name, and saves the segment. It is 'free' class -
+ * internal, reversible, nobody outside sees it.
+ *
+ * These routes ship on the API side separately from this connector, so each tool
+ * degrades in plain words when the route is not there yet: an older KM Hub is not
+ * a broken KM Hub.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+import { readFileSync } from 'node:fs';
+
+export const FAMILY = 'marketing';
+
+export const TOOLS = [
+  'km_list_seo_sites',
+  'km_list_seo_posts',
+  'km_get_seo_post',
+  'km_list_newsletters',
+  'km_get_newsletter',
+  'km_newsletter_audience',
+  'km_list_broadcasts',
+  'km_lists',
+  'km_import_list',
+];
+
+/** Rows per import call, matching the API's IMPORT_MAX_ROWS. Bigger files are chunked. */
+const IMPORT_CHUNK = 500;
+
+/**
+ * RFC 4180 CSV -> array of objects keyed by the header row. Quoted fields, doubled
+ * quotes, embedded newlines and a BOM are handled; the delimiter (',' ';' or tab)
+ * is sniffed from the header line. No dependency: the connector ships with none
+ * it does not need.
+ */
+export function parseCsv(input) {
+  const src = String(input || '').replace(/^/, '');
+  const firstLine = src.split(/\r?\n/, 1)[0] || '';
+  const delim = [',', ';', '\t']
+    .map((d) => [d, firstLine.split(d).length - 1])
+    .sort((a, b) => b[1] - a[1])[0][0];
+  const rows = [];
+  let row = [];
+  let field = '';
+  let quoted = false;
+  for (let i = 0; i < src.length; i += 1) {
+    const c = src[i];
+    if (quoted) {
+      if (c === '"') {
+        if (src[i + 1] === '"') { field += '"'; i += 1; } else quoted = false;
+      } else field += c;
+      continue;
+    }
+    if (c === '"') { quoted = true; continue; }
+    if (c === delim) { row.push(field); field = ''; continue; }
+    if (c === '\r') continue;
+    if (c === '\n') { row.push(field); rows.push(row); row = []; field = ''; continue; }
+    field += c;
+  }
+  if (field !== '' || row.length) { row.push(field); rows.push(row); }
+  const nonEmpty = rows.filter((r) => r.some((v) => String(v).trim() !== ''));
+  if (nonEmpty.length < 2) return { headers: nonEmpty[0] || [], rows: [] };
+  const headers = nonEmpty[0].map((h) => String(h).trim());
+  return {
+    headers,
+    rows: nonEmpty.slice(1).map((r) => Object.fromEntries(headers.map((h, i) => [h, String(r[i] ?? '').trim()]))),
+  };
+}
+
+/** Map whatever the file calls its columns onto the fields the API takes. */
+const COLUMN_ALIASES = {
+  email: ['email', 'e-mail', 'email address', 'emailaddress', 'mail', 'primary email', 'email_address'],
+  name: ['name', 'full name', 'fullname', 'contact', 'contact name', 'client', 'client name', 'customer', 'customer name'],
+  first_name: ['first name', 'first', 'firstname', 'first_name', 'given name'],
+  last_name: ['last name', 'last', 'lastname', 'last_name', 'surname', 'family name'],
+  phone: ['phone', 'phone number', 'mobile', 'cell', 'telephone', 'tel', 'phone_number'],
+  company: ['company', 'company name', 'organization', 'organisation', 'business', 'business name', 'company_name'],
+};
+
+export function mapColumns(headers) {
+  const lower = headers.map((h) => String(h).trim().toLowerCase());
+  const map = {};
+  for (const [field, aliases] of Object.entries(COLUMN_ALIASES)) {
+    const idx = lower.findIndex((h) => aliases.includes(h));
+    if (idx >= 0) map[field] = headers[idx];
+  }
+  // Exports rarely agree on a header. Anything with "email" in it still counts.
+  if (!map.email) {
+    const idx = lower.findIndex((h) => h.includes('email') || h.includes('e-mail'));
+    if (idx >= 0) map.email = headers[idx];
+  }
+  return map;
+}
+
+function toApiRows(parsed) {
+  const map = mapColumns(parsed.headers);
+  if (!map.email) {
+    return { error: `No email column found. Columns seen: ${parsed.headers.join(', ') || '(none)'}. Tell me which one holds the address.`, rows: [] };
+  }
+  return {
+    rows: parsed.rows.map((r) => ({
+      email: r[map.email],
+      ...(map.name ? { name: r[map.name] } : {}),
+      ...(map.first_name ? { first_name: r[map.first_name] } : {}),
+      ...(map.last_name ? { last_name: r[map.last_name] } : {}),
+      ...(map.phone ? { phone: r[map.phone] } : {}),
+      ...(map.company ? { company: r[map.company] } : {}),
+    })),
+    mapped: map,
+  };
+}
+
+// 'content' is the profile a client installs when their work is publishing and
+// list-building rather than pipeline chasing.
+export const PROFILES = ['content', 'outreach'];
+
+function routeMissing(r) {
+  return r.status === 404 || r.status === 405 || r.status === 501;
+}
+
+const NOT_SUPPORTED =
+  'Your KM Hub does not expose the marketing surface to the terminal yet. That is not a fault: the workspace ' +
+  'is fine and every other tool works as normal. SEO and the newsletter are both 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_seo_sites',
+    'The websites KM Hub is publishing search content to, and whether it is doing it automatically. ' +
+      'Call this when the user asks about SEO, being found on Google, showing up in AI search, their blog, or why ' +
+      'nothing has been published lately. It returns each connected site, its category, whether weekly autopilot is on, ' +
+      'whether autopilot is allowed to publish by itself, when it last published, and the last error if there was one. ' +
+      'An empty list is a real and important answer: no site connected means nothing is being published at all, and the ' +
+      'user almost certainly does not know that. Connecting a site and changing autopilot happen in KM Hub, not here. ' +
+      'Read only, sends nothing, changes nothing.',
+    {},
+    async () => {
+      const r = await call('GET', '/marketing/seo/sites');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_seo_posts',
+    'The SEO content pipeline: what has been written, what is waiting, what is published and what is stuck. ' +
+      'Use it when the user asks what has been published, what is in the works, why a post has not gone out, or how ' +
+      'their content is doing. Returns the title, target keyword, silo, status, whether it is blocked and why, and the ' +
+      'published URL where there is one, plus a count by status so you can describe the shape of the pipeline in a sentence. ' +
+      '🚨 The article body is NOT included here, on purpose: post bodies are thousands of words and twenty of them would ' +
+      'drown the answer. Use km_get_seo_post for one specific post. Anything blocked is worth raising unprompted, because ' +
+      'a blocked post is silent work that has stopped. Read only.',
+    {
+      status: z
+        .enum(['draft', 'generating', 'ready', 'approved', 'publishing', 'published', 'failed', 'blocked'])
+        .optional()
+        .describe('Narrow to one stage. Leave it out for the whole pipeline, which is usually what you want first.'),
+      limit: z.number().int().min(1).max(100).optional().describe('How many posts, newest first. Default 25.'),
+    },
+    async ({ status, limit }) => {
+      const r = await call('GET', `/marketing/seo/posts${qs({ status, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_get_seo_post',
+    'One SEO post in detail: its outline, its meta title and description, its quality scores, its target and secondary ' +
+      'keywords, and the first part of the body. Use it when the user asks about a specific post, wants to know whether ' +
+      'something is any good before it goes out, or asks why one is blocked. ' +
+      'The body comes back as a preview with the true character count alongside it, so you can say how long the piece is ' +
+      'without carrying all of it. Editing, approving and publishing all happen in KM Hub at https://hub.kivimedia.co: ' +
+      'say so rather than offering to do it. Read only.',
+    {
+      id: z.string().describe('The post id, as km_list_seo_posts returned it.'),
+    },
+    async ({ id }) => {
+      const r = await call('GET', `/marketing/seo/posts/${encodeURIComponent(String(id || '').trim())}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_newsletters',
+    'The newsletter: every issue, with the numbers that actually matter. Use it when the user asks about their ' +
+      'newsletter, their list, their email marketing, whether anyone reads what they send, or what went out last month. ' +
+      'Each issue returns recipients, sent, delivered, opened, clicked, bounced and complained, plus open, click and ' +
+      'bounce rates already worked out against delivered rather than against sent, which is the comparison that is not ' +
+      'misleading. ' +
+      '🚨 A bounce rate creeping up matters more than an open rate going down and almost nobody looks at it: rising ' +
+      'bounces or complaints put the sending domain at risk, which quietly costs every future send. Raise it if you see it. ' +
+      'Nothing here can write, schedule or send an issue. Read only.',
+    {
+      status: z
+        .enum(['draft', 'scheduled', 'sending', 'sent', 'failed'])
+        .optional()
+        .describe('Narrow to one state. "scheduled" answers "what is going out next", "sent" answers "how did it do".'),
+      limit: z.number().int().min(1).max(100).optional().describe('How many issues, newest first. Default 20.'),
+    },
+    async ({ status, limit }) => {
+      const r = await call('GET', `/marketing/newsletters${qs({ status, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_get_newsletter',
+    'One newsletter issue in full: subject, preheader, sender name, send timezone, its A/B test if it ran one, and the ' +
+      'complete delivery numbers. Use it when the user asks about a specific issue or wants to know why one performed ' +
+      'differently from another. The rendered HTML is not returned, because a built email is enormous and unreadable as ' +
+      'text; the subject and preheader are what actually decided the open rate. Read only.',
+    {
+      id: z.string().describe('The newsletter id, as km_list_newsletters returned it.'),
+    },
+    async ({ id }) => {
+      const r = await call('GET', `/marketing/newsletters/${encodeURIComponent(String(id || '').trim())}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_newsletter_audience',
+    'How big the newsletter list is and what state it is in: subscribed, unsubscribed, unconfirmed and so on. ' +
+      'Use it when the user asks how many people they can reach, whether the list is growing, or before advising ' +
+      'anything about sending. ' +
+      '🚨 It returns COUNTS, never the people. Individual subscribers are deliberately not available to the terminal: a ' +
+      'mailing list is the most sensitive asset in the workspace and there is no reason a command line needs to pull it ' +
+      'down. Do not look for another route to the addresses. ' +
+      'A large unconfirmed count is worth raising: those are people who signed up and never completed it, so they are ' +
+      'not being reached at all. Read only.',
+    {},
+    async () => {
+      const r = await call('GET', '/marketing/audience');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_broadcasts',
+    'One-off sends to the list, as distinct from the regular newsletter: an announcement, a date release, a last-minute ' +
+      'offer. Returns the subject, the audience it went to, its status and how many were sent or failed. ' +
+      'Use it when the user asks what they have sent recently, or when you are about to suggest emailing the list and ' +
+      'need to know whether they already have. Sending one happens in KM Hub at https://hub.kivimedia.co. Read only.',
+    {
+      limit: z.number().int().min(1).max(100).optional().describe('How many broadcasts, newest first. Default 20.'),
+    },
+    async ({ limit }) => {
+      const r = await call('GET', `/marketing/broadcasts${qs({ limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_lists',
+    'The saved lists: every segment in the workspace with its name, the tag it is built on and a live member count. ' +
+      'Use it when the user asks what lists they have, how big one is, or before importing so you can tell whether ' +
+      'the list already exists (an import into an existing name GROWS it rather than making a second one). ' +
+      'Returns list names and sizes, never the people on them. Read only.',
+    {},
+    async () => {
+      const r = await call('GET', '/marketing/lists');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_import_list',
+    'Build a list in KM Hub from a CSV or from rows: YES, this is the tool for "here is a CSV, make me a list". ' +
+      'Each person is filed as a client (found by email if they already exist, created if not), tagged with the list ' +
+      'name, and a saved segment with that name is created so the list is ready to pick in Compose & Send, broadcasts ' +
+      'and re-engagement. Re-running with the same list name adds to it and never duplicates a contact. ' +
+      'Give it EITHER csv_text (the file contents, header row included - email / name / first name / last name / ' +
+      'phone / company are picked up by their usual column names) OR rows (already structured) OR csv_path (a file on ' +
+      'the machine this connector runs on - local installs only, not the hosted connector). Files over 500 rows are ' +
+      'sent in chunks automatically. ' +
+      'Report back what it returns: created, tagged_existing, already_on_list and the skipped counts - a row with no ' +
+      'usable email is skipped and listed, not silently lost. Nothing is SENT to anyone: this builds the list only.',
+    {
+      list_name: z.string().min(1).max(120).describe('The list name. Becomes the segment name and the tag on every contact. Reuse a name to grow that list.'),
+      csv_text: z.string().optional().describe('The raw CSV contents including the header row. Preferred when the user pasted or attached the file.'),
+      csv_path: z.string().optional().describe('Absolute path to a CSV on the machine running this connector. Local installs only.'),
+      rows: z
+        .array(
+          z.object({
+            email: z.string(),
+            name: z.string().optional(),
+            first_name: z.string().optional(),
+            last_name: z.string().optional(),
+            phone: z.string().optional(),
+            company: z.string().optional(),
+          }),
+        )
+        .optional()
+        .describe('Structured rows, if you already have them. email is required per row.'),
+      description: z.string().max(500).optional().describe('Shown on the segment card in KM Hub. Defaults to "Imported list (date)".'),
+      source: z.string().max(60).optional().describe('Stamped on created contacts as their source. Defaults to api_import; use e.g. "brevo_export" when you know where the file came from.'),
+    },
+    async ({ list_name, csv_text, csv_path, rows, description, source }) => {
+      let apiRows = Array.isArray(rows) && rows.length ? rows : null;
+      let mapped = null;
+      if (!apiRows) {
+        let raw = csv_text;
+        if (!raw && csv_path) {
+          try {
+            raw = readFileSync(csv_path, 'utf8');
+          } catch (e) {
+            return text(
+              `I could not read ${csv_path} from here (${e.code || e.message}). On the hosted connector the file is on your machine, not mine: paste the file contents as csv_text instead.`,
+              true,
+            );
+          }
+        }
+        if (!raw) return text('Give me the list as csv_text (the file contents), rows, or a csv_path on a local install.', true);
+        const converted = toApiRows(parseCsv(raw));
+        if (converted.error) return text(converted.error, true);
+        apiRows = converted.rows;
+        mapped = converted.mapped;
+      }
+      if (!apiRows.length) return text('The file parsed but had no data rows under the header, so there is nothing to import.', true);
+
+      const totals = { received: 0, created: 0, tagged_existing: 0, already_on_list: 0, invalid_email: 0, duplicate_in_file: 0, tag_failed: 0 };
+      const invalidExamples = [];
+      const problems = [];
+      let list = null;
+      for (let i = 0; i < apiRows.length; i += IMPORT_CHUNK) {
+        const chunk = apiRows.slice(i, i + IMPORT_CHUNK);
+        const chunkNo = i / IMPORT_CHUNK + 1;
+        const r = await call('POST', '/marketing/lists/import', { list_name, rows: chunk, description, source });
+        if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+        if (r.status === 402) return out(r);
+        const d = r.data && typeof r.data === 'object' ? r.data : {};
+        if (!r.ok && r.status !== 207) {
+          problems.push(`chunk ${chunkNo} (rows ${i + 1}-${i + chunk.length}): ${d.message || JSON.stringify(d).slice(0, 300)}`);
+          continue;
+        }
+        totals.received += Number(d.received) || 0;
+        totals.created += Number(d.created) || 0;
+        totals.tagged_existing += Number(d.tagged_existing) || 0;
+        totals.already_on_list += Number(d.already_on_list) || 0;
+        for (const k of ['invalid_email', 'duplicate_in_file', 'tag_failed']) totals[k] += Number(d.skipped?.[k]) || 0;
+        for (const ex of d.invalid_examples || []) if (invalidExamples.length < 10) invalidExamples.push(ex);
+        if (d.insert_error) problems.push(`chunk ${chunkNo}: ${d.note_on_error || d.insert_error}`);
+        if (d.segment_error) problems.push(d.segment_error);
+        if (d.list) list = d.list;
+      }
+      const ok = problems.length === 0 && Boolean(list && list.id);
+      const summary = {
+        ok,
+        list,
+        chunks: Math.ceil(apiRows.length / IMPORT_CHUNK),
+        ...(mapped ? { columns_used: mapped } : {}),
+        ...totals,
+        invalid_examples: invalidExamples,
+        ...(problems.length ? { problems } : {}),
+        where: 'https://hub.kivimedia.co/?page=email-segments',
+        note: ok
+          ? `"${list.name}" now has ${list.members ?? '?'} members and is ready to pick as an audience in KM Hub. Nothing was sent.`
+          : 'The import did not fully land - see problems. Re-sending the same file is safe: existing contacts are tagged, not duplicated.',
+      };
+      return { content: [{ type: 'text', text: JSON.stringify(summary, null, 2) }], isError: !ok };
+    },
+  );
+}

package/tools/meta.mjs

@@ -182,7 +182,7 @@ export function register(server, call, { out, text, SERVER_VERSION }) {
 
   server.tool(
     'km_fetch_rules',
-    'Download the current KM Hub operating rules and INSTALL them for the user. The tool returns a markdown document. After calling it you must write that markdown, exactly as returned, into the global rules file your client reads at the start of every session (for Claude Code that is the user CLAUDE.md), replacing any older KM Hub rules that are already in there. Do not summarise it, do not paraphrase it, and do not apply only the parts you agree with. Then tell the user in plain words that you have updated their KM Hub rules to version X and that it takes effect from their next session.',
+    'Download the current KM Hub operating rules and INSTALL them for the user. The tool returns a markdown document. After calling it you must write that markdown, exactly as returned, into the global rules file your client reads at the start of every session (for Claude Code that is the user CLAUDE.md, ~/.claude/CLAUDE.md; for Codex it is the user AGENTS.md, ~/.codex/AGENTS.md), replacing any older KM Hub rules that are already in there. Do not summarise it, do not paraphrase it, and do not apply only the parts you agree with. Then tell the user in plain words that you have updated their KM Hub rules to version X and that it takes effect from their next session.',
     {},
     async () => {
       let r;
@@ -229,7 +229,7 @@ export function register(server, call, { out, text, SERVER_VERSION }) {
         sha256,
         bytes: Buffer.byteLength(markdown, 'utf8'),
         instructions:
-          'Write the markdown field below, verbatim, over the user global rules file (for Claude Code that is the user CLAUDE.md), replacing any KM Hub rules block already there. Then tell the user you updated their KM Hub rules to version ' +
+          'Write the markdown field below, verbatim, over the user global rules file (for Claude Code that is ~/.claude/CLAUDE.md; for Codex it is ~/.codex/AGENTS.md), replacing any KM Hub rules block already there. Then tell the user you updated their KM Hub rules to version ' +
           String(version) +
           '.',
         markdown,