@kivimedia/kmhub 2.9.1 → 2.11.0

package/tools/capabilities.mjs

@@ -1,155 +1,155 @@
-/**
- * Tool family: capabilities - what KM Hub can do, and honestly where.
- *
- * km_capabilities answers "what is KM Hub" from ./capabilities.json, which is
- * GENERATED from the web app's own nav registry (scripts/generate-capabilities.mjs).
- * That generation is the whole point: a hand-written feature list is wrong within a
- * month, and a connector that confidently describes a product that has moved is
- * worse than one that says nothing.
- *
- * WHY THIS READS A LOCAL FILE AND NOT THE API. The answer is the same for every
- * workspace on a given build, it is needed at the START of a session when the model
- * is deciding what is even possible, and it must work when the API is slow. A round
- * trip would buy nothing. Per-workspace filtering (which pillars this org has switched
- * on) is a later addition and belongs on the API when it comes.
- *
- * 🚨 THE `reach` FIELD IS THE HONEST PART. Every page reports `terminal`,
- * `terminal_read` or `web_only`. Claude MUST NOT promise to do a web_only thing
- * from the terminal, and MUST NOT promise to EDIT a terminal_read page: those can
- * be looked at from here and changed only in the web app. Say KM Hub does it, name
- * the page, and point at the web app. Telling a client "yes I can" and then
- * failing is worse than "KM Hub does that, here is where". The read distinction
- * exists because Mark Fuller's 01-Sep-26 gap report caught two read-only pages
- * reporting plain `terminal`, which reads as "you can work on this from here".
- *
- * The family contract this file follows is documented in ./README.md.
- */
-import { readFileSync } from 'node:fs';
-import { z } from 'zod';
-
-export const FAMILY = 'capabilities';
-
-export const TOOLS = ['km_capabilities'];
-
-// Knowing what the product is costs one small file and changes every other answer,
-// so it loads in every profile.
-export const PROFILES = ['*'];
-
-let CACHE = null;
-
-function load() {
-  if (CACHE) return CACHE;
-  try {
-    CACHE = JSON.parse(readFileSync(new URL('../capabilities.json', import.meta.url), 'utf8'));
-  } catch (e) {
-    CACHE = { error: String(e?.message || e) };
-  }
-  return CACHE;
-}
-
-/** Trim a page down to what a model needs to decide, dropping the empty fields. */
-function slim(p, withTools) {
-  const o = { id: p.id, label: p.label, reach: p.reach };
-  // A page can be web-only because nobody built it yet, or because it should never
-  // be driven from a terminal at all. Saying which is the difference between "not
-  // yet" and "not ever", and a model that blurs them will keep offering to try.
-  if (p.web_only_by_design) o.web_only_by_design = true;
-  if (p.benefit) o.what_it_does = p.benefit;
-  if (withTools && p.tools?.length) o.tools = p.tools;
-  if (withTools && p.plays?.length) o.plays = p.plays;
-  return o;
-}
-
-export function register(server, call, { text }) {
-  server.tool(
-    'km_capabilities',
-    'The map of everything KM Hub does, and honestly which parts you can do from here. ' +
-      'CALL THIS EARLY in any session where the user is deciding what to work on, asks what KM Hub can do, ' +
-      'asks whether it can handle some area of their business, wonders if it does something a different tool does, ' +
-      'or asks a question you are about to answer with "I do not think KM Hub does that". You very likely have not ' +
-      'seen the whole product: it is 7 pillars and over 100 feature pages, far more than the tools in front of you, ' +
-      'so an answer based only on your tool list will understate it badly. ' +
-      'What comes back is the same nav the web app renders - Marketing, Sales, Operations, HR, Clients, AI Team, ' +
-      'Settings - each with its groups, its pages, and one plain sentence per page about what that page is FOR. ' +
-      '🚨 Every page carries `reach`. `terminal` means tools or plays here can do it. `terminal_read` means you can ' +
-      'look from here but every change happens in the web app, so say where the editing lives up front. `web_only` ' +
-      'means KM Hub does it but this connector cannot reach it at all. NEVER offer to do a web_only thing or to ' +
-      'edit a terminal_read one. Say KM Hub does it, name the page, and ' +
-      'point them at https://hub.kivimedia.co. Claiming a capability you do not have and then failing costs more ' +
-      'trust than saying where it lives. ' +
-      'Use it to answer the whole question rather than the part you happen to hold: someone asking about follow-up ' +
-      'should hear that KM Hub also runs their newsletter, their SEO and their reviews. It reads a file, costs ' +
-      'nothing, sends nothing and changes nothing.',
-    {
-      pillar: z
-        .enum(['marketing', 'sales', 'operations', 'hr', 'support', 'strategy', 'setup'])
-        .optional()
-        .describe(
-          'Narrow to one pillar when the user asked about one area. marketing = being found and reaching out, ' +
-            'sales = pipeline through to close, operations = diary, money and delivery, hr = team, pay and time, ' +
-            'support = clients, conversations and reputation, strategy = the AI officers, decisions and reporting, ' +
-            'setup = account, billing and connections. Leave it out for the whole product.',
-        ),
-      reach: z
-        .enum(['terminal', 'terminal_read', 'web_only', 'all'])
-        .optional()
-        .describe(
-          "Default 'all'. Use 'terminal' when you want what you can reach from here; it includes 'terminal_read' " +
-            "pages, so check each page's own reach before offering to CHANGE anything on it. Use 'terminal_read' " +
-            "for only the look-but-not-touch pages, and 'web_only' to answer \"what else is in there\" honestly.",
-        ),
-      detail: z
-        .enum(['summary', 'full'])
-        .optional()
-        .describe(
-          "Default 'summary': pillars, groups, pages and what each is for. 'full' adds the exact tool and play " +
-            'names behind each page, which you want when planning a piece of work rather than describing the product.',
-        ),
-    },
-    async ({ pillar, reach = 'all', detail = 'summary' }) => {
-      const doc = load();
-      if (doc.error) {
-        return text(
-          'The capability map did not load on this connector, so I cannot list what KM Hub does. ' +
-            'The workspace itself is fine and every other tool works as normal. Detail: ' + doc.error,
-          true,
-        );
-      }
-
-      const withTools = detail === 'full';
-      const pillars = [];
-      for (const p of doc.pillars) {
-        if (pillar && p.id !== pillar) continue;
-        const groups = [];
-        for (const g of p.groups) {
-          const pages = g.pages
-            // 'terminal' includes 'terminal_read': both are reachable, and a
-            // caller narrowing to what it can reach must not lose the read side.
-            .filter((x) => reach === 'all' || x.reach === reach || (reach === 'terminal' && x.reach === 'terminal_read'))
-            .map((x) => slim(x, withTools));
-          if (pages.length) groups.push({ group: g.header, pages });
-        }
-        if (groups.length) pillars.push({ id: p.id, label: p.label, tagline: p.tagline, groups });
-      }
-
-      const shown = pillars.reduce((n, p) => n + p.groups.reduce((m, g) => m + g.pages.length, 0), 0);
-
-      const body = {
-        product: 'KM Hub',
-        web_app: 'https://hub.kivimedia.co',
-        totals: doc.counts,
-        showing: { pillar: pillar || 'all', reach, pages: shown },
-        how_to_read:
-          "reach 'terminal' means you can do it from here. reach 'terminal_read' means you can LOOK at it from " +
-          'here but every change happens in the web app: say where the editing lives up front, never offer the ' +
-          "edit and fail at it. reach 'web_only' means KM Hub does it but this connector cannot yet, so name the " +
-          'page and point at the web app rather than offering to do it. ' +
-          "A page also carrying web_only_by_design will NEVER be reachable from a terminal: it is a deliberate " +
-          'boundary, not a backlog item, so do not imply it is coming.',
-        pillars,
-      };
-
-      return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }] };
-    },
-  );
-}
+/**
+ * Tool family: capabilities - what KM Hub can do, and honestly where.
+ *
+ * km_capabilities answers "what is KM Hub" from ./capabilities.json, which is
+ * GENERATED from the web app's own nav registry (scripts/generate-capabilities.mjs).
+ * That generation is the whole point: a hand-written feature list is wrong within a
+ * month, and a connector that confidently describes a product that has moved is
+ * worse than one that says nothing.
+ *
+ * WHY THIS READS A LOCAL FILE AND NOT THE API. The answer is the same for every
+ * workspace on a given build, it is needed at the START of a session when the model
+ * is deciding what is even possible, and it must work when the API is slow. A round
+ * trip would buy nothing. Per-workspace filtering (which pillars this org has switched
+ * on) is a later addition and belongs on the API when it comes.
+ *
+ * 🚨 THE `reach` FIELD IS THE HONEST PART. Every page reports `terminal`,
+ * `terminal_read` or `web_only`. Claude MUST NOT promise to do a web_only thing
+ * from the terminal, and MUST NOT promise to EDIT a terminal_read page: those can
+ * be looked at from here and changed only in the web app. Say KM Hub does it, name
+ * the page, and point at the web app. Telling a client "yes I can" and then
+ * failing is worse than "KM Hub does that, here is where". The read distinction
+ * exists because Mark Fuller's 01-Sep-26 gap report caught two read-only pages
+ * reporting plain `terminal`, which reads as "you can work on this from here".
+ *
+ * The family contract this file follows is documented in ./README.md.
+ */
+import { readFileSync } from 'node:fs';
+import { z } from 'zod';
+
+export const FAMILY = 'capabilities';
+
+export const TOOLS = ['km_capabilities'];
+
+// Knowing what the product is costs one small file and changes every other answer,
+// so it loads in every profile.
+export const PROFILES = ['*'];
+
+let CACHE = null;
+
+function load() {
+  if (CACHE) return CACHE;
+  try {
+    CACHE = JSON.parse(readFileSync(new URL('../capabilities.json', import.meta.url), 'utf8'));
+  } catch (e) {
+    CACHE = { error: String(e?.message || e) };
+  }
+  return CACHE;
+}
+
+/** Trim a page down to what a model needs to decide, dropping the empty fields. */
+function slim(p, withTools) {
+  const o = { id: p.id, label: p.label, reach: p.reach };
+  // A page can be web-only because nobody built it yet, or because it should never
+  // be driven from a terminal at all. Saying which is the difference between "not
+  // yet" and "not ever", and a model that blurs them will keep offering to try.
+  if (p.web_only_by_design) o.web_only_by_design = true;
+  if (p.benefit) o.what_it_does = p.benefit;
+  if (withTools && p.tools?.length) o.tools = p.tools;
+  if (withTools && p.plays?.length) o.plays = p.plays;
+  return o;
+}
+
+export function register(server, call, { text }) {
+  server.tool(
+    'km_capabilities',
+    'The map of everything KM Hub does, and honestly which parts you can do from here. ' +
+      'CALL THIS EARLY in any session where the user is deciding what to work on, asks what KM Hub can do, ' +
+      'asks whether it can handle some area of their business, wonders if it does something a different tool does, ' +
+      'or asks a question you are about to answer with "I do not think KM Hub does that". You very likely have not ' +
+      'seen the whole product: it is 7 pillars and over 100 feature pages, far more than the tools in front of you, ' +
+      'so an answer based only on your tool list will understate it badly. ' +
+      'What comes back is the same nav the web app renders - Marketing, Sales, Operations, HR, Clients, AI Team, ' +
+      'Settings - each with its groups, its pages, and one plain sentence per page about what that page is FOR. ' +
+      '🚨 Every page carries `reach`. `terminal` means tools or plays here can do it. `terminal_read` means you can ' +
+      'look from here but every change happens in the web app, so say where the editing lives up front. `web_only` ' +
+      'means KM Hub does it but this connector cannot reach it at all. NEVER offer to do a web_only thing or to ' +
+      'edit a terminal_read one. Say KM Hub does it, name the page, and ' +
+      'point them at https://hub.kivimedia.co. Claiming a capability you do not have and then failing costs more ' +
+      'trust than saying where it lives. ' +
+      'Use it to answer the whole question rather than the part you happen to hold: someone asking about follow-up ' +
+      'should hear that KM Hub also runs their newsletter, their SEO and their reviews. It reads a file, costs ' +
+      'nothing, sends nothing and changes nothing.',
+    {
+      pillar: z
+        .enum(['marketing', 'sales', 'operations', 'hr', 'support', 'strategy', 'setup'])
+        .optional()
+        .describe(
+          'Narrow to one pillar when the user asked about one area. marketing = being found and reaching out, ' +
+            'sales = pipeline through to close, operations = diary, money and delivery, hr = team, pay and time, ' +
+            'support = clients, conversations and reputation, strategy = the AI officers, decisions and reporting, ' +
+            'setup = account, billing and connections. Leave it out for the whole product.',
+        ),
+      reach: z
+        .enum(['terminal', 'terminal_read', 'web_only', 'all'])
+        .optional()
+        .describe(
+          "Default 'all'. Use 'terminal' when you want what you can reach from here; it includes 'terminal_read' " +
+            "pages, so check each page's own reach before offering to CHANGE anything on it. Use 'terminal_read' " +
+            "for only the look-but-not-touch pages, and 'web_only' to answer \"what else is in there\" honestly.",
+        ),
+      detail: z
+        .enum(['summary', 'full'])
+        .optional()
+        .describe(
+          "Default 'summary': pillars, groups, pages and what each is for. 'full' adds the exact tool and play " +
+            'names behind each page, which you want when planning a piece of work rather than describing the product.',
+        ),
+    },
+    async ({ pillar, reach = 'all', detail = 'summary' }) => {
+      const doc = load();
+      if (doc.error) {
+        return text(
+          'The capability map did not load on this connector, so I cannot list what KM Hub does. ' +
+            'The workspace itself is fine and every other tool works as normal. Detail: ' + doc.error,
+          true,
+        );
+      }
+
+      const withTools = detail === 'full';
+      const pillars = [];
+      for (const p of doc.pillars) {
+        if (pillar && p.id !== pillar) continue;
+        const groups = [];
+        for (const g of p.groups) {
+          const pages = g.pages
+            // 'terminal' includes 'terminal_read': both are reachable, and a
+            // caller narrowing to what it can reach must not lose the read side.
+            .filter((x) => reach === 'all' || x.reach === reach || (reach === 'terminal' && x.reach === 'terminal_read'))
+            .map((x) => slim(x, withTools));
+          if (pages.length) groups.push({ group: g.header, pages });
+        }
+        if (groups.length) pillars.push({ id: p.id, label: p.label, tagline: p.tagline, groups });
+      }
+
+      const shown = pillars.reduce((n, p) => n + p.groups.reduce((m, g) => m + g.pages.length, 0), 0);
+
+      const body = {
+        product: 'KM Hub',
+        web_app: 'https://hub.kivimedia.co',
+        totals: doc.counts,
+        showing: { pillar: pillar || 'all', reach, pages: shown },
+        how_to_read:
+          "reach 'terminal' means you can do it from here. reach 'terminal_read' means you can LOOK at it from " +
+          'here but every change happens in the web app: say where the editing lives up front, never offer the ' +
+          "edit and fail at it. reach 'web_only' means KM Hub does it but this connector cannot yet, so name the " +
+          'page and point at the web app rather than offering to do it. ' +
+          "A page also carrying web_only_by_design will NEVER be reachable from a terminal: it is a deliberate " +
+          'boundary, not a backlog item, so do not imply it is coming.',
+        pillars,
+      };
+
+      return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }] };
+    },
+  );
+}