@kivimedia/kmhub 2.9.1 → 2.10.0

package/tools/sops.mjs

@@ -1,314 +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 } : {}),
-      })),
-  );
-}
+/**
+ * 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 } : {}),
+      })),
+  );
+}