@kivimedia/kmhub 2.9.0 → 2.10.0

package/tools/schedules.mjs

@@ -1,55 +1,55 @@
-/**
- * Tool family: schedules - what runs on its own, and whether it actually is.
- *
- * Workstream D, the half that is safe today. D1's writing scheduler was rejected by
- * three independent reviews against the B8 write policy: a scheduled run composes
- * its request body fresh at run time, so no confirm token can exist for it in
- * advance, and "scheduling is the consent" can only be built as a branch that skips
- * verification entirely.
- *
- * 🚨 What ships is the thing whose ABSENCE is dangerous. A recurring job that fails
- * past its retry limit is set failed and nothing re-queues it and nothing reports
- * it. The schedule is dead permanently and the client finds out weeks later. Worse,
- * "ran and found nothing" and "has not run since April" look identical from the
- * outside. This makes them distinguishable.
- *
- * The family contract this file follows is documented in ./README.md.
- */
-export const FAMILY = 'schedules';
-
-export const TOOLS = ['km_list_schedules'];
-
-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 scheduling to the terminal yet. That is not a fault: the workspace is fine and every ' +
-  'other tool works as normal. Recurring work is configured in the web app at https://hub.kivimedia.co.';
-
-export function register(server, call, { out, text }) {
-  server.tool(
-    'km_list_schedules',
-    'Everything in this workspace set to run on its own - the morning sweep, sequence sweeps, scheduled actions and ' +
-      'the rest - with when each is next due, when it last finished, and whether it is actually healthy. ' +
-      'Call it whenever the user asks what runs automatically, why something stopped arriving, or whether anything ' +
-      'is set up. Also call it before telling anybody that nothing happens on its own here. ' +
-      '🚨 LEAD WITH `problems`, and specifically with `dead_and_will_not_retry`. A recurring job that failed past its ' +
-      'retry limit is stopped PERMANENTLY: nothing re-queues it and no other screen in the product mentions it. The ' +
-      'client will not discover it on their own, because a schedule that silently stopped looks exactly like a quiet ' +
-      'week. Telling them is often the single most valuable thing in a session. ' +
-      '🚨 `overdue_hours` above about a day usually means the WORKER is not running, not that the schedule is wrong. ' +
-      'Say which you think it is rather than reporting a number and moving on. ' +
-      'Nothing here creates, pauses, restarts or runs a schedule. That happens in KM Hub, deliberately: a scheduled ' +
-      'run acts with nobody present, so it cannot give the confirmation that a money-spending or client-visible ' +
-      'action requires. Read only.',
-    {},
-    async () => {
-      const r = await call('GET', '/schedules');
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-}
+/**
+ * Tool family: schedules - what runs on its own, and whether it actually is.
+ *
+ * Workstream D, the half that is safe today. D1's writing scheduler was rejected by
+ * three independent reviews against the B8 write policy: a scheduled run composes
+ * its request body fresh at run time, so no confirm token can exist for it in
+ * advance, and "scheduling is the consent" can only be built as a branch that skips
+ * verification entirely.
+ *
+ * 🚨 What ships is the thing whose ABSENCE is dangerous. A recurring job that fails
+ * past its retry limit is set failed and nothing re-queues it and nothing reports
+ * it. The schedule is dead permanently and the client finds out weeks later. Worse,
+ * "ran and found nothing" and "has not run since April" look identical from the
+ * outside. This makes them distinguishable.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+export const FAMILY = 'schedules';
+
+export const TOOLS = ['km_list_schedules'];
+
+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 scheduling to the terminal yet. That is not a fault: the workspace is fine and every ' +
+  'other tool works as normal. Recurring work is configured in the web app at https://hub.kivimedia.co.';
+
+export function register(server, call, { out, text }) {
+  server.tool(
+    'km_list_schedules',
+    'Everything in this workspace set to run on its own - the morning sweep, sequence sweeps, scheduled actions and ' +
+      'the rest - with when each is next due, when it last finished, and whether it is actually healthy. ' +
+      'Call it whenever the user asks what runs automatically, why something stopped arriving, or whether anything ' +
+      'is set up. Also call it before telling anybody that nothing happens on its own here. ' +
+      '🚨 LEAD WITH `problems`, and specifically with `dead_and_will_not_retry`. A recurring job that failed past its ' +
+      'retry limit is stopped PERMANENTLY: nothing re-queues it and no other screen in the product mentions it. The ' +
+      'client will not discover it on their own, because a schedule that silently stopped looks exactly like a quiet ' +
+      'week. Telling them is often the single most valuable thing in a session. ' +
+      '🚨 `overdue_hours` above about a day usually means the WORKER is not running, not that the schedule is wrong. ' +
+      'Say which you think it is rather than reporting a number and moving on. ' +
+      'Nothing here creates, pauses, restarts or runs a schedule. That happens in KM Hub, deliberately: a scheduled ' +
+      'run acts with nobody present, so it cannot give the confirmation that a money-spending or client-visible ' +
+      'action requires. Read only.',
+    {},
+    async () => {
+      const r = await call('GET', '/schedules');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+}

package/tools/setup.mjs

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

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