@kivimedia/kmhub 2.0.0 → 2.9.1

package/tools/setup.mjs

@@ -0,0 +1,168 @@
+/**
+ * Tool family: setup - what this workspace is on, connected to, and paying for.
+ *
+ * Workstream B7. Setup was 3 of 21, the largest remaining gap, and the least
+ * glamorous pillar in the product. It is also where a model most often GUESSES:
+ * asked "am I paying for this", "is my email set up properly" or "is Stripe
+ * connected", a connector with no reach here invents a plausible answer.
+ *
+ *   km_subscription     -> GET /setup/subscription
+ *   km_ai_usage         -> GET /setup/usage
+ *   km_list_integrations-> GET /setup/integrations
+ *   km_deliverability   -> GET /setup/deliverability
+ *   km_workspace_config -> GET /setup/config
+ *
+ * 🚨🚨 km_list_integrations returns WHICH providers are connected and NEVER a
+ * credential. There is no parameter that changes that and no verbosity that reveals
+ * one. Do not ask for a key, do not offer to read one, and do not suggest another
+ * route to it. A truncated secret is still a secret.
+ *
+ * 🚨 READ ONLY. Changing a plan, a spend cap or a connection is money or a door.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'setup';
+
+export const TOOLS = [
+  'km_subscription',
+  'km_ai_usage',
+  'km_list_integrations',
+  'km_deliverability',
+  'km_workspace_config',
+  'km_calendar_feed',
+  'km_sms_config',
+];
+
+export const PROFILES = ['*'];
+
+function routeMissing(r) {
+  return r.status === 404 || r.status === 405 || r.status === 501;
+}
+
+const NOT_SUPPORTED =
+  'Your KM Hub does not expose the settings surface to the terminal yet. That is not a fault: the workspace is fine ' +
+  'and every other tool works as normal. Billing, connections and deliverability are all in the web app at ' +
+  'https://hub.kivimedia.co, and this connector will read them once your KM Hub is on a build that publishes them.';
+
+export function register(server, call, { out, text, qs }) {
+  server.tool(
+    'km_subscription',
+    'What this workspace is actually on: the plan, whether it is active, trialing or comped, when it renews, whether it ' +
+      'is set to cancel, and any monthly spend cap. ' +
+      'Call it when the user asks about their plan, their bill, what they are paying for, or whether something is ' +
+      'included. Never answer those from memory or from what a plan name sounds like. ' +
+      '🚨 `cancel_at_period_end` true is worth saying out loud unprompted: Terminal Mode itself stops working when the ' +
+      'subscription lapses, so a user planning work past that date should know. `trial_days_left` deserves the same ' +
+      'treatment. Amounts are in cents. Read only: changing a plan happens in KM Hub.',
+    {},
+    async () => {
+      const r = await call('GET', '/setup/subscription');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_ai_usage',
+    'What the AI side of the workspace has cost this month, against the spend cap if one is set. These are the same ' +
+      'figures the billing page reads, so the terminal and the web app cannot disagree. ' +
+      'Use it before starting anything expensive, when the user asks what their usage looks like, or if a paid operation ' +
+      'has stopped working for no obvious reason. ' +
+      '🚨 If a cap is set and usage is close to it, say so plainly. Work simply stops when a cap is reached, and finding ' +
+      'that out mid-task is far worse than being told in advance. Amounts are in cents. Read only.',
+    {},
+    async () => {
+      const r = await call('GET', '/setup/usage');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_list_integrations',
+    'Which third-party providers this workspace has connected: payments, email, calendar, lead sources and so on. ' +
+      'Use it before suggesting anything that depends on an integration, and when the user asks whether something is ' +
+      'hooked up. A feature that needs Stripe is not available on a workspace without Stripe, and finding that out by ' +
+      'trying is a bad experience you can avoid with one call. ' +
+      '🚨 This returns the NAMES of connected providers and never a credential value. There is no argument, no verbosity ' +
+      'and no other route that returns one. Do not ask the user to paste a key into the terminal either: connecting and ' +
+      'rotating providers happens in KM Hub at https://hub.kivimedia.co, where the secret stays. Read only.',
+    {},
+    async () => {
+      const r = await call('GET', '/setup/integrations');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_deliverability',
+    'Whether the mail this business sends is actually arriving: daily delivery, bounce and complaint figures over a ' +
+      'window. ' +
+      'Call it before recommending any outbound push, and whenever outreach or a newsletter is underperforming. ' +
+      '🚨 Deliverability is the quietest way a business loses money, because mail that never arrived looks exactly like ' +
+      'mail nobody answered, and every diagnosis downstream of that mistake is wrong. Rising bounces or complaints matter ' +
+      'more than a falling open rate: they put the sending domain itself at risk, which costs every future send and not ' +
+      'just this one. Raise it unprompted when you see it. ' +
+      'Domain setup and authentication live in KM Hub. Read only.',
+    {
+      days: z.number().int().min(1).max(90).optional().describe('How many days back. Default 30.'),
+    },
+    async ({ days }) => {
+      const r = await call('GET', `/setup/deliverability${qs({ days })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_workspace_config',
+    'How this workspace is shaped: the custom fields it records beyond the standard model, its holidays and whether each ' +
+      'blocks availability, and its email templates with their merge variables. ' +
+      '🚨 Read the custom fields before concluding a business does not track something. A workspace that records "room ' +
+      'layout" or "dietary notes" as a custom field is telling you what matters to it, and answering "KM Hub does not ' +
+      'store that" when it does is a bad and avoidable mistake. ' +
+      'A holiday with blocks_availability true is a date that genuinely is not bookable, which matters before offering ' +
+      'anybody a date. Template bodies are not returned: the list is for choosing one, and editing happens in KM Hub. ' +
+      'Read only.',
+    {},
+    async () => {
+      const r = await call('GET', '/setup/config');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_calendar_feed',
+    'Whether this workspace publishes its diary as a subscribable calendar feed, and when that was set up. ' +
+      'Use it when the user asks about syncing their calendar elsewhere. ' +
+      '🚨 The feed URL contains a private token and is NEVER returned here. Anybody holding it has a permanent ' +
+      'subscription to this diary, and it cannot be rotated without breaking every calendar already subscribed, so it is ' +
+      'not something to put in a terminal transcript. Point them at KM Hub to copy it. Read only.',
+    {},
+    async () => {
+      const r = await call('GET', '/setup/calendar-feed');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_sms_config',
+    'Whether SMS is switched on for this workspace, which provider it uses, whether credentials are configured, and the ' +
+      'number clients see. ' +
+      'Call it before suggesting anything that texts a client: a workspace with SMS off cannot send one, and finding that ' +
+      'out by trying wastes the user time. ' +
+      '🚨 Credential VALUES are never returned, only whether they are present. The sending number IS returned, ' +
+      'because it is the public identity clients already see on their phones. Read only.',
+    {},
+    async () => {
+      const r = await call('GET', '/setup/sms-config');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+}

package/tools/sops-bridges.mjs

@@ -0,0 +1,86 @@
+/**
+ * Tool family: sops-bridges - the SOP, delivered to the moment of the work.
+ *
+ * WHY THIS IS A SECOND FAMILY AND NOT MORE TOOLS IN sops.mjs
+ * The sops family is about the LIBRARY: writing procedures, publishing them,
+ * attaching them to things. These two tools are about a JOB. Somebody is about
+ * to load a truck for Saturday, and the only question they have is "what do I
+ * need to know before this one". km_sops_for can only answer that thing by
+ * thing; km_sop_brief answers it for the whole booking at once - the booking's
+ * own procedures plus the venue's, the event type's, every piece of gear's and
+ * every crew role's, deduplicated, critical steps first.
+ *
+ * That is the difference between KM Hub SOPs and the tool J&M cancelled after
+ * two days. GembaDocs holds the same 21-step warehouse procedure and cannot say
+ * which of its documents matter tonight, because it has never heard of the
+ * venue, the gear or the person driving the truck.
+ *
+ * WHAT IS DELIBERATELY NOT HERE
+ * The bridge resolve route (POST sops/bridge/resolve) has no tool. It exists so
+ * DJEP, the Zoho bridge and the SMPL bridge can ask by name when they do not
+ * know a KM Hub uuid. A model in this conversation always has the booking, so
+ * giving it a hint-matching tool would only invite it to guess a venue name
+ * when it could have passed an id. Bridges call that route directly.
+ *
+ * SAFETY. Both tools read. Nothing here sends, charges or changes anything.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'sops-bridges';
+
+export const TOOLS = ['km_sop_brief', 'km_sop_pullsheet'];
+
+// Empty, not ['*'] - see the note in sops.mjs. ['*'] pins a family into every
+// profile, which is the opposite of what this comment used to claim.
+export const PROFILES = [];
+
+export function register(server, call, { out, text }) {
+  server.tool(
+    'km_sop_brief',
+    'Everything somebody should read before working a specific booking: the SOPs attached to the booking itself, plus the ' +
+      'ones attached to its venue, its event type, every piece of gear on it, every crew role staffed on it, and the client. ' +
+      'Deduplicated, ordered so the critical procedures come first, with a flat list of every critical step across all of them. ' +
+      'REACH FOR THIS WHENEVER A JOB IS BEING PREPARED, BRIEFED OR TALKED THROUGH, and reach for it before you answer from ' +
+      'memory: a written procedure beats a good guess, and this is the only tool that finds every procedure that touches one ' +
+      'job in a single call. Worth running unprompted the day before an event - an SOP that exists and is not read is the same ' +
+      'as no SOP at all. ' +
+      'It also answers usefully when the answer is nothing: it names the venue, the gear and the roles that have no procedure ' +
+      'written for them, which is the list of what only lives in somebody\'s head. ' +
+      'Only PUBLISHED SOPs appear. A draft is somebody still thinking and an archived one is no longer how the work is done, ' +
+      'and putting either in front of a crew member carries the authority of a document it has not earned. Read only.',
+    {
+      booking_id: z.string()
+        .describe('The booking id, or the booking number people say out loud (for example JM-1042). Either works.'),
+    },
+    async ({ booking_id }) => out(await call('GET', `/sops/brief/${encodeURIComponent(booking_id)}`)),
+  );
+
+  server.tool(
+    'km_sop_pullsheet',
+    'The same job brief as km_sop_brief, rendered as a plain-text block to paste into a pull sheet, a production system or a ' +
+      'printed sheet taped to a road case. It carries the SOP reference numbers, titles, revisions, why each one applies, and ' +
+      'the CRITICAL STEPS ONLY - not the full procedure. ' +
+      'Reach for it when the user asks for something to paste, print, send to the crew, or add to a pull sheet or a DJEP ' +
+      'export, and when they want the short version rather than every step. ' +
+      'It is plain text on purpose: it lands in systems with no HTML, so hand it over exactly as it comes back rather than ' +
+      'reformatting it into a table. Use km_sop_brief instead when somebody needs to actually follow a procedure, because the ' +
+      'non-critical steps are the ones missing here. Read only.',
+    {
+      booking_id: z.string()
+        .describe('The booking id, or the booking number people say out loud. Either works.'),
+    },
+    async ({ booking_id }) => {
+      const r = await call('GET', `/sops/pullsheet/${encodeURIComponent(booking_id)}`);
+      // The block is the product, so it goes back as prose. Wrapped in JSON its
+      // line breaks arrive as the two characters backslash-n, and the thing a
+      // person is meant to paste stops being pasteable.
+      const block = r && r.ok && r.data && typeof r.data.text === 'string' ? r.data.text : '';
+      if (!block) return out(r);
+
+      const warnings = Array.isArray(r.data.warnings) ? r.data.warnings.filter(Boolean) : [];
+      return text(warnings.length ? `${block}\n\n${warnings.map((w) => `note: ${w}`).join('\n')}` : block);
+    },
+  );
+}

package/tools/sops.mjs

@@ -0,0 +1,314 @@
+/**
+ * Tool family: sops - the written-down version of how this business actually works.
+ *
+ * WHY THIS EXISTS
+ * J&M Events paid for GembaDocs and cancelled it two days later. The document
+ * half of that tool is easy; what neither GembaDocs nor Scribe can do is know
+ * what a job is. A GembaDocs SOP is a page somebody has to remember to go and
+ * find. Here, an SOP hangs off the venue, the gear, the event type or the crew
+ * role, so `km_sops_for` can answer "what do I need to know before this job"
+ * from the job itself.
+ *
+ * That is why km_sops_for exists and why it is the tool to reach for first.
+ *
+ * SAFETY. Nothing here sends, charges or moves anything. The one real gate is
+ * publishing: a draft is somebody thinking out loud, a published SOP is what a
+ * crew member on a loading dock will actually follow, and km_publish_sop is the
+ * line between them. That is why publishing refuses an SOP with no steps.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'sops';
+
+export const TOOLS = [
+  'km_sops_for',
+  'km_list_sops',
+  'km_get_sop',
+  'km_create_sop',
+  'km_update_sop',
+  'km_set_sop_steps',
+  'km_publish_sop',
+  'km_attach_sop',
+  'km_detach_sop',
+  'km_sop_images',
+  'km_set_sop_step_image',
+  'km_set_sop_step_video',
+  'km_delete_sop',
+];
+
+// Lands in `full` only, which is what an EMPTY list means here - not ['*'].
+//
+// tools.mjs is explicit about this and I got it wrong first time: a family the
+// PROFILES map has never PLACED falls through to its own declaration, and ['*']
+// opts into every profile. Measured: all 11 SOP tools landed in `core`, taking
+// it from 45 tools to 45 including a quarter that a caller asking for the
+// minimal set never wanted. The file's own header records six families making
+// exactly this mistake and calls the resulting split theatre.
+//
+// To put SOPs into a narrow profile deliberately, name the family in the
+// PROFILES map in tools.mjs. That is a decision, and it belongs there.
+export const PROFILES = [];
+
+// equipment_item is the real gear table; catalog_item is the legacy spelling
+// mig 673 shipped, kept valid so nothing already written breaks.
+const TARGET_TYPES = ['booking', 'gig', 'venue', 'equipment_item', 'catalog_item', 'event_type', 'crew_role', 'client'];
+
+const stepShape = z.object({
+  body: z.string().describe('What to DO, in one instruction. Keep it under about 120 characters where you can - it prints beside a photo.'),
+  title: z.string().optional().describe('Optional short heading for the step.'),
+  reasons_why: z.string().optional()
+    .describe('WHY the step matters, kept separate from the instruction on purpose. This is where "the warehouse never sees it if it is not written here" goes.'),
+  is_critical: z.boolean().optional()
+    .describe('True when getting this step wrong costs money, damages gear, or reaches a client. It prints as a warning triangle. Use it sparingly - three flags in a twelve-step SOP still mean something, ten do not.'),
+  is_text_only: z.boolean().optional()
+    .describe('True when the step deliberately has no picture. Defaults to true automatically when there is no image_path, so the PDF never prints an empty frame.'),
+  image_path: z.string().optional().describe('Storage path in the org-sop-images bucket, if this step has a photograph.'),
+  video_path: z.string().optional().describe('R2 key (kmsop/<org>/<uuid>.mp4) of the clip on this step, as returned by km_set_sop_step_video. Clips live on Cloudflare R2, not Supabase storage.'),
+  video_alt: z.string().optional().describe('What the clip shows. Printed as the caption of the video link on every PDF style.'),
+  image_alt: z.string().optional().describe('What the photograph shows, for anyone who cannot see it.'),
+  capture_meta: z.record(z.unknown()).optional()
+    .describe('Provenance when a browser capture wrote this step: {url, selector, click, viewport, captured_at}. Lets the step be re-captured when the screen it describes moves.'),
+});
+
+export function register(server, call, { out }) {
+  // ── the one that justifies the whole family ─────────────────────────────
+  server.tool(
+    'km_sops_for',
+    'Every published SOP attached to a specific thing: a booking, a venue, a piece of gear, an event type or a crew role. ' +
+      'THIS IS THE TOOL TO REACH FOR FIRST. It answers "what does somebody need to know before doing this job" from the job ' +
+      'itself, which is the whole reason SOPs live in KM Hub rather than in a separate documents app nobody opens. ' +
+      'Reach for it when a booking is being prepared, when crew are being briefed, when somebody asks how a venue is loaded in, ' +
+      'or when a piece of equipment is going out and you want the setup procedure for it. ' +
+      'Worth running unprompted before a job: an SOP that exists and is not read is the same as no SOP. ' +
+      'Draft SOPs are deliberately excluded - a draft is not guidance yet. Read only.',
+    {
+      target_type: z.enum(TARGET_TYPES).describe('What kind of thing you are asking about.'),
+      target_id: z.string().describe('The id of that booking, venue, gear item, event type or role.'),
+    },
+    async ({ target_type, target_id }) =>
+      out(await call('GET', `/sops/for/${encodeURIComponent(target_type)}/${encodeURIComponent(target_id)}`)),
+  );
+
+  server.tool(
+    'km_list_sops',
+    'The SOP library for this workspace: reference number, title, folder, status and revision. ' +
+      'Reach for it when the user asks what procedures exist, what is documented, or wants to find an SOP by name. ' +
+      'An empty library is worth saying out loud - it means every process in the business lives only in somebody\'s head, ' +
+      'and the answer to "what happens when that person is away" is nothing. ' +
+      'Filter by status to separate what is actually in use from what is still being written. Read only.',
+    {
+      status: z.enum(['draft', 'published', 'archived']).optional()
+        .describe('published = in use. draft = being written and NOT yet guidance. archived = kept for history.'),
+      folder: z.string().optional().describe('Only SOPs filed in this folder or any folder nested under it, e.g. "Operations" also returns "Operations/Equipment".'),
+      tag: z.string().optional().describe('Only SOPs carrying this tag.'),
+      q: z.string().optional().describe('Free text against title and summary.'),
+    },
+    async (args) => {
+      const p = new URLSearchParams();
+      for (const [k, v] of Object.entries(args)) if (v) p.set(k, String(v));
+      const qs = p.toString();
+      return out(await call('GET', `/sops${qs ? `?${qs}` : ''}`));
+    },
+  );
+
+  server.tool(
+    'km_get_sop',
+    'One SOP in full: every step in order with its reasons-why, which steps are flagged critical, and what the SOP is ' +
+      'attached to. Reach for it before editing an SOP, when somebody asks how a specific job is done, or when you are about ' +
+      'to answer a question that a written procedure already answers better than you can. Read only.',
+    { sop_id: z.string().describe('The SOP id from km_list_sops or km_sops_for.') },
+    async ({ sop_id }) => out(await call('GET', `/sops/${encodeURIComponent(sop_id)}`)),
+  );
+
+  // ── writing ─────────────────────────────────────────────────────────────
+  server.tool(
+    'km_create_sop',
+    'Write a new SOP, steps and all. It is created as a DRAFT and is not guidance until km_publish_sop runs, so this is safe ' +
+      'to use while still working the wording out. ' +
+      'Reach for it when the user describes how something is done and it is worth keeping, when a call transcript contains a ' +
+      'procedure, or when a process was just worked out and would otherwise be lost. ' +
+      'Write steps the way somebody standing in a warehouse reads them: one action each, present tense, the thing to do first. ' +
+      'Put the reason in reasons_why rather than folding it into the instruction - a step that explains itself mid-sentence ' +
+      'is a step nobody finishes. Flag a step critical only when getting it wrong costs money or reaches a client.',
+    {
+      title: z.string().describe('What this procedure is called. It is what people search for, so name it after the job, not the tool.'),
+      summary: z.string().optional().describe('One line on when this SOP applies.'),
+      folder: z.string().optional().describe('Folder path. Nest with "/" (or ">"), e.g. "Operations/Processes" or "Operations/Equipment".'),
+      tags: z.array(z.string()).optional().describe('Free tags, e.g. ["audio", "load-in"]. Stored lower case, de-duplicated, max 20.'),
+      is_critical: z.boolean().optional().describe('True when the whole procedure is safety or money critical.'),
+      source: z.enum(['manual', 'capture', 'import', 'mobile']).optional()
+        .describe('Where the steps came from. "capture" means a browser extension wrote them; "mobile" means somebody photographed real work.'),
+      steps: z.array(stepShape).optional().describe('The steps, in order. You can create the SOP empty and add them later.'),
+    },
+    async (args) => out(await call('POST', '/sops', args)),
+  );
+
+  server.tool(
+    'km_update_sop',
+    'Change an SOP\'s title, summary, folder, tags, status or whole-SOP critical flag. tags REPLACES the whole tag list: ' +
+      'read the current tags with km_get_sop and send them back with your change. Does not touch the steps - use ' +
+      'km_set_sop_steps for those. Reach for it to refile, rename, or archive a procedure that is no longer how the work is done.',
+    {
+      sop_id: z.string(),
+      title: z.string().optional(),
+      summary: z.string().optional(),
+      folder: z.string().optional().describe('Folder path, nested with "/", e.g. "Operations/Equipment". Empty string unfiles it.'),
+      tags: z.array(z.string()).optional().describe('The COMPLETE tag list. An empty array removes every tag.'),
+      status: z.enum(['draft', 'published', 'archived']).optional(),
+      is_critical: z.boolean().optional(),
+    },
+    async ({ sop_id, ...patch }) => out(await call('PATCH', `/sops/${encodeURIComponent(sop_id)}`, patch)),
+  );
+
+  server.tool(
+    'km_set_sop_steps',
+    'Replace the entire step list of an SOP with the list you pass. ' +
+      '🚨 THIS IS A REPLACE, NOT AN APPEND. Whatever is there now is deleted and what you send becomes the SOP. Read the ' +
+      'current steps with km_get_sop first and send them back with your changes included, or you will silently delete work ' +
+      'somebody else wrote. Steps are renumbered from 1 in the order you send them.',
+    {
+      sop_id: z.string(),
+      steps: z.array(stepShape).describe('The COMPLETE step list, in order. An empty array deletes every step.'),
+    },
+    async ({ sop_id, steps }) => out(await call('PUT', `/sops/${encodeURIComponent(sop_id)}/steps`, { steps })),
+  );
+
+  server.tool(
+    'km_publish_sop',
+    'Publish an SOP and freeze the current version into its revision history. ' +
+      'This is the line between a draft somebody is still thinking about and a document a crew member on a loading dock will ' +
+      'follow, so treat it as a real decision rather than a save button. Confirm with the user before publishing something ' +
+      'you wrote yourself. ' +
+      'The frozen snapshot is the audit trail: it can be read back even after the live steps move on, which is what makes the ' +
+      'revision number mean anything. Publishing an SOP with no steps is refused. ' +
+      'Say what changed in changes_detail - a revision history with no reasons in it is just a list of dates.',
+    {
+      sop_id: z.string(),
+      changes_detail: z.string().optional().describe('What changed and why, for the revision history.'),
+      revision_bump: z.enum(['minor', 'major']).optional()
+        .describe('minor (default) moves 1.000 to 1.001 - wording, a clearer photo. major moves 1.000 to 2.000 - the procedure itself changed and anyone trained on the old one needs telling.'),
+    },
+    async ({ sop_id, ...body }) => out(await call('POST', `/sops/${encodeURIComponent(sop_id)}/publish`, body)),
+  );
+
+  // ── the link that makes an SOP findable ─────────────────────────────────
+  server.tool(
+    'km_attach_sop',
+    'Attach an SOP to a booking, venue, piece of gear, event type or crew role, so it surfaces automatically whenever ' +
+      'somebody is working on that thing. ' +
+      'This is what stops a good procedure from being a document nobody opens. Reach for it every time you write an SOP: an ' +
+      'unattached SOP is only findable by someone who already knows it exists. ' +
+      'A venue load-in procedure belongs on the venue. A projector setup belongs on the gear item. A prep process belongs on ' +
+      'the event type. Attaching the same SOP to the same thing twice is harmless.',
+    {
+      sop_id: z.string(),
+      target_type: z.enum(TARGET_TYPES),
+      target_id: z.string().describe('The id of the booking, venue, gear item, event type or role.'),
+      note: z.string().optional().describe('Why this SOP is on this thing, e.g. "ballroom only, not the terrace".'),
+    },
+    async ({ sop_id, ...body }) => out(await call('POST', `/sops/${encodeURIComponent(sop_id)}/links`, body)),
+  );
+
+  server.tool(
+    'km_detach_sop',
+    'Take an SOP back off a booking, venue, gear item, event type or role. The SOP itself is untouched - this only stops it ' +
+      'appearing against that one thing.',
+    {
+      sop_id: z.string(),
+      target_type: z.enum(TARGET_TYPES),
+      target_id: z.string(),
+    },
+    async ({ sop_id, target_type, target_id }) => {
+      const p = new URLSearchParams({ target_type, target_id });
+      return out(await call('DELETE', `/sops/${encodeURIComponent(sop_id)}/links?${p.toString()}`));
+    },
+  );
+  // ── the photographs ─────────────────────────────────────────────────────
+  server.tool(
+    'km_sop_images',
+    'Look at the photographs on an SOP. Returns a short-lived link per step, plus the instruction that goes with it. ' +
+      'REACH FOR THIS WHENEVER THE PICTURES MATTER, which is most of the time: an SOP is half words and half "the screen ' +
+      'looks like THIS", and every other tool here hands back a storage path in a private bucket that cannot be opened. ' +
+      'Use it to check a captured SOP actually shows what it claims, to write image_alt text for steps that have none, ' +
+      'or to answer a question about what a screen looks like. ' +
+      'A step reported as missing_bytes has an image recorded whose file is gone from the bucket, which is worth saying ' +
+      'out loud rather than treating as a step with no picture. The links expire, so fetch them when you need them ' +
+      'rather than storing them. Read only.',
+    { sop_id: z.string().describe('The SOP id from km_list_sops, km_get_sop or km_sops_for.') },
+    async ({ sop_id }) => out(await call('GET', `/sops/${encodeURIComponent(sop_id)}/images`)),
+  );
+
+  server.tool(
+    'km_set_sop_step_image',
+    'Put a photograph on a step. This is what turns an SOP from a description into something somebody can follow: ' +
+      '"the cable goes in THIS port" cannot be written, only shown. ' +
+      'Reach for it when a step is about what something looks like, when km_sop_images reports a step with no picture ' +
+      'that clearly needs one, or when replacing a photograph of a screen that has since changed. ' +
+      'PREFER image_url. A photograph is megabytes; sending it as base64 through this tool means pushing all of it ' +
+      'through the conversation, which is slow and often refused outright. Give the server a public https URL and it ' +
+      'fetches the picture itself. Use image_base64 only for something genuinely small. ' +
+      'Re-sending replaces that step\'s photograph rather than adding a second one, so a retry is safe. ' +
+      'Write image_alt every time: it is what somebody who cannot see the picture gets, and it is the only part of a ' +
+      'photograph that survives into a text brief.',
+    {
+      sop_id: z.string(),
+      step_no: z.number().int().positive().describe('Which step, counting from 1, as km_get_sop numbers them.'),
+      image_url: z.string().optional()
+        .describe('Public https URL for the server to fetch. Not a private address, and it must not redirect.'),
+      image_base64: z.string().optional()
+        .describe('The raw bytes, base64. Only for small images - prefer image_url.'),
+      image_alt: z.string().optional().describe('What the photograph shows, for anyone who cannot see it.'),
+    },
+    async ({ sop_id, step_no, ...body }) =>
+      out(await call('POST', `/sops/${encodeURIComponent(sop_id)}/steps/${step_no}/image`, body)),
+  );
+
+  server.tool(
+    'km_set_sop_step_video',
+    'Put a video clip on a step, or take it off. Clips live on Cloudflare R2 and the bytes never pass through this ' +
+      'tool: call it with mime and size to get a presigned upload_url, PUT the file there (any HTTP client, ' +
+      'Content-Type = the mime), then call again with the returned path to attach it. Pass remove:true to clear a ' +
+      'clip. MP4, MOV or WebM, 500MB max. Write video_alt: it is the caption printed beside the link on the PDF.',
+    {
+      sop_id: z.string(),
+      step_no: z.number().int().positive().describe('Which step, counting from 1.'),
+      mime: z.string().optional().describe('video/mp4, video/quicktime or video/webm - to request an upload_url.'),
+      size: z.number().int().positive().optional().describe('File size in bytes - with mime.'),
+      path: z.string().optional().describe('The path from the first call, once the PUT succeeded - to attach.'),
+      video_alt: z.string().optional().describe('What the clip shows.'),
+      remove: z.boolean().optional().describe('true to clear the clip from the step.'),
+    },
+    async ({ sop_id, step_no, ...body }) =>
+      out(await call('POST', `/sops/${encodeURIComponent(sop_id)}/steps/${step_no}/video`, body)),
+  );
+
+  // ── the one that does not come back ─────────────────────────────────────
+  server.tool(
+    'km_delete_sop',
+    'Permanently delete an SOP: every step, every photograph, every attachment and its whole revision history. ' +
+      'NOTHING HERE COMES BACK, and the revision history is the audit trail of how the procedure changed, so deleting it ' +
+      'destroys more than the current version. ' +
+      'ARCHIVING IS ALMOST ALWAYS THE RIGHT ANSWER INSTEAD: km_update_sop with status "archived" keeps the SOP readable ' +
+      'and stops it being offered as guidance, which is what somebody usually means by "get rid of it". Reach for delete ' +
+      'only for something created by mistake, a duplicate, or a test. ' +
+      'Confirm with the user first, in their own words, and pass confirm_reference_no to prove you read the right SOP. ' +
+      'There are TWO gates and both are deliberate: confirm_reference_no proves you looked at the right SOP, and KM Hub ' +
+      'separately answers 409 with a confirmation sentence and a confirm_token. SHOW THAT SENTENCE TO THE USER, wait for ' +
+      'an explicit yes, then retry ONCE with the exact token and otherwise identical arguments. The token is bound to ' +
+      'those arguments, so changing anything on the retry invalidates it and you start again, which is the point.',
+    {
+      sop_id: z.string(),
+      confirm_reference_no: z.number().int()
+        .describe('The reference number of the SOP you intend to destroy, from km_get_sop. It must match, which is the point: it proves you looked at the one you are deleting. Send it on the FIRST call, not only the retry, or the token will be bound to a different set of arguments.'),
+      confirm_token: z.string().optional()
+        .describe('Use only the exact token KM Hub returned in its 409, and only after the user has explicitly approved the sentence that came with it.'),
+    },
+    async ({ sop_id, confirm_reference_no, confirm_token }) =>
+      out(await call('DELETE', `/sops/${encodeURIComponent(sop_id)}`, {
+        confirm_reference_no,
+        ...(confirm_token ? { confirm_token } : {}),
+      })),
+  );
+}