@kivimedia/kmhub 2.9.1 → 2.11.0

package/tools/catalog.mjs

@@ -1,288 +1,288 @@
-/**
- * Tool family: catalog - the public booking catalog tree, readable and editable.
- *
- * WHY THIS FAMILY EXISTS. On 01-Sep-2026 Mark Fuller asked his terminal to make a
- * package appear under a second booking pathway and rename it there. The terminal
- * read his whole catalog correctly and then had to hand him back to the mouse:
- * km_get_offers_and_pricing returned a flat list with nothing saying which pathway
- * each package sits under, and no tool could write a package at all. His written
- * gap report asked for the mapping read, a package edit, a way to place a package
- * on a pathway, the shared-or-copied design answer, and for every write to sit
- * behind the confirm gate. This family is that list, in that order.
- *
- * THE DESIGN ANSWER his report demanded: a package lives under exactly ONE
- * pathway (service_packages.pathway_id is a single reference, no join table).
- * "Appear under a second pathway" is a COPY; renaming a copy never touches the
- * original. The tools are named copy and move, not "attach", so the name cannot
- * imply a data model the schema does not have.
- *
- * 🚨 THE BOOKING PAGE IS THE SHOPFRONT, a page on the open internet. Every write
- * here is a confirmed write, same as form fields: KM Hub answers 409 with a plain
- * sentence naming the package and pathway, and nothing happens until the person
- * you are working with has said yes to that sentence.
- *
- * The family contract this file follows is documented in ./README.md.
- */
-import { z } from 'zod';
-
-export const FAMILY = 'catalog';
-
-export const TOOLS = [
-  'km_get_catalog', 'km_update_package', 'km_copy_package_to_pathway', 'km_move_package_to_pathway',
-  'km_create_package', 'km_delete_package', 'km_get_package_composition', 'km_set_package_composition',
-  'km_create_pathway', 'km_update_pathway',
-];
-
-// Lands in `full` only. An EMPTY list means exactly that - ['*'] would opt into
-// every profile, which is the mistake tools.mjs documents six families making.
-export const PROFILES = [];
-
-/** Route-level 404 (carries a routes list) vs a handler's not_found. See forms.mjs. */
-function routeMissing(r) {
-  if (r.status === 405 || r.status === 501) return true;
-  return r.status === 404 && Array.isArray(r.data?.routes);
-}
-
-const NOT_SUPPORTED =
-  'This KM Hub is running a version that cannot read or edit the booking catalog tree from the terminal yet. The ' +
-  'workspace is fine and every other tool works as normal. The catalog is editable in the web app at ' +
-  'https://hub.kivimedia.co under Operations then Booking Catalogs.';
-
-const CONFIRM_DESC =
-  'Leave this out on the first call. This action changes the public booking page, so it needs an explicit yes from '
-  + 'the person you are working with: KM Hub answers 409 with a plain description of exactly what would change, plus '
-  + 'a token. Show them that description in those words, wait for a real answer, and only then call again with the '
-  + 'token and the SAME arguments. A yes for one change never authorises a different one.';
-
-export function register(server, call, { out, text }) {
-  server.tool(
-    'km_get_catalog',
-    'The booking catalog the way a buyer sees it: pathways in display order, and which packages sit under each, ' +
-      'with price, duration, order and published state. This is the ONLY tool that shows the pathway-to-package ' +
-      'mapping, so reach for it before describing, editing, copying or moving anything on the public booking page; ' +
-      'the ids every write tool here needs come from it. ' +
-      'THE MODEL, so you never have to guess: a package lives under exactly ONE pathway. To show one under a ' +
-      'second pathway you COPY it there (km_copy_package_to_pathway); renaming the copy never touches the ' +
-      'original. A buyer sees a package only when both it and its pathway are published. Read only.',
-    {
-      catalog_id: z.string().optional().describe('From km_list_catalogs. Leave it out for the default catalog, which is almost always the one you want.'),
-    },
-    async ({ catalog_id }) => {
-      const q = catalog_id ? `?catalog_id=${encodeURIComponent(String(catalog_id).trim())}` : '';
-      const r = await call('GET', `/catalogs/tree${q}`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_update_package',
-    'Edit one package on the public booking catalog: rename it, change its price or duration, edit its ' +
-      'description or badge, publish or unpublish it, or change its position in the pathway ' +
-      '(booking_display_seq, lowest first, which is also how you reorder). ' +
-      'Run km_get_catalog first and work from real ids. Send only the fields you are changing. ' +
-      'Prices are CENTS: base_price_cents 25000 is $250. The legacy proposal price is kept in step ' +
-      'automatically, so never try to set starting_price yourself. ' +
-      '🚨 booking_status is the PUBLIC switch: published means buyers see it on the booking page the moment you ' +
-      'save. This is a confirmed write; expect a 409 naming the package first.',
-    {
-      package_id: z.string().describe('UUID of the package, from km_get_catalog.'),
-      name: z.string().min(1).max(200).optional().describe('The name buyers read.'),
-      description: z.string().max(2000).nullable().optional().describe('Send null to clear it.'),
-      base_price_cents: z.number().int().min(0).nullable().optional().describe('The price the booking form charges, in cents. Null clears it.'),
-      duration_mins: z.number().int().min(0).nullable().optional(),
-      badge_text: z.string().max(200).nullable().optional().describe('The small badge on the package card, e.g. "Most popular". Null clears it.'),
-      per_child_pricing: z.boolean().optional().describe('True makes base_price_cents cover children_included children, with extras charged per child.'),
-      children_included: z.number().int().min(0).nullable().optional(),
-      price_per_extra_child_cents: z.number().int().min(0).nullable().optional(),
-      max_children: z.number().int().min(0).nullable().optional(),
-      booking_display_seq: z.number().int().min(0).optional().describe('Position inside its pathway, lowest first. Set these across siblings to reorder.'),
-      booking_status: z.enum(['draft', 'published']).optional().describe('published puts it on the public page. draft takes it off.'),
-      confirm_token: z.string().optional().describe(CONFIRM_DESC),
-    },
-    async ({ package_id, ...changes }) => {
-      const r = await call('PATCH', `/packages/${encodeURIComponent(String(package_id || '').trim())}`, changes);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_copy_package_to_pathway',
-    'Clone a package into another pathway, landing at the bottom of that pathway, with its add-on options and ' +
-      'choices copied along. This is HOW a package appears under a second pathway: a package lives under exactly ' +
-      'one, so a second appearance is a copy, and renaming the copy (new_name) never touches the original. ' +
-      'The copy keeps the original\'s booking_status, so copying a published package into a published pathway is ' +
-      'live immediately - the confirmation sentence says which you are getting. ' +
-      'After copying, edits to either one are separate: a price change on the original does NOT follow to the ' +
-      'copy, which is worth saying to the owner out loud. This is a confirmed write; expect a 409 first.',
-    {
-      package_id: z.string().describe('UUID of the package to copy, from km_get_catalog.'),
-      pathway_id: z.string().describe('UUID of the pathway to copy it into, from km_get_catalog.'),
-      new_name: z.string().min(1).max(200).optional().describe('What the copy is called. Leave it out to keep the same name.'),
-      confirm_token: z.string().optional().describe(CONFIRM_DESC),
-    },
-    async ({ package_id, ...body }) => {
-      const r = await call('POST', `/packages/${encodeURIComponent(String(package_id || '').trim())}/copy`, body);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_move_package_to_pathway',
-    'Move a package to a different pathway, landing at the bottom, optionally renaming it on the way. ' +
-      'It LEAVES its current pathway: a package lives under exactly one, so a move is a removal there and an ' +
-      'arrival here, in one step. When the owner wants it in BOTH places, use km_copy_package_to_pathway ' +
-      'instead. This is a confirmed write; expect a 409 naming both pathways first.',
-    {
-      package_id: z.string().describe('UUID of the package to move, from km_get_catalog.'),
-      pathway_id: z.string().describe('UUID of the destination pathway, from km_get_catalog.'),
-      new_name: z.string().min(1).max(200).optional().describe('Rename it as part of the move. Leave it out to keep the name.'),
-      confirm_token: z.string().optional().describe(CONFIRM_DESC),
-    },
-    async ({ package_id, ...body }) => {
-      const r = await call('POST', `/packages/${encodeURIComponent(String(package_id || '').trim())}/move`, body);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_create_pathway',
-    'Create a booking pathway: the CATEGORY that packages live under on the public booking page, like ' +
-      '"Birthday Parties" or "Monthly Subscriptions". Reach for this FIRST when building a booking page from ' +
-      'nothing, because km_create_package requires a pathway_id and a workspace that has never opened the ' +
-      'Catalog Builder has no pathway to give it - that is exactly the dead end this tool removes. ' +
-      'It is a DRAFT unless you say otherwise, so nothing reaches buyers by surprise. ' +
-      'catalog_id is optional: left out, it uses the workspace default catalog, and if the workspace has NO ' +
-      'catalog at all it creates one (Main Catalog) on the way, so this works on a completely empty workspace. ' +
-      'Run km_get_catalog afterwards to see the new pathway with its id, then create packages under it. ' +
-      'This is a confirmed write; expect a 409 naming the pathway and catalog first.',
-    {
-      name: z.string().min(1).max(200).describe('The category name buyers read, e.g. "Dazzling Decor Club".'),
-      catalog_id: z.string().optional().describe('From km_list_catalogs. Leave it out for the default catalog, which is almost always right - and which will be created if the workspace has none.'),
-      subtitle: z.string().max(300).nullable().optional().describe('The small line under the name on the booking page, e.g. "Billed monthly, 3-month minimum".'),
-      description: z.string().max(2000).nullable().optional(),
-      status: z.enum(['draft', 'published']).optional().describe('Leave it out for draft, the safe default. published puts the category on the public page - but buyers still see nothing under it until its packages are published too.'),
-      image_url: z.string().max(1000).nullable().optional().describe('An image for the category card. A public URL; this tool does not upload anything.'),
-      display_seq: z.number().int().min(0).optional().describe('Position among the pathways, lowest first. Leave it out to land at the bottom.'),
-      confirm_token: z.string().optional().describe(CONFIRM_DESC),
-    },
-    async (body) => {
-      const r = await call('POST', '/pathways', body);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_update_pathway',
-    'Edit one booking pathway (the category packages sit under): rename it, change its subtitle or description, ' +
-      'publish or unpublish it, or move its position among the pathways (display_seq, lowest first). ' +
-      'Run km_get_catalog first and work from real ids. Send only the fields you are changing. ' +
-      '🚨 status is the PUBLIC switch, and it is only HALF the switch: a buyer sees a package only when the ' +
-      'PACKAGE is published AND its pathway is published. Publishing a pathway whose packages are all drafts ' +
-      'shows buyers an empty category; unpublishing a pathway hides every package under it at once, however ' +
-      'published those packages are. The response says which of those you just did. ' +
-      'This is a confirmed write; expect a 409 naming the pathway first.',
-    {
-      pathway_id: z.string().describe('UUID of the pathway, from km_get_catalog.'),
-      name: z.string().min(1).max(200).optional().describe('The category name buyers read.'),
-      subtitle: z.string().max(300).nullable().optional().describe('The small line under the name. Send null to clear it.'),
-      description: z.string().max(2000).nullable().optional().describe('Send null to clear it.'),
-      status: z.enum(['draft', 'published']).optional().describe('published puts the category on the public page. draft takes it, and everything under it, off.'),
-      display_seq: z.number().int().min(0).optional().describe('Position among the pathways, lowest first. Set these across siblings to reorder.'),
-      confirm_token: z.string().optional().describe(CONFIRM_DESC),
-    },
-    async ({ pathway_id, ...changes }) => {
-      const r = await call('PATCH', `/pathways/${encodeURIComponent(String(pathway_id || '').trim())}`, changes);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_create_package',
-    'Create a new package on the public booking catalog, at the bottom of a pathway. It is a DRAFT unless you ' +
-      'say otherwise, so nothing reaches buyers by surprise. Run km_get_catalog first for the pathway id; if the ' +
-      'catalog is empty and there is no pathway to put this under, make one with km_create_pathway. ' +
-      'Price is CENTS: 36500 is $365; the legacy proposal price is kept in step automatically. ' +
-      'After creating, say what the package is MADE OF with km_set_package_composition - that is what lets ' +
-      'quotes offer it as editable service lines and shows the owner the discount they are giving. ' +
-      'This is a confirmed write; expect a 409 naming the package and pathway first.',
-    {
-      pathway_id: z.string().describe('UUID of the pathway it lives under, from km_get_catalog.'),
-      name: z.string().min(1).max(200).describe('The name buyers read.'),
-      base_price_cents: z.number().int().min(0).nullable().optional().describe('The price the booking form charges, in cents. Leave it out for no price yet.'),
-      description: z.string().max(2000).nullable().optional(),
-      booking_status: z.enum(['draft', 'published']).optional().describe('Leave it out for draft, the safe default. published shows it to buyers the moment the pathway is also published.'),
-      confirm_token: z.string().optional().describe(CONFIRM_DESC),
-    },
-    async (body) => {
-      const r = await call('POST', '/packages', body);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_delete_package',
-    'Delete a package from the booking catalog, permanently. Its composition links and add-on options are ' +
-      'deleted with it, and there is no undo - which is why unpublishing (km_update_package with ' +
-      "booking_status 'draft') is usually the better first move, and this tool is for packages that are truly " +
-      'wrong, duplicates, or test rows. If bookings or quotes reference the package the delete is refused, and ' +
-      'unpublishing is the answer. This is a confirmed write; expect a 409 naming the package first.',
-    {
-      package_id: z.string().describe('UUID of the package, from km_get_catalog.'),
-      confirm_token: z.string().optional().describe(CONFIRM_DESC),
-    },
-    async ({ package_id, ...body }) => {
-      const r = await call('DELETE', `/packages/${encodeURIComponent(String(package_id || '').trim())}`, body);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_get_package_composition',
-    'What a package is MADE OF: the services inside it with quantities, each priced LIVE off the rate card, ' +
-      'plus the parts total and the discount against the package price. A package is an assortment of services ' +
-      'the OWNER selected - "3 hours of Balloon Twisting + 1 x 30-minute Magic Show" - never everything on the ' +
-      'rate card. The response also carries available_services (the whole rate card with ids), so this one call ' +
-      'gives you everything km_set_package_composition needs. An empty composition is a fine state: the package ' +
-      'sells on its price alone. Read only.',
-    {
-      package_id: z.string().describe('UUID of the package, from km_get_catalog.'),
-    },
-    async ({ package_id }) => {
-      const r = await call('GET', `/packages/${encodeURIComponent(String(package_id || '').trim())}/composition`);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-
-  server.tool(
-    'km_set_package_composition',
-    'Set what a package is made of, in ONE call: the full list of services and how much of each. Whatever you ' +
-      'send REPLACES the current composition, so start from km_get_package_composition and send the complete ' +
-      'list, not just the change. quantity is in the service\'s own unit: a per-hour service with quantity 3 ' +
-      'means 3 hours; decimals like 1.5 are fine. An empty list clears the composition (the package keeps its ' +
-      'price and stays bookable). Composition never changes what a buyer pays - the package price stands; it is ' +
-      'what lets quotes explode a package into editable service lines and shows the owner the discount they are ' +
-      'giving off their own rates. This is a confirmed write; expect a 409 spelling the composition out first.',
-    {
-      package_id: z.string().describe('UUID of the package, from km_get_catalog.'),
-      services: z.array(z.object({
-        service_id: z.string().describe('UUID of a rate-card service, from available_services on km_get_package_composition.'),
-        quantity: z.number().gt(0).max(999).describe("How much of it, in the service's own unit. 3 on a per-hour service = 3 hours."),
-      })).max(50).describe('The COMPLETE composition. It replaces what is there. Empty array clears it.'),
-      confirm_token: z.string().optional().describe(CONFIRM_DESC),
-    },
-    async ({ package_id, ...body }) => {
-      const r = await call('PUT', `/packages/${encodeURIComponent(String(package_id || '').trim())}/composition`, body);
-      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
-      return out(r);
-    },
-  );
-}
+/**
+ * Tool family: catalog - the public booking catalog tree, readable and editable.
+ *
+ * WHY THIS FAMILY EXISTS. On 01-Sep-2026 Mark Fuller asked his terminal to make a
+ * package appear under a second booking pathway and rename it there. The terminal
+ * read his whole catalog correctly and then had to hand him back to the mouse:
+ * km_get_offers_and_pricing returned a flat list with nothing saying which pathway
+ * each package sits under, and no tool could write a package at all. His written
+ * gap report asked for the mapping read, a package edit, a way to place a package
+ * on a pathway, the shared-or-copied design answer, and for every write to sit
+ * behind the confirm gate. This family is that list, in that order.
+ *
+ * THE DESIGN ANSWER his report demanded: a package lives under exactly ONE
+ * pathway (service_packages.pathway_id is a single reference, no join table).
+ * "Appear under a second pathway" is a COPY; renaming a copy never touches the
+ * original. The tools are named copy and move, not "attach", so the name cannot
+ * imply a data model the schema does not have.
+ *
+ * 🚨 THE BOOKING PAGE IS THE SHOPFRONT, a page on the open internet. Every write
+ * here is a confirmed write, same as form fields: KM Hub answers 409 with a plain
+ * sentence naming the package and pathway, and nothing happens until the person
+ * you are working with has said yes to that sentence.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'catalog';
+
+export const TOOLS = [
+  'km_get_catalog', 'km_update_package', 'km_copy_package_to_pathway', 'km_move_package_to_pathway',
+  'km_create_package', 'km_delete_package', 'km_get_package_composition', 'km_set_package_composition',
+  'km_create_pathway', 'km_update_pathway',
+];
+
+// Lands in `full` only. An EMPTY list means exactly that - ['*'] would opt into
+// every profile, which is the mistake tools.mjs documents six families making.
+export const PROFILES = [];
+
+/** Route-level 404 (carries a routes list) vs a handler's not_found. See forms.mjs. */
+function routeMissing(r) {
+  if (r.status === 405 || r.status === 501) return true;
+  return r.status === 404 && Array.isArray(r.data?.routes);
+}
+
+const NOT_SUPPORTED =
+  'This KM Hub is running a version that cannot read or edit the booking catalog tree from the terminal yet. The ' +
+  'workspace is fine and every other tool works as normal. The catalog is editable in the web app at ' +
+  'https://hub.kivimedia.co under Operations then Booking Catalogs.';
+
+const CONFIRM_DESC =
+  'Leave this out on the first call. This action changes the public booking page, so it needs an explicit yes from '
+  + 'the person you are working with: KM Hub answers 409 with a plain description of exactly what would change, plus '
+  + 'a token. Show them that description in those words, wait for a real answer, and only then call again with the '
+  + 'token and the SAME arguments. A yes for one change never authorises a different one.';
+
+export function register(server, call, { out, text }) {
+  server.tool(
+    'km_get_catalog',
+    'The booking catalog the way a buyer sees it: pathways in display order, and which packages sit under each, ' +
+      'with price, duration, order and published state. This is the ONLY tool that shows the pathway-to-package ' +
+      'mapping, so reach for it before describing, editing, copying or moving anything on the public booking page; ' +
+      'the ids every write tool here needs come from it. ' +
+      'THE MODEL, so you never have to guess: a package lives under exactly ONE pathway. To show one under a ' +
+      'second pathway you COPY it there (km_copy_package_to_pathway); renaming the copy never touches the ' +
+      'original. A buyer sees a package only when both it and its pathway are published. Read only.',
+    {
+      catalog_id: z.string().optional().describe('From km_list_catalogs. Leave it out for the default catalog, which is almost always the one you want.'),
+    },
+    async ({ catalog_id }) => {
+      const q = catalog_id ? `?catalog_id=${encodeURIComponent(String(catalog_id).trim())}` : '';
+      const r = await call('GET', `/catalogs/tree${q}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_update_package',
+    'Edit one package on the public booking catalog: rename it, change its price or duration, edit its ' +
+      'description or badge, publish or unpublish it, or change its position in the pathway ' +
+      '(booking_display_seq, lowest first, which is also how you reorder). ' +
+      'Run km_get_catalog first and work from real ids. Send only the fields you are changing. ' +
+      'Prices are CENTS: base_price_cents 25000 is $250. The legacy proposal price is kept in step ' +
+      'automatically, so never try to set starting_price yourself. ' +
+      '🚨 booking_status is the PUBLIC switch: published means buyers see it on the booking page the moment you ' +
+      'save. This is a confirmed write; expect a 409 naming the package first.',
+    {
+      package_id: z.string().describe('UUID of the package, from km_get_catalog.'),
+      name: z.string().min(1).max(200).optional().describe('The name buyers read.'),
+      description: z.string().max(2000).nullable().optional().describe('Send null to clear it.'),
+      base_price_cents: z.number().int().min(0).nullable().optional().describe('The price the booking form charges, in cents. Null clears it.'),
+      duration_mins: z.number().int().min(0).nullable().optional(),
+      badge_text: z.string().max(200).nullable().optional().describe('The small badge on the package card, e.g. "Most popular". Null clears it.'),
+      per_child_pricing: z.boolean().optional().describe('True makes base_price_cents cover children_included children, with extras charged per child.'),
+      children_included: z.number().int().min(0).nullable().optional(),
+      price_per_extra_child_cents: z.number().int().min(0).nullable().optional(),
+      max_children: z.number().int().min(0).nullable().optional(),
+      booking_display_seq: z.number().int().min(0).optional().describe('Position inside its pathway, lowest first. Set these across siblings to reorder.'),
+      booking_status: z.enum(['draft', 'published']).optional().describe('published puts it on the public page. draft takes it off.'),
+      confirm_token: z.string().optional().describe(CONFIRM_DESC),
+    },
+    async ({ package_id, ...changes }) => {
+      const r = await call('PATCH', `/packages/${encodeURIComponent(String(package_id || '').trim())}`, changes);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_copy_package_to_pathway',
+    'Clone a package into another pathway, landing at the bottom of that pathway, with its add-on options and ' +
+      'choices copied along. This is HOW a package appears under a second pathway: a package lives under exactly ' +
+      'one, so a second appearance is a copy, and renaming the copy (new_name) never touches the original. ' +
+      'The copy keeps the original\'s booking_status, so copying a published package into a published pathway is ' +
+      'live immediately - the confirmation sentence says which you are getting. ' +
+      'After copying, edits to either one are separate: a price change on the original does NOT follow to the ' +
+      'copy, which is worth saying to the owner out loud. This is a confirmed write; expect a 409 first.',
+    {
+      package_id: z.string().describe('UUID of the package to copy, from km_get_catalog.'),
+      pathway_id: z.string().describe('UUID of the pathway to copy it into, from km_get_catalog.'),
+      new_name: z.string().min(1).max(200).optional().describe('What the copy is called. Leave it out to keep the same name.'),
+      confirm_token: z.string().optional().describe(CONFIRM_DESC),
+    },
+    async ({ package_id, ...body }) => {
+      const r = await call('POST', `/packages/${encodeURIComponent(String(package_id || '').trim())}/copy`, body);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_move_package_to_pathway',
+    'Move a package to a different pathway, landing at the bottom, optionally renaming it on the way. ' +
+      'It LEAVES its current pathway: a package lives under exactly one, so a move is a removal there and an ' +
+      'arrival here, in one step. When the owner wants it in BOTH places, use km_copy_package_to_pathway ' +
+      'instead. This is a confirmed write; expect a 409 naming both pathways first.',
+    {
+      package_id: z.string().describe('UUID of the package to move, from km_get_catalog.'),
+      pathway_id: z.string().describe('UUID of the destination pathway, from km_get_catalog.'),
+      new_name: z.string().min(1).max(200).optional().describe('Rename it as part of the move. Leave it out to keep the name.'),
+      confirm_token: z.string().optional().describe(CONFIRM_DESC),
+    },
+    async ({ package_id, ...body }) => {
+      const r = await call('POST', `/packages/${encodeURIComponent(String(package_id || '').trim())}/move`, body);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_create_pathway',
+    'Create a booking pathway: the CATEGORY that packages live under on the public booking page, like ' +
+      '"Birthday Parties" or "Monthly Subscriptions". Reach for this FIRST when building a booking page from ' +
+      'nothing, because km_create_package requires a pathway_id and a workspace that has never opened the ' +
+      'Catalog Builder has no pathway to give it - that is exactly the dead end this tool removes. ' +
+      'It is a DRAFT unless you say otherwise, so nothing reaches buyers by surprise. ' +
+      'catalog_id is optional: left out, it uses the workspace default catalog, and if the workspace has NO ' +
+      'catalog at all it creates one (Main Catalog) on the way, so this works on a completely empty workspace. ' +
+      'Run km_get_catalog afterwards to see the new pathway with its id, then create packages under it. ' +
+      'This is a confirmed write; expect a 409 naming the pathway and catalog first.',
+    {
+      name: z.string().min(1).max(200).describe('The category name buyers read, e.g. "Dazzling Decor Club".'),
+      catalog_id: z.string().optional().describe('From km_list_catalogs. Leave it out for the default catalog, which is almost always right - and which will be created if the workspace has none.'),
+      subtitle: z.string().max(300).nullable().optional().describe('The small line under the name on the booking page, e.g. "Billed monthly, 3-month minimum".'),
+      description: z.string().max(2000).nullable().optional(),
+      status: z.enum(['draft', 'published']).optional().describe('Leave it out for draft, the safe default. published puts the category on the public page - but buyers still see nothing under it until its packages are published too.'),
+      image_url: z.string().max(1000).nullable().optional().describe('An image for the category card. A public URL; this tool does not upload anything.'),
+      display_seq: z.number().int().min(0).optional().describe('Position among the pathways, lowest first. Leave it out to land at the bottom.'),
+      confirm_token: z.string().optional().describe(CONFIRM_DESC),
+    },
+    async (body) => {
+      const r = await call('POST', '/pathways', body);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_update_pathway',
+    'Edit one booking pathway (the category packages sit under): rename it, change its subtitle or description, ' +
+      'publish or unpublish it, or move its position among the pathways (display_seq, lowest first). ' +
+      'Run km_get_catalog first and work from real ids. Send only the fields you are changing. ' +
+      '🚨 status is the PUBLIC switch, and it is only HALF the switch: a buyer sees a package only when the ' +
+      'PACKAGE is published AND its pathway is published. Publishing a pathway whose packages are all drafts ' +
+      'shows buyers an empty category; unpublishing a pathway hides every package under it at once, however ' +
+      'published those packages are. The response says which of those you just did. ' +
+      'This is a confirmed write; expect a 409 naming the pathway first.',
+    {
+      pathway_id: z.string().describe('UUID of the pathway, from km_get_catalog.'),
+      name: z.string().min(1).max(200).optional().describe('The category name buyers read.'),
+      subtitle: z.string().max(300).nullable().optional().describe('The small line under the name. Send null to clear it.'),
+      description: z.string().max(2000).nullable().optional().describe('Send null to clear it.'),
+      status: z.enum(['draft', 'published']).optional().describe('published puts the category on the public page. draft takes it, and everything under it, off.'),
+      display_seq: z.number().int().min(0).optional().describe('Position among the pathways, lowest first. Set these across siblings to reorder.'),
+      confirm_token: z.string().optional().describe(CONFIRM_DESC),
+    },
+    async ({ pathway_id, ...changes }) => {
+      const r = await call('PATCH', `/pathways/${encodeURIComponent(String(pathway_id || '').trim())}`, changes);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_create_package',
+    'Create a new package on the public booking catalog, at the bottom of a pathway. It is a DRAFT unless you ' +
+      'say otherwise, so nothing reaches buyers by surprise. Run km_get_catalog first for the pathway id; if the ' +
+      'catalog is empty and there is no pathway to put this under, make one with km_create_pathway. ' +
+      'Price is CENTS: 36500 is $365; the legacy proposal price is kept in step automatically. ' +
+      'After creating, say what the package is MADE OF with km_set_package_composition - that is what lets ' +
+      'quotes offer it as editable service lines and shows the owner the discount they are giving. ' +
+      'This is a confirmed write; expect a 409 naming the package and pathway first.',
+    {
+      pathway_id: z.string().describe('UUID of the pathway it lives under, from km_get_catalog.'),
+      name: z.string().min(1).max(200).describe('The name buyers read.'),
+      base_price_cents: z.number().int().min(0).nullable().optional().describe('The price the booking form charges, in cents. Leave it out for no price yet.'),
+      description: z.string().max(2000).nullable().optional(),
+      booking_status: z.enum(['draft', 'published']).optional().describe('Leave it out for draft, the safe default. published shows it to buyers the moment the pathway is also published.'),
+      confirm_token: z.string().optional().describe(CONFIRM_DESC),
+    },
+    async (body) => {
+      const r = await call('POST', '/packages', body);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_delete_package',
+    'Delete a package from the booking catalog, permanently. Its composition links and add-on options are ' +
+      'deleted with it, and there is no undo - which is why unpublishing (km_update_package with ' +
+      "booking_status 'draft') is usually the better first move, and this tool is for packages that are truly " +
+      'wrong, duplicates, or test rows. If bookings or quotes reference the package the delete is refused, and ' +
+      'unpublishing is the answer. This is a confirmed write; expect a 409 naming the package first.',
+    {
+      package_id: z.string().describe('UUID of the package, from km_get_catalog.'),
+      confirm_token: z.string().optional().describe(CONFIRM_DESC),
+    },
+    async ({ package_id, ...body }) => {
+      const r = await call('DELETE', `/packages/${encodeURIComponent(String(package_id || '').trim())}`, body);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_get_package_composition',
+    'What a package is MADE OF: the services inside it with quantities, each priced LIVE off the rate card, ' +
+      'plus the parts total and the discount against the package price. A package is an assortment of services ' +
+      'the OWNER selected - "3 hours of Balloon Twisting + 1 x 30-minute Magic Show" - never everything on the ' +
+      'rate card. The response also carries available_services (the whole rate card with ids), so this one call ' +
+      'gives you everything km_set_package_composition needs. An empty composition is a fine state: the package ' +
+      'sells on its price alone. Read only.',
+    {
+      package_id: z.string().describe('UUID of the package, from km_get_catalog.'),
+    },
+    async ({ package_id }) => {
+      const r = await call('GET', `/packages/${encodeURIComponent(String(package_id || '').trim())}/composition`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_set_package_composition',
+    'Set what a package is made of, in ONE call: the full list of services and how much of each. Whatever you ' +
+      'send REPLACES the current composition, so start from km_get_package_composition and send the complete ' +
+      'list, not just the change. quantity is in the service\'s own unit: a per-hour service with quantity 3 ' +
+      'means 3 hours; decimals like 1.5 are fine. An empty list clears the composition (the package keeps its ' +
+      'price and stays bookable). Composition never changes what a buyer pays - the package price stands; it is ' +
+      'what lets quotes explode a package into editable service lines and shows the owner the discount they are ' +
+      'giving off their own rates. This is a confirmed write; expect a 409 spelling the composition out first.',
+    {
+      package_id: z.string().describe('UUID of the package, from km_get_catalog.'),
+      services: z.array(z.object({
+        service_id: z.string().describe('UUID of a rate-card service, from available_services on km_get_package_composition.'),
+        quantity: z.number().gt(0).max(999).describe("How much of it, in the service's own unit. 3 on a per-hour service = 3 hours."),
+      })).max(50).describe('The COMPLETE composition. It replaces what is there. Empty array clears it.'),
+      confirm_token: z.string().optional().describe(CONFIRM_DESC),
+    },
+    async ({ package_id, ...body }) => {
+      const r = await call('PUT', `/packages/${encodeURIComponent(String(package_id || '').trim())}/composition`, body);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+}