@kivimedia/kmhub 2.0.0 → 2.9.1

package/tools/catalog.mjs

@@ -0,0 +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);
+    },
+  );
+}

package/tools/clubs.mjs

@@ -0,0 +1,176 @@
+/**
+ * Tool family: clubs - the Clubs Radar directory, read from the terminal.
+ *
+ * Like the military family (and unlike every scan-shaped radar), the clubs market is ENUMERABLE
+ * rather than searchable: every chartered American Legion post, VFW post, Elks lodge and Moose
+ * lodge is a published row somewhere, and the engine has already pulled them in. So the thing a
+ * person wants from the terminal is not "what did the last scan find", it is "show me what is
+ * already in there", and that needs its own family rather than another entry in a mission list.
+ *
+ *   km_clubs_directory -> GET /clubs/directory
+ *   km_clubs_posts     -> GET /clubs/posts
+ *   km_clubs_post      -> GET /clubs/posts/:ref
+ *
+ * 🚨 READ ONLY, and there are three separate reasons, all of which the descriptions say out loud:
+ *
+ *   1. NOTHING HERE SUBMITS, APPROVES OR SENDS. Writing to a post's mailbox or dialing its phone
+ *      is a human act in KM Hub, behind the Approval Queue - club_radar drafts are a never-auto
+ *      source, because a cold first impression to a veterans hall is exactly the message a human
+ *      must read first.
+ *   2. NOTHING HERE STARTS A SWEEP. Queueing one is admin-only under RLS in the web app, and the
+ *      API runs on the service role, which bypasses RLS: a start tool would quietly hand any
+ *      read/write key a power the product refuses to a non-admin member. Whether a sweep is
+ *      running is readable through km_list_radar_scans with kind 'club_radar_ingest'.
+ *   3. Reading costs NOTHING and sends NOTHING. The directory is shared reference data with
+ *      global read, already populated before anybody runs anything, so there is no first click
+ *      to make and no bill for looking.
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { z } from 'zod';
+
+export const FAMILY = 'clubs';
+
+export const TOOLS = [
+  'km_clubs_directory',
+  'km_clubs_posts',
+  'km_clubs_post',
+];
+
+// Finding and reaching buyers is outreach work, so this family joins that profile. It is not in
+// `core`: a session that only wants orientation should not carry three more schemas.
+export const PROFILES = ['outreach'];
+
+/**
+ * Has this KM Hub simply never heard of the route, or did the route run and find nothing?
+ *
+ * 🚨 Same discrimination as the military family, for the same reason: asking for a post that is
+ * not in the directory is a real, ordinary 404. Collapsing the two would answer a plain typo with
+ * "your KM Hub does not have the clubs directory", which is a false statement about the product
+ * rather than a wrong answer about a post. So only the router's own self-describing 404, which
+ * carries the whole route list, counts as a missing route.
+ */
+function routeMissing(r) {
+  if (r.status === 405 || r.status === 501) return true;
+  if (r.status !== 404) return false;
+  const body = r && r.data && typeof r.data === 'object' ? r.data : null;
+  if (!body) return true;
+  if (Array.isArray(body.routes)) return true;
+  return typeof body.message === 'string' && body.message.startsWith('Unknown route');
+}
+
+const NOT_SUPPORTED =
+  'This KM Hub does not serve the clubs directory to the terminal yet. Nothing is broken: the workspace is fine ' +
+  'and every other tool works as normal. The directory is there in the web app at https://hub.kivimedia.co under ' +
+  'Outbound, named Clubs Radar.';
+
+const NO_SEND =
+  'What it will NOT do: it cannot write to a post, dial a phone, mark an engagement or send anything, and no ' +
+  'other tool here can either. Working a post - the ladder from first contact to a monthly residency - happens in ' +
+  'KM Hub at https://hub.kivimedia.co, on purpose. Never tell somebody a message went out.';
+
+const NO_INVENTION =
+  'Never construct an address. A post that publishes no email keeps no email, and a VFW row with a phone and no ' +
+  'mailbox is the NORMAL published state for that order, not missing data. A row whose email_confidence says ' +
+  '"pattern" is a constructed guess from the order\'s scheme (lodge<NUM>@mooseunits.org) that must verify before ' +
+  'it may reach a draft - say so whenever one is shown.';
+
+export function register(server, call, { out, text, qs }) {
+  server.tool(
+    'km_clubs_directory',
+    'The fraternal and veterans halls KM Hub has already enumerated: every chartered American Legion post, VFW ' +
+      'post, Elks lodge and Moose lodge in the directory, counted by order and by state, with how many rent their ' +
+      'hall, run a club room, and publish a mailbox. ' +
+      'Reach for it whenever somebody asks about clubs, lodges, posts, veterans halls, the Legion, the VFW, the ' +
+      'Elks or the Moose, and reach for it FIRST rather than describing the feature: this directory is shared ' +
+      'reference data that is already full before anybody runs anything, so there is nothing to start and nothing ' +
+      'to wait for. Reading it costs nothing, spends nothing and sends nothing. ' +
+      '🚨 Lead with the `directory` block, which is counted from the rows and not asserted. Say those numbers ' +
+      'before any individual row, because the single thing people get wrong about this surface is assuming it is ' +
+      'empty. ' +
+      'Why these buyers matter: posts run weekly member nights on a PRINTED schedule and most own a rentable hall ' +
+      'with an entertainment budget - one signed residency is a recurring monthly show. ' +
+      NO_INVENTION +
+      ' ' +
+      'Whether a sweep is running is a different question, answered by km_list_radar_scans with kind ' +
+      "'club_radar_ingest'. Starting one is done in KM Hub, never from here. " +
+      NO_SEND,
+    {},
+    async () => {
+      const r = await call('GET', '/clubs/directory');
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_clubs_posts',
+    'The posts themselves: one row per hall, with its printed meeting schedule (the free-demo-night slot IS that ' +
+      'line), the hall-rental and club-room flags, the route counts, the best mailbox where one is published, and ' +
+      'this workspace\'s own engagement status per post. ' +
+      'Use it when somebody wants the posts near them, the halls that rent, or a call list. Elks rows are the ' +
+      'warmest written route (published lodge emails); VFW rows are phone-first because that order publishes no ' +
+      'email - a phone-only row there is the office working normally. ' +
+      'Every filter is optional and `filters_applied` says back which ones are doing the narrowing, so an empty ' +
+      'result is explained rather than shrugged at. The radius filter needs lat, lng and radius_miles together, ' +
+      'and `skipped_no_coordinates` counts the rows it could not judge. ' +
+      NO_INVENTION +
+      ' ' +
+      'Read only. Costs nothing, spends nothing. ' +
+      NO_SEND,
+    {
+      org: z
+        .enum(['legion', 'vfw', 'elks', 'moose'])
+        .optional()
+        .describe('One fraternal order. Leave it out to see all four.'),
+      state: z.string().optional().describe('Two-letter US state, for example "NJ".'),
+      city: z.string().optional().describe('City name, matched loosely.'),
+      hall_rental: z.boolean().optional().describe('True for posts whose hall is rentable - the venue-partnership list.'),
+      club_room: z.boolean().optional().describe('True for posts with a bar, canteen or club room on premises.'),
+      q: z.string().optional().describe('Free text against name, place, order and meeting schedule, in any order.'),
+      lat: z.number().optional().describe('Radius center latitude. Use with lng and radius_miles.'),
+      lng: z.number().optional().describe('Radius center longitude. Use with lat and radius_miles.'),
+      radius_miles: z.number().optional().describe('Radius in miles around lat/lng. Nearest posts come back first.'),
+      limit: z.number().int().min(1).max(200).optional().describe('How many posts to return. Default 40. Check `truncated`.'),
+    },
+    async ({ org, state, city, hall_rental, club_room, q, lat, lng, radius_miles, limit }) => {
+      const r = await call('GET', `/clubs/posts${qs({ org, state, city, hall_rental, club_room, q, lat, lng, radius_miles, limit })}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+
+  server.tool(
+    'km_clubs_post',
+    'One post in full: every published contact with the page it was read off and the verbatim fragment it came ' +
+      'from, the meeting schedule, the hall flags, and whatever engagement this workspace has already recorded. ' +
+      'Use it after km_clubs_posts when somebody picks a post, or whenever they name one directly. It takes the ' +
+      'club_key from a previous answer (for example "elks:nj:21") or a 9-digit EIN. ' +
+      '🚨 `email_confidence` decides whether an address may be written to as it stands: "published" was read off ' +
+      'the page named in source_url; "pattern" is a constructed guess that must verify first, and any draft ' +
+      'against it is refused until it does. `serves_posts` above 1 means one mailbox answers for several posts - ' +
+      'send it once, never once per hall. ' +
+      '`your_engagement` is this workspace\'s own ladder (researching, contacted, replied, demo booked, monthly ' +
+      'resident) and its sent marks - the record that keeps the same mailbox from being contacted twice. ' +
+      NO_INVENTION +
+      ' ' +
+      'Read only. Costs nothing, spends nothing. ' +
+      NO_SEND,
+    {
+      post: z
+        .string()
+        .describe('The club_key from a previous answer, for example "elks:nj:21", or the post\'s 9-digit EIN.'),
+    },
+    async ({ post }) => {
+      const ref = String(post || '').trim();
+      if (!ref) {
+        return text(
+          'I need to know which post. km_clubs_posts lists them, and each row carries the club_key this tool takes.',
+        );
+      }
+      const r = await call('GET', `/clubs/posts/${encodeURIComponent(ref)}`);
+      if (routeMissing(r)) return text(NOT_SUPPORTED, true);
+      return out(r);
+    },
+  );
+}