@kivimedia/kmhub 2.0.0 → 2.9.1

package/tools/military.mjs

@@ -0,0 +1,244 @@
+/**
+ * Tool family: military - the USO MWR Military Scout, read from the terminal.
+ *
+ * Every other radar in KM Hub is a scan that goes LOOKING for work, which is why radar.mjs
+ * reaches all nine of them through one pair of mission tools. This one is not that shape. The
+ * military market is ENUMERABLE rather than searchable: a finite published list of Army garrisons,
+ * USO centers, Navy MWR, Marine MCCS, Air Force FSS and Coast Guard desks, each on a predictable
+ * URL. So the thing a person wants from the terminal is not "what did the last scan find", it is
+ * "show me what is already in there", and that needs its own family rather than a sixth entry in
+ * a mission list.
+ *
+ *   km_military_directory    -> GET /military/directory
+ *   km_military_desks        -> GET /military/desks
+ *   km_military_installation -> GET /military/installations/:ref
+ *
+ * 🚨 READ ONLY, and there are three separate reasons, all of which the descriptions say out loud:
+ *
+ *   1. NOTHING HERE SUBMITS, APPROVES OR SENDS. The engine worker registers the
+ *      military_radar_submit job with no browser driver, so it resolves the read-only one and
+ *      structurally cannot type or press anything. Approving a packet is deliberately a human act
+ *      in the web app. A terminal tool that appeared to submit would be a lie told to a government
+ *      office in a client's name, which is the worst outcome this feature has available.
+ *   2. NOTHING HERE STARTS A SWEEP. Queueing one is admin-only under RLS in the web app, and the
+ *      API runs on the service role, which bypasses RLS: a start tool would quietly hand any
+ *      read/write key a power the product refuses to a non-admin member. The sweep button lives in
+ *      KM Hub where the person pressing it is checked. Whether a sweep is running is readable, and
+ *      it is readable through the tool that already answers that for every radar:
+ *      km_list_radar_scans with kind 'military_radar_ingest'.
+ *   3. Reading costs NOTHING and sends NOTHING. The directory is shared reference data with global
+ *      read, already populated before anybody runs anything, so there is no first click to make
+ *      and no bill for looking.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'military';
+
+export const TOOLS = [
+  'km_military_directory',
+  'km_military_desks',
+  'km_military_installation',
+];
+
+// Finding and reaching buyers is outreach work, so this family joins that profile. It is not in
+// `core`: a session that only wants orientation should not carry three more schemas.
+export const PROFILES = ['outreach'];
+
+/**
+ * Has this KM Hub simply never heard of the route, or did the route run and find nothing?
+ *
+ * 🚨 The neighbouring families treat every 404 as "not deployed here", which is safe for them
+ * because none of their routes can answer 404 themselves. This family has one that can: asking for
+ * an installation that is not in the directory is a real, ordinary 404. Collapsing the two would
+ * answer a plain typo with "your KM Hub does not have the military directory", which is a false
+ * statement about the product rather than a wrong answer about a base. So only the router's own
+ * self-describing 404, which carries the whole route list, counts as a missing route.
+ */
+function routeMissing(r) {
+  if (r.status === 405 || r.status === 501) return true;
+  if (r.status !== 404) return false;
+  const body = r && r.data && typeof r.data === 'object' ? r.data : null;
+  if (!body) return true;
+  if (Array.isArray(body.routes)) return true;
+  return typeof body.message === 'string' && body.message.startsWith('Unknown route');
+}
+
+const NOT_SUPPORTED =
+  'This KM Hub does not serve the military directory to the terminal yet. Nothing is broken: the workspace is fine ' +
+  'and every other tool works as normal. The directory is there in the web app at https://hub.kivimedia.co under ' +
+  'Outbound, named USO MWR Military Scout.';
+
+/**
+ * The six buyer lanes, in one clause each.
+ *
+ * 🚨 This paragraph is here because a client on a live call asked "what is an NAF?" and nothing
+ * answered him. These labels are military shorthand, and a model that repeats them without
+ * expanding them is no more useful than the raw row. Every acronym any answer can print is
+ * expanded at least once here.
+ */
+const LANES =
+  'The six lanes and who is actually on the other end. `special_events`: the office that puts on ' +
+  'the base own concerts, festivals and family days, which is the entertainment budget itself. ' +
+  '`marketing`: the desk that advertises those events, which rarely books an act but walks your ' +
+  'name to the office that does. `sponsorship`: commercial sponsorship, where a company pays and ' +
+  'the base receives the act, so the money never comes out of the events budget. `naf_prime`: NAF ' +
+  'is non-appropriated funds, the money a base earns from its own clubs and shops rather than from ' +
+  'Congress, and a prime is a private company that already holds the contract to spend it and hires ' +
+  'acts underneath it. `uso`: a USO center is the lounge on or beside a base that troops walk into, ' +
+  'and each center programs its own floor. `afe`: Armed Forces Entertainment, the Department of ' +
+  'Defense office that sends entertainment to troops posted overseas, which publishes no route for ' +
+  'an act to contact it at all, so nobody reaches it directly.';
+
+const NO_SEND =
+  'What it will NOT do: it cannot write to a desk, fill a form, approve a packet or send anything, ' +
+  'and no other tool here can either. Approving the words and submitting them is a person job in KM ' +
+  'Hub at https://hub.kivimedia.co, on purpose, because the other end is a government office. Never ' +
+  'tell somebody a message went out.';
+
+const NO_INVENTION =
+  'Never construct an address. These offices publish shared desk mailboxes whose middle token ' +
+  'differs per garrison, so an address that is not in the answer does not exist to us, and a phone ' +
+  'or web form with no mailbox beside it is the NORMAL published state here rather than missing data.';
+
+export function register(server, call, { out, text, qs }) {
+  server.tool(
+    'km_military_directory',
+    'The military entertainment buyers KM Hub has already enumerated: every Army garrison, USO center, Navy MWR, ' +
+      'Marine MCCS, Air Force FSS and Coast Guard desk that publishes a way for an act to reach it, plus the global ' +
+      'gateways. ' +
+      'Reach for it whenever somebody asks about military work, bases, garrisons, the USO, MWR, overseas troops or ' +
+      'who books entertainment on a base, and reach for it FIRST rather than describing the feature: this directory ' +
+      'is shared reference data that is already full before anybody runs anything, so there is nothing to start and ' +
+      'nothing to wait for. Reading it costs nothing, spends nothing and sends nothing. ' +
+      '🚨 Lead with the `directory` block, which is counted from the rows and not asserted: how many installations, ' +
+      'how many distinct desks, how many are overseas, and when it was last read. Say those numbers before any ' +
+      'individual row, because the single thing people get wrong about this surface is assuming it is empty. ' +
+      'Call it with no arguments to see the whole thing, then narrow. Every filter is optional and `filters_applied` ' +
+      'says back which ones are doing the narrowing, so an empty result is explained rather than shrugged at. ' +
+      LANES +
+      ' ' +
+      NO_INVENTION +
+      ' ' +
+      'Whether a sweep is running is a different question, answered by km_list_radar_scans with kind ' +
+      "'military_radar_ingest'. Starting one is done in KM Hub, never from here. " +
+      NO_SEND,
+    {
+      q: z
+        .string()
+        .optional()
+        .describe(
+          'Free text, in the words the person used. Matches the name, the place, the region, the branch as the ' +
+            'badge words it, and the theater heading, in any order: "okinawa uso" and "uso okinawa" both work.',
+        ),
+      branch: z
+        .enum(['army', 'navy', 'usmc', 'usaf', 'uscg', 'uso', 'afe', 'naf_prime'])
+        .optional()
+        .describe('One service or gateway. Leave it out to see all of them.'),
+      lane: z
+        .enum(['special_events', 'marketing', 'sponsorship', 'afe', 'naf_prime', 'uso'])
+        .optional()
+        .describe('Only installations that publish a desk on this buyer lane. See the lane guide in this description.'),
+      route: z
+        .enum(['email', 'phone', 'form'])
+        .optional()
+        .describe('Only installations reachable this way. Use it when somebody says they want places they can email.'),
+      region: z
+        .string()
+        .optional()
+        .describe('A region or theater as published or as grouped, for example "Europe", "Indo Pacific", "Japan", "Germany".'),
+      state: z.string().optional().describe('A US state or province. Most rows publish no state, so prefer region or q.'),
+      overseas: z
+        .boolean()
+        .optional()
+        .describe('True for installations outside the continental United States only, including Guam and Puerto Rico.'),
+      limit: z.number().int().min(1).max(200).optional().describe('How many installations to return. Default 40. Check `truncated`.'),
+    },
+    async ({ q, branch, lane, route, region, state, overseas, limit }) => {
+      const r = await call('GET', `/military/directory${qs({ q, branch, lane, route, region, state, overseas, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_military_desks',
+    'The desks themselves rather than the places: one row per mailbox, phone line or web form, however many ' +
+      'installations it serves. ' +
+      'This is the list to reach for when somebody asks who they would actually contact, or wants the special events ' +
+      'offices in Europe, or the mailboxes they could write to. ' +
+      '🚨 `serves_installations` is the number that matters and is the whole reason this tool exists separately from ' +
+      'km_military_directory: one regional USO organisation answers a SINGLE mailbox for every center under it, so a ' +
+      'list counted by location would have somebody send the same desk the same message eight times, which is the ' +
+      'fastest way to be ignored across an entire branch. One desk, one message. ' +
+      'Most of these buyers publish no named person, so `contact_name` is usually empty and that is the office ' +
+      'working normally, not a gap to fill in. `source_url` is the page each route was read off, and `evidence_quote` ' +
+      'is available on the installation view if somebody wants to see the wording it came from. ' +
+      NO_INVENTION +
+      ' ' +
+      'Read only. Costs nothing, spends nothing. ' +
+      NO_SEND,
+    {
+      lane: z
+        .enum(['special_events', 'marketing', 'sponsorship', 'afe', 'naf_prime', 'uso'])
+        .optional()
+        .describe('The buyer lane. Different lanes spend different budgets and each needs its own message.'),
+      route: z
+        .enum(['email', 'phone', 'form'])
+        .optional()
+        .describe('Only desks reachable this way. "email" is the one to use when somebody wants a list they can write to.'),
+      branch: z
+        .enum(['army', 'navy', 'usmc', 'usaf', 'uscg', 'uso', 'afe', 'naf_prime'])
+        .optional()
+        .describe('One service or gateway.'),
+      region: z.string().optional().describe('A region or theater, for example "Europe", "Indo Pacific", "Germany".'),
+      q: z.string().optional().describe('Free text against the installation the desk belongs to, in the words the person used.'),
+      overseas: z.boolean().optional().describe('True for desks outside the continental United States only.'),
+      limit: z.number().int().min(1).max(200).optional().describe('How many desks to return. Default 40, busiest desks first. Check `truncated`.'),
+    },
+    async ({ lane, route, branch, region, q, overseas, limit }) => {
+      const r = await call('GET', `/military/desks${qs({ lane, route, branch, region, q, overseas, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_military_installation',
+    'One installation in full: every desk it publishes with its lane and its route, the page each one was read off, ' +
+      'the events on its own calendar, and whatever outreach this workspace has already recorded against it. ' +
+      'Use it after km_military_directory when somebody picks a base, or whenever they name one directly. It takes ' +
+      'either the id from a previous answer or the slug, for example "benning". ' +
+      'The events are the why-now: naming a garrison own event is the difference between a note that gets read and ' +
+      'one that gets filed. ' +
+      '🚨 `window_is_published` decides whether the pitch window may be spoken as a fact. True means the date came off ' +
+      'something the installation actually published. False means it was worked out from the usual season and this ' +
+      'year date is not out yet, so it is a guess and must never be repeated as though it were confirmed. ' +
+      '`your_outreach` is this workspace own audit trail and nothing more. A packet reading `approved` means a named ' +
+      'person signed off those exact words and NOTHING has been sent to the desk. `possibly_submitted` means a submit ' +
+      'button was pressed and the page could not be read back afterwards, so that garrison may or may not hold the ' +
+      'packet: only somebody who telephones the office can settle it, and it is never retried on its own. ' +
+      NO_INVENTION +
+      ' ' +
+      'Read only. Costs nothing, spends nothing. ' +
+      NO_SEND,
+    {
+      installation: z
+        .string()
+        .describe('The installation id from a previous answer, or its slug, for example "benning" or "uso-okinawa".'),
+    },
+    async ({ installation }) => {
+      const ref = String(installation || '').trim();
+      if (!ref) {
+        return text(
+          'I need to know which installation. km_military_directory lists them, and each row carries the id and the ' +
+            'slug this tool takes.',
+        );
+      }
+      const r = await call('GET', `/military/installations/${encodeURIComponent(ref)}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+}

package/tools/outreach.mjs

@@ -92,8 +92,11 @@ export function register(server, call, { out, qs }) {
       'Send the FULL replacement text, never a description of the change, never a diff, never only the paragraph you touched. ' +
       'Read the message first with km_read_outreach_draft so you are rewriting what is really there. ' +
       'It refuses, and says why, once a person has approved, scheduled, sent or cancelled the message: wording someone signed off on is the ' +
-      'wording that goes out. It also refuses to rewrite the body of a message that carries a photo gallery or a saved template, because the ' +
-      'plain text is only half of what the recipient sees; the subject can still be changed. ' +
+      'wording that goes out. ' +
+      'A message carrying PHOTOS rewrites normally: the rich version is rebuilt around your new words and the photos stay exactly where they ' +
+      'are, so there is no need to finish the wording before adding images. ' +
+      'The one thing it will not rewrite is a draft built from a saved TEMPLATE, where the markup is hand built around this copy and the plain ' +
+      'text is only half of what the recipient sees; the subject can still be changed there. ' +
       'Editing does NOT approve and does NOT send. The message stays in the queue and a person still approves it. ' +
       'The wording you replaced is kept in the AI activity log so nothing is lost, but there is no one-click undo for an edit: ' +
       'putting the old words back means editing again, so do not promise the user a revert button.',
@@ -146,8 +149,18 @@ export function register(server, call, { out, qs }) {
       'or unenroll anybody.',
     {
       campaign_id: z.string().describe('UUID of the campaign (see km_list_outreach_campaigns).'),
+      confirm_token: z
+        .string()
+        .optional()
+        .describe(
+          'Leave this out on the first call. This action needs an explicit yes from the person you are working with: '
+            + 'KM Hub answers 409 with a plain description of exactly what would happen, plus a token. Show them that '
+            + 'description in those words, wait for a real answer, and only then call again with the token and the SAME '
+            + 'arguments. A yes for one action never authorises a different one.',
+        ),
     },
-    async ({ campaign_id }) => out(await call('POST', `/outreach-campaigns/${encodeURIComponent(String(campaign_id))}/pause`)),
+    async ({ campaign_id, confirm_token }) =>
+      out(await call('POST', `/outreach-campaigns/${encodeURIComponent(String(campaign_id))}/pause`, { confirm_token })),
   );
 
   server.tool(
@@ -158,8 +171,18 @@ export function register(server, call, { out, qs }) {
       'one; those are decisions a person makes in KM Hub. Every message on the campaign still waits for a human approval before it sends.',
     {
       campaign_id: z.string().describe('UUID of the campaign (see km_list_outreach_campaigns).'),
+      confirm_token: z
+        .string()
+        .optional()
+        .describe(
+          'Leave this out on the first call. This action needs an explicit yes from the person you are working with: '
+            + 'KM Hub answers 409 with a plain description of exactly what would happen, plus a token. Show them that '
+            + 'description in those words, wait for a real answer, and only then call again with the token and the SAME '
+            + 'arguments. A yes for one action never authorises a different one.',
+        ),
     },
-    async ({ campaign_id }) => out(await call('POST', `/outreach-campaigns/${encodeURIComponent(String(campaign_id))}/resume`)),
+    async ({ campaign_id, confirm_token }) =>
+      out(await call('POST', `/outreach-campaigns/${encodeURIComponent(String(campaign_id))}/resume`, { confirm_token })),
   );
 
   server.tool(

package/tools/pending.mjs

@@ -0,0 +1,122 @@
+/**
+ * Tool family: pending - what a scheduled run decided should happen, waiting on a person.
+ *
+ * Workstream D1, the design that survived review.
+ *
+ * A scheduled run has nobody at the keyboard, so it cannot give the confirmation a
+ * money-spending or client-visible action requires. The first shipped answer to that
+ * was "then schedules only read". This is the second answer: a scheduled run may
+ * DECIDE something should happen, and may not DO it. The intent lands here carrying
+ * the sentence the SERVER wrote about it, and a person approves.
+ *
+ * 🚨 THE SENTENCE IS NOT WRITTEN BY A MODEL. It comes from describeAction() in the
+ * API, the same code that will carry the action out. That is the whole reason it can
+ * be trusted as a description of what approving will do. Never paraphrase it into
+ * something friendlier when presenting it: the paraphrase is what a person would be
+ * consenting to, and it is not what will run.
+ *
+ * 🚨 NAMING. This family is deliberately NOT called proposals and its tools are
+ * deliberately NOT km_list_proposals. That name is already taken by money.mjs for
+ * SALES proposals sent to clients, and MCP tool names are a flat namespace: a second
+ * km_list_proposals would have shadowed a shipped tool rather than erroring, so
+ * "show me my proposals" would quietly have started answering a different question.
+ * Same reason the routes are /pending-actions and not /proposals, which money.ts
+ * already owns and, being registered first, would have won the match.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'pending';
+
+export const TOOLS = ['km_list_pending_actions', 'km_approve_pending_action', 'km_reject_pending_action'];
+
+export const PROFILES = ['*'];
+
+function routeMissing(r) {
+  return r.status === 404 || r.status === 405 || r.status === 501;
+}
+
+const NOT_SUPPORTED =
+  'Your KM Hub does not have the approvals queue in the terminal yet. That is not a fault: everything else works as ' +
+  'normal, and anything waiting for a decision is in the web app at https://hub.kivimedia.co.';
+
+export function register(server, call, { out, text }) {
+  server.tool(
+    'km_list_pending_actions',
+    'Actions that are waiting for a person to say yes: things a scheduled run decided should happen and then stopped, ' +
+      'because there was nobody there to confirm them. Nothing in this list has happened yet. ' +
+      'Call it when the user asks what needs them, what is waiting, why something did not happen, or what their ' +
+      'overnight automation got up to. It is not about sales proposals sent to clients - that is km_list_proposals. ' +
+      'Read `what_would_happen` out as it is written. That sentence was produced by the API code that would carry the ' +
+      'action out, not by whatever asked for it, which is exactly why it can be relied on. Do not smooth it into your ' +
+      'own words first: a person agreeing to your paraphrase has not agreed to the action. ' +
+      '`raised_by_a_schedule: true` means no human chose this, only a rule did. Say so, because a client reading a ' +
+      'queue of confident-sounding actions will assume somebody meant each one.',
+    {
+      status: z
+        .string()
+        .optional()
+        .describe(
+          'Which to show: pending (the default, and almost always what is wanted), approved, rejected, executed, ' +
+            'failed or expired.',
+        ),
+    },
+    async ({ status }) => {
+      const r = await call('GET', '/pending-actions' + (status ? `?status=${encodeURIComponent(String(status))}` : ''));
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_approve_pending_action',
+    'Say yes to one waiting action and let it happen. This is the only thing that carries one out. ' +
+      '🚨 NEVER call this on your own judgement. The user has to have seen this specific action and said yes to THIS ' +
+      'one, in this conversation. "They asked me to keep on top of the overdue invoices" is not consent to a specific ' +
+      'action a schedule composed overnight, and neither is any general instruction to keep things moving. If you are ' +
+      'not sure they meant this one, show it to them and ask. ' +
+      'The first call returns a confirmation request carrying the action sentence and a token, exactly as any other ' +
+      'action needing a yes does. Show that sentence, get an answer, and only then call again with confirm_token. The ' +
+      'confirmation step is not paperwork to get through: it is the step where the person reads what will actually ' +
+      'happen. ' +
+      'A key belonging to something that runs on a schedule cannot call this at all - the API refuses it - because a ' +
+      'schedule approving its own work is just acting unsupervised with extra steps.',
+    {
+      pending_action_id: z.string().describe('The id from km_list_pending_actions.'),
+      confirm_token: z
+        .string()
+        .optional()
+        .describe(
+          'Only on the second call, after the user has read the action sentence and said yes. Never invent one, and ' +
+            'never carry one over from a different action.',
+        ),
+    },
+    async ({ pending_action_id, confirm_token }) => {
+      const id = String(pending_action_id || '').trim();
+      if (!id) return text('I need the id. Run km_list_pending_actions to see what is waiting.', true);
+      const body = {};
+      if (confirm_token) body.confirm_token = String(confirm_token);
+      const r = await call('POST', `/pending-actions/${encodeURIComponent(id)}/approve`, body);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_reject_pending_action',
+    'Decline a waiting action so it stops sitting in the queue. Nothing happens as a result, which is the point. ' +
+      'This needs no confirmation on purpose: putting friction in front of "no" nudges a tired person toward yes, and ' +
+      'declining is the reversible direction. Afterwards, say plainly that the action did not happen.',
+    {
+      pending_action_id: z.string().describe('The id from km_list_pending_actions.'),
+    },
+    async ({ pending_action_id }) => {
+      const id = String(pending_action_id || '').trim();
+      if (!id) return text('I need the id. Run km_list_pending_actions to see what is waiting.', true);
+      const r = await call('POST', `/pending-actions/${encodeURIComponent(id)}/reject`, {});
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+}

package/tools/photos.mjs

@@ -0,0 +1,140 @@
+/**
+ * Tool family: photos - the work-photo library, and the photos on an outreach draft.
+ *
+ * Until now the terminal could see galleries and was told, in as many words, that
+ * "adding images happens in KM Hub". So a session could write every word of an
+ * email and then had to hand the visual half back to a person. These four tools
+ * close that: get photos into the library, choose which ones ride an email, and
+ * choose the shape they sit in.
+ *
+ * The safety line is the same as the rest of outreach: nothing here sends. A
+ * draft with a gallery on it is still a draft, and a person still approves it.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'photos';
+
+export const TOOLS = [
+  'km_list_work_photos',
+  'km_add_work_photos',
+  'km_attach_draft_photos',
+  'km_remove_draft_photos',
+];
+
+export const PROFILES = ['outreach', 'content'];
+
+const LAYOUT = ['grid', 'pyramid'];
+
+export function register(server, call, { out }) {
+  server.tool(
+    'km_list_work_photos',
+    'The real work photos this business has on file, grouped into the themed sets they belong to, each with its caption, ' +
+      'its hosted URL and the id you need to put it on an email. ' +
+      'Reach for it before attaching photos to anything, so you are choosing from what actually exists rather than guessing, ' +
+      'and when the user asks what imagery they have. ' +
+      'These are the photos that ride inside first-touch outreach emails, so they are also the honest answer to "what does a ' +
+      'prospect see when we write to them". ' +
+      'An empty library is worth saying out loud: it means every email this workspace sends is text only. Read only.',
+    {},
+    async () => out(await call('GET', '/photos')),
+  );
+
+  server.tool(
+    'km_add_work_photos',
+    'Add photos to the work-photo library, either by URL or as base64, into a named set. Once they are in, any outreach draft ' +
+      'in the workspace can use them. ' +
+      'Reach for it when the user hands you images, points you at some, or asks to get their work photos in. ' +
+      'Give each one a short caption where you can: the caption becomes the image alt text that a recipient with images turned ' +
+      'off actually reads, so a photo with no caption is a blank box to them. ' +
+      '🚨 SIZE IS THE ONE THING THAT WILL BITE. Each photo must be under about 1.2MB, and a phone original is five times that. ' +
+      'KM Hub resizes in the browser before uploading; nothing here can, so an oversized photo is REFUSED rather than quietly ' +
+      'accepted, and the answer tells you which one and why. Resize to roughly 1600px on the longest edge as a JPEG around 82 ' +
+      'percent quality and send it again. Do that yourself rather than asking the user to. ' +
+      'JPEG, PNG and GIF only: HEIC and WebP render as a broken box in Gmail and Outlook, which is worse than sending no photo. ' +
+      'It adds to the library and nothing else. It does not attach anything to an email and it does not send.',
+    {
+      photos: z
+        .array(
+          z.object({
+            url: z.string().optional().describe('Public http or https URL to fetch the image from.'),
+            base64: z.string().optional().describe('The image itself, base64 encoded. A data: URL is fine. Use this for a local file.'),
+            caption: z.string().optional().describe('Short human caption. Becomes the alt text, and helps the matcher pick this set for the right lead.'),
+            filename: z.string().optional().describe('Original filename, used to name the stored file. Optional.'),
+          }),
+        )
+        .min(1)
+        .max(20)
+        .describe('The photos to add. Each needs either a url or a base64. Twenty per call.'),
+      theme: z
+        .string()
+        .optional()
+        .describe(
+          'The set these belong to, in plain words, like "burning rubber" or "grand openings". Default "my best work". ' +
+            'Sets are how the right photos reach the right lead, so a name that describes the WORK beats a name that describes the date.',
+        ),
+    },
+    async ({ photos, theme }) => out(await call('POST', '/photos', { photos, theme })),
+  );
+
+  server.tool(
+    'km_attach_draft_photos',
+    'Put a photo gallery on an outreach draft that is still waiting for approval, and choose the shape it sits in. ' +
+      'This is how "add some photos to that email" actually lands: the recipient opens the message and sees the words followed ' +
+      'by the pictures. ' +
+      'LAYOUT. "pyramid" is one big image across the top, then two side by side, then three, which is the shape that reads as ' +
+      'designed rather than dumped, and it is built around six photos. "grid" is the plainer two-across block and is what every ' +
+      'existing campaign already sends. ' +
+      'Pick the photos with photo_ids when the order matters, and put the strongest image FIRST, because in a pyramid the first ' +
+      'one is the big one. Pass a theme instead to take a whole set in its own order. ' +
+      'Attaching REPLACES any gallery already on the draft rather than adding a second one. ' +
+      'The wording stays yours afterwards: km_edit_outreach_draft rebuilds the message around these photos and keeps them, so ' +
+      'there is no need to finish the text before adding images. ' +
+      'It refuses on a message that is already approved, scheduled, sent or cancelled, on anything that is not email, and on a ' +
+      'draft built from a saved template, and it says which. It does NOT approve and does NOT send.',
+    {
+      id: z.string().describe('UUID of the draft (see km_list_outreach_drafts).'),
+      layout: z
+        .enum(LAYOUT)
+        .optional()
+        .describe('pyramid for one big then two then three. grid for the plain two-across block. Default grid.'),
+      photo_ids: z
+        .array(z.string())
+        .optional()
+        .describe('UUIDs from km_list_work_photos, in the order they should appear. The first one is the hero in a pyramid.'),
+      theme: z
+        .string()
+        .optional()
+        .describe('Take a whole themed set instead of naming photos. Ignored when photo_ids is given.'),
+      count: z
+        .number()
+        .int()
+        .min(1)
+        .max(12)
+        .optional()
+        .describe('How many photos to use. Defaults to what the layout is built for: 6 for a pyramid, 10 for a grid.'),
+      heading: z
+        .string()
+        .optional()
+        .describe('The quiet line above the photos. Default "A few pieces of our recent work:".'),
+    },
+    async ({ id, layout, photo_ids, theme, count, heading }) =>
+      out(await call('POST', `/outreach-drafts/${encodeURIComponent(String(id))}/photos`, {
+        layout, photo_ids, theme, count, heading,
+      })),
+  );
+
+  server.tool(
+    'km_remove_draft_photos',
+    'Take the photo gallery back off a draft, so it goes back to being a plain text email. ' +
+      'Reach for it when the user says the pictures are wrong, too many, or not right for this prospect, and you want the ' +
+      'message clean before choosing again. ' +
+      'It removes the photos from THIS ONE MESSAGE. The photos stay in the library and every other draft keeps its own. ' +
+      'It only works while the message is still a draft, and it does not send anything.',
+    {
+      id: z.string().describe('UUID of the draft (see km_list_outreach_drafts).'),
+    },
+    async ({ id }) => out(await call('DELETE', `/outreach-drafts/${encodeURIComponent(String(id))}/photos`)),
+  );
+}

package/tools/plays.mjs

@@ -128,7 +128,7 @@ export function register(server, call, { out, text }) {
     'km_play_catalog',
     [
       'The plays: the proven ways a business like this one actually gets booked, kept current by KM Hub and written by people who book work for a living rather than assembled from general marketing advice.',
-      'LOOK HERE FIRST whenever the ask is open ended. "What should I do today", "how do I get more corporate work", "nobody is replying to me", "help me with the fair market", "next month looks empty", "how do I get repeat bookings out of this client": there is very often a play for exactly that, and it will be sharper than anything improvised from what you already know about marketing.',
+      'LOOK HERE FIRST whenever the ask is open ended. "What should I do today", "how do I get more corporate work", "nobody is replying to me", "help me with the fair market", "next month looks empty", "how do I get repeat bookings out of this client": there is very often a play for exactly that, and it will be sharper than anything improvised from what you already know about marketing. This is also where brand and pricing work lives, so check here before answering that the workspace has no luxury, brand, positioning or pricing capability: "am I priced too low", "does my website undersell me", "should I run a discount", "should I add this new service", "what do I say on the call about price", "do you have the luxury tools". The luxury family is in this catalog, not in the tool list.',
       'Free, fast, sends nothing and changes nothing. What comes back is a short list, and each entry is a slug to run it by, its name, and the plain reason a working performer would care about it.',
       'What it deliberately does NOT contain is the method. The steps are not in here and cannot be worked out from the name, so never describe how a play works or promise what it will produce from the catalog alone. The method arrives one step at a time from km_play_run, and only while the subscription is live.',
       'Reading the catalog is not doing the work, and reciting the whole list at somebody is not an answer. Name the one or two that actually fit what they said, in their words, and offer to run one.',