@pipeshub-ai/mcp 2.2.0 → 2.3.1

package/bin/mcp-server.js

@@ -50456,6 +50456,36 @@ the user can verify.
 - \`pipeshub_agents\` — list the org's configured **agents** (specialized
   assistants with their own prompt, tools, and knowledge scope).
 
+## Knowledge Sources
+
+A source (an app connector or a KB) holds record groups (a project, space,
+drive, folder), which hold records (one ticket, page, file). Records nest —
+an epic over its stories, a page over its child pages.
+
+**Every tool returns metadata or content.**
+
+- \`pipeshub_search\` / \`pipeshub_chat\` — content, but only a ranked sample of
+  blocks: never all blocks of a record, never every record that matches, never
+  a complete list of what exists.
+- \`mode:"lookup"\` and \`mode:"navigate"\` — metadata: recordIds, fields, and
+  structure. No document text. \`mode:"content"\` — one whole record.
+
+**Combining them.** Search finds a starting point by wording; navigate on a
+\`recordId\` reveals what search structurally cannot — siblings, children,
+linked records, and the group's total count. For a question that must be
+exhaustive ("all", "how many", "every"), do NOT count search hits or trust a
+chat answer: navigate the record group, which reports the real total. For a
+record's siblings, navigate its parent — take the id from the \`Path\` line.
+
+**A named record** — an issue key, a Confluence / Drive / Slack link, an
+external ID → \`mode:"lookup"\` FIRST. It returns that record's metadata (for a
+ticket: status, assignee, priority, dates) plus its \`recordId\`, which often
+answers the question outright. Never guess a \`recordId\`.
+
+Pass a source's id from \`pipeshub_sources\` as \`apps: ["<id>"]\` to search or
+chat, and as \`nodeId\` to navigate. Navigate and lookup end in a \`Next:\` line
+naming the exact follow-up call — follow it.
+
 ## Agents
 
 Some orgs configure **agents** for specific jobs (e.g. a Slack messenger, a
@@ -50595,10 +50625,17 @@ var init_registration = __esm(() => {
   init_requestid();
 });
 
-// src/lib/base64.ts
+// src/lib/bytes-to-base64.ts
 function bytesToBase64(u8arr) {
-  return btoa(String.fromCodePoint(...u8arr));
+  let binary = "";
+  for (let i = 0;i < u8arr.length; i += BASE64_CHUNK) {
+    binary += String.fromCharCode(...u8arr.subarray(i, i + BASE64_CHUNK));
+  }
+  return btoa(binary);
 }
+var BASE64_CHUNK = 32768;
+
+// src/lib/base64.ts
 function bytesFromBase64(encoded) {
   return Uint8Array.from(atob(encoded), (c) => c.charCodeAt(0));
 }
@@ -51919,9 +51956,6 @@ function createRegisterPrompt(logger, server, getSDK, allowedScopes) {
 }
 
 // src/mcp-server/shared.ts
-function bytesToBase642(u8arr) {
-  return btoa(String.fromCodePoint(...u8arr));
-}
 async function consumeStream(stream) {
   const reader = stream.getReader();
   const chunks = [];
@@ -51942,13 +51976,13 @@ async function valueToBase64(value) {
   if (value == null) {
     return null;
   } else if (value instanceof Uint8Array) {
-    return bytesToBase642(value);
+    return bytesToBase64(value);
   } else if (value instanceof ArrayBuffer) {
-    return bytesToBase642(new Uint8Array(value));
+    return bytesToBase64(new Uint8Array(value));
   } else if (value instanceof Response || value instanceof Blob) {
-    return bytesToBase642(new Uint8Array(await value.arrayBuffer()));
+    return bytesToBase64(new Uint8Array(await value.arrayBuffer()));
   } else if (value instanceof ReadableStream) {
-    return bytesToBase642(await consumeStream(value));
+    return bytesToBase64(await consumeStream(value));
   } else if (typeof value === "string") {
     return base64Schema.parse(value);
   } else {
@@ -52912,6 +52946,77 @@ var init_agentsStreamMessage = __esm(() => {
   init_async();
 });
 
+// src/mcp-server/tools/_agui.ts
+function newChatStreamState() {
+  return {
+    conversation: null,
+    recordsUsed: undefined,
+    error: null,
+    conversationId: null,
+    title: null,
+    text: new Map,
+    rootMessageIds: new Set
+  };
+}
+function applyAGUIFrame(state, frame) {
+  const data = frame.data;
+  const d = data && typeof data === "object" ? data : {};
+  switch (frame.event) {
+    case AGUIEvent.RUN_FINISHED: {
+      const result = d.result;
+      if (!result || typeof result !== "object")
+        return false;
+      state.conversation = result.conversation ?? null;
+      state.recordsUsed = result.recordsUsed ?? result.meta?.recordsUsed;
+      return true;
+    }
+    case AGUIEvent.RUN_ERROR: {
+      state.error = (typeof data === "string" ? data : null) ?? d.message ?? d.error ?? frame.raw ?? "Stream error";
+      return true;
+    }
+    case AGUIEvent.CUSTOM: {
+      if (d.name === "conversation_created") {
+        const value = d.value ?? {};
+        state.conversationId = value.conversationId ?? state.conversationId;
+        state.title = value.title ?? state.title;
+      }
+      return false;
+    }
+    case AGUIEvent.TEXT_MESSAGE_CONTENT: {
+      if (typeof d.delta !== "string" || d.delta.length === 0)
+        return false;
+      const id = typeof d.messageId === "string" ? d.messageId : "";
+      state.text.set(id, (state.text.get(id) ?? "") + d.delta);
+      if (d.parentRunId == null)
+        state.rootMessageIds.add(id);
+      return false;
+    }
+    default:
+      return false;
+  }
+}
+function salvagedText(state) {
+  const pick2 = (ids) => {
+    let best = null;
+    for (const id of ids) {
+      const text = state.text.get(id);
+      if (text && (best === null || text.length > best.length))
+        best = text;
+    }
+    return best;
+  };
+  return pick2(state.rootMessageIds) ?? pick2(state.text.keys());
+}
+var AGUIEvent;
+var init__agui = __esm(() => {
+  AGUIEvent = {
+    RUN_FINISHED: "RUN_FINISHED",
+    RUN_ERROR: "RUN_ERROR",
+    CUSTOM: "CUSTOM",
+    TEXT_MESSAGE_CONTENT: "TEXT_MESSAGE_CONTENT"
+  };
+});
+
 // src/funcs/agentsListAgents.ts
 function agentsListAgents(client$, request, options) {
   return new APIPromise($do5(client$, request, options));
@@ -52993,7 +53098,10 @@ var init_agentsListAgents = __esm(() => {
 });
 
 // src/mcp-server/tools/_helpers.ts
-async function readJson(response) {
+async function readJson(response, context = "PipesHub request") {
+  const httpErr = await httpErrorResult(response, context);
+  if (httpErr)
+    return { ok: false, result: httpErr };
   const text = await response.text();
   if (!text) {
     return {
@@ -53022,6 +53130,13 @@ ${text.slice(0, 500)}`
     };
   }
 }
+function expiredTokenError(exp) {
+  if (typeof exp !== "number" || !Number.isFinite(exp))
+    return null;
+  if (exp * 1000 > Date.now())
+    return null;
+  return errorResult(`The access token expired on ${new Date(exp * 1000).toISOString()}. ` + "Mint a new personal access token in PipesHub under " + "Developer Settings → Personal Access Tokens.");
+}
 function jsonResult(value) {
   return {
     content: [{ type: "text", text: JSON.stringify(value, null, 2) }]
@@ -53048,11 +53163,15 @@ async function httpErrorResult(response, context) {
       message = candidate || body;
     } catch {}
   }
-  const detail = message ? ` ${message.slice(0, 400)}` : "";
+  const reason = message.slice(0, 400).trim();
+  const detail = reason ? ` ${/[.!?]$/.test(reason) ? reason : `${reason}.`}` : "";
   const auth = response.status === 401 || response.status === 403 ? " Check that the bearer token / credentials are valid and not expired." : "";
   return errorResult(`${context} failed (HTTP ${response.status} ${response.statusText}).${detail}${auth}`);
 }
-async function readValidated(response, schema) {
+async function readValidated(response, schema, context = "PipesHub request") {
+  const httpErr = await httpErrorResult(response, context);
+  if (httpErr)
+    return { ok: false, result: httpErr };
   const text = await response.text();
   if (!text) {
     return { ok: false, result: errorResult("Empty response from server") };
@@ -53121,15 +53240,17 @@ function trimCitations(citations) {
   if (!Array.isArray(citations))
     return [];
   return citations.map((c) => {
-    const md = c?.metadata ?? {};
+    const cd = c?.citationData ?? c;
+    const md = cd?.metadata ?? c?.metadata ?? {};
+    const content = typeof cd?.content === "string" ? cd.content : c?.content;
     return {
-      recordId: md.recordId ?? c?.recordId,
-      recordName: md.recordName ?? c?.recordName,
-      snippet: typeof c?.content === "string" ? c.content.slice(0, 280) : md.blockText ?? null,
+      recordId: md.recordId ?? cd?.recordId ?? c?.recordId,
+      recordName: md.recordName ?? cd?.recordName ?? c?.recordName,
+      snippet: typeof content === "string" ? content.slice(0, 280) : md.blockText ?? null,
       mimeType: md.mimeType,
       webUrl: md.webUrl,
       pageNum: md.pageNum,
-      chunkIndex: c?.chunkIndex ?? md.chunkIndex
+      chunkIndex: cd?.chunkIndex ?? c?.chunkIndex ?? md.chunkIndex
     };
   });
 }
@@ -53302,9 +53423,10 @@ var init_pipeshubChat = __esm(() => {
   init_conversationsStreamMessage();
   init_agentsStreamConversation();
   init_agentsStreamMessage();
+  init__agui();
   init__helpers();
   FiltersShape = object({
-    apps: array(string2()).optional().describe("Source-scoping ids. Mix connector instance UUIDs with the synthetic " + "`knowledgeBase_<orgId>` id (use pipeshub_sources to discover them). " + "Empty / omitted means no app-side restriction."),
+    apps: array(string2()).optional().describe("Source-scoping ids from `pipeshub_sources` — connector instance and / " + "or knowledge base ids, mixed freely. The legacy org-wide " + "`knowledgeBase_<orgId>` id is still accepted on deployments that " + "predate per-KB sources. Empty / omitted means no app-side " + "restriction."),
     kb: array(string2()).optional().describe("Legacy / unused. Leave empty.")
   }).optional();
   args = {
@@ -53318,40 +53440,45 @@ var init_pipeshubChat = __esm(() => {
     chatMode: _enum([
       "internal_search",
       "web_search",
-      "auto",
-      "quick",
-      "verification",
-      "deep"
+      "quick"
     ]).optional().describe("Response strategy. The valid values depend on whether `agentId` is set:\n" + "- WITHOUT `agentId` (plain chat): `internal_search` — answer from the " + "org's indexed knowledge (default) — or `web_search` — answer from the " + `live web.
-` + "- WITH `agentId` (agent chat): `auto` (let the agent decide; default), " + "`quick`, `verification`, or `deep`.")
+` + "- WITH `agentId` (agent chat): `quick` is the only supported mode and " + "is sent automatically, so this argument can be omitted.")
   };
   tool$pipeshubChat = {
     name: "pipeshub_chat",
-    description: `**Primary chat tool — handles both internal knowledge queries and web search.**
-
-**Internal search** (default, \`chatMode: "internal_search"\`): Use whenever
-the user asks about their documents, files, knowledge base, company policies,
-or anything that could plausibly be answered by content in their PipesHub-indexed
-sources (Drive, Box, Confluence, Slack, Gmail, Jira, the org's KB, ...).
-Grounds the answer in the user's actual data and returns citations.
-Answers come from a few retrieved passages, not whole documents — for
-any task needing a document's full content, use
-\`pipeshub_get_record_content\` instead.
-
-**Web search** (\`chatMode: "web_search"\`): Use when the user asks about
-current events, public information, or anything unlikely to be in the org's
-internal knowledge base. Pass \`chatMode: "web_search"\` and this tool will
-search the public web instead.
-
-**When to pick this over other tools:**
-- "Summarize <doc>" / "key points of <doc>" / "what does <document> say
-  about X?" → NOT this tool. Use \`pipeshub_search\` →
-  \`pipeshub_get_record_content\`: answering for a specific document
-  requires its full content, and chat only sees a few retrieved
-  passages, never the whole document.
+    description: `Ask a question, get an answer grounded in the org's indexed data with
+citations. It reads a few retrieved passages — never a whole document,
+never a complete list.
+
+**Three questions this tool gets WRONG. Check them first:**
+- **Structure** — "what's under this epic?", "which pages are in this
+  space?", "what links to this ticket?", "what's in this folder?" →
+  \`pipeshub_get_record_content\` \`mode:"navigate"\`. Ranking cannot see how
+  records relate.
+- **Exhaustive** — "how many X?", "list ALL the Y", "every Z" →
+  \`mode:"navigate"\`, which reports the group's real total. This tool
+  undercounts and will not say so.
+- **One named document** — summarize it, extract from it, what does it say
+  about X → \`pipeshub_search\` for the \`recordId\`, then \`mode:"content"\`.
+
+Everything else about the org's knowledge belongs here: policies,
+processes, decisions, history, "what do we know about X", and any question
+spanning several documents.
+
+**Internal search** (default, \`chatMode: "internal_search"\`): the user's
+documents, files, knowledge base, company policies — anything in their
+PipesHub-indexed sources (Drive, Box, Confluence, Slack, Gmail, Jira, the
+org's KB, ...).
+
+**Web search** (\`chatMode: "web_search"\`): current events or public
+information unlikely to be in the org's knowledge base.
+
+Both are plain-chat modes. **Agent chat** — pass an \`agentId\` from
+\`pipeshub_agents\` — runs against that agent's own prompt, tools and knowledge;
+\`quick\` is its only mode, requires the \`agentId\`, and is sent automatically.
+
 - "What's our policy on Y?" → \`pipeshub_chat\` (internal_search)
 - "What's in the news about Z?" → \`pipeshub_chat\` (web_search)
-- "What is the latest version of <library>?" → \`pipeshub_chat\` (web_search)
 - "Find / locate the file named X" → \`pipeshub_search\` (then
   \`pipeshub_download_record\` if the user wants the bytes).
 
@@ -53381,9 +53508,10 @@ cited document, take \`citations[*].recordId\` and call
     args,
     tool: async (client, args2, ctx) => {
       const fetchOptions = { signal: ctx.signal };
+      const plainChatMode = args2.chatMode === "web_search" ? "web_search" : "internal_search";
       let response;
       if (args2.agentId) {
-        const agentChatMode = args2.chatMode ?? "auto";
+        const agentChatMode = "quick";
         if (args2.conversationId) {
           const [result] = await agentsStreamMessage(client, {
             agentKey: args2.agentId,
@@ -53423,7 +53551,7 @@ cited document, take \`citations[*].recordId\` and call
             modelKey: args2.modelKey,
             modelName: args2.modelName,
             modelFriendlyName: args2.modelFriendlyName,
-            chatMode: args2.chatMode ?? "internal_search"
+            chatMode: plainChatMode
           }
         }, { fetchOptions }).$inspect();
         if (!result.ok)
@@ -53436,7 +53564,7 @@ cited document, take \`citations[*].recordId\` and call
           modelKey: args2.modelKey,
           modelName: args2.modelName,
           modelFriendlyName: args2.modelFriendlyName,
-          chatMode: args2.chatMode ?? "internal_search"
+          chatMode: plainChatMode
         }, { fetchOptions }).$inspect();
         if (!result.ok)
           return errorResult(result.error.message);
@@ -53445,62 +53573,36 @@ cited document, take \`citations[*].recordId\` and call
       const httpErr = await httpErrorResult(response, "PipesHub chat request");
       if (httpErr)
         return httpErr;
-      let finalConversation = null;
-      let recordsUsed;
-      let lastAccumulated = null;
-      let errorMessage = null;
+      const state = newChatStreamState();
       try {
         for await (const frame of iterateSSE(response)) {
-          switch (frame.event) {
-            case "complete": {
-              const d = frame.data ?? {};
-              finalConversation = d.conversation ?? null;
-              recordsUsed = d.recordsUsed ?? d.meta?.recordsUsed;
-              break;
-            }
-            case "error": {
-              const d = frame.data ?? {};
-              errorMessage = typeof d === "string" ? d : d.error ?? d.message ?? frame.raw ?? "Stream error";
-              break;
-            }
-            case "answer_chunk": {
-              const d = frame.data ?? {};
-              if (typeof d.accumulated === "string") {
-                lastAccumulated = d.accumulated;
-              } else if (typeof d.content === "string") {
-                lastAccumulated = (lastAccumulated ?? "") + d.content;
-              }
-              break;
-            }
-            default:
-              break;
-          }
-          if (finalConversation || errorMessage)
+          if (applyAGUIFrame(state, frame))
             break;
         }
       } catch (e) {
         return errorResult(`SSE stream failed: ${e.message}`);
       }
-      if (errorMessage)
-        return errorResult(errorMessage);
-      if (finalConversation) {
+      if (state.error)
+        return errorResult(state.error);
+      if (state.conversation) {
         return jsonResult({
-          ...trimConversation(finalConversation),
-          recordsUsed
+          ...trimConversation(state.conversation),
+          recordsUsed: state.recordsUsed
         });
       }
-      if (lastAccumulated) {
+      const salvaged = salvagedText(state);
+      if (salvaged) {
         return jsonResult({
-          conversationId: null,
-          title: null,
+          conversationId: state.conversationId,
+          title: state.title,
           status: "Inprogress",
-          answer: lastAccumulated,
+          answer: salvaged,
           confidence: null,
           citations: [],
           followUpQuestions: [],
           messageCount: 0,
-          recordsUsed,
-          warning: "Stream ended without a `complete` frame; answer is " + "the last accumulated chunk and citations are unavailable."
+          recordsUsed: state.recordsUsed,
+          warning: "Stream ended without a terminal RUN_FINISHED; answer is the " + "accumulated TEXT_MESSAGE_CONTENT and citations are unavailable."
         });
       }
       return errorResult("Stream ended without any usable frames.");
@@ -53669,10 +53771,23 @@ Typical uses:
 - Show the user a ranked list of matching files when they ask "find /
   search for X".
 
+Not for structural questions — what is under this epic, which pages are
+in this space, what links to this ticket. Ranking by content cannot show
+how records relate; use \`pipeshub_get_record_content\` \`mode:"navigate"\`.
+
+**A ranked sample, never a complete list.** Hits are the top-scoring
+blocks from the best-matching records — not all blocks of any record, and
+not every record that matches. Never count them to answer "how many" /
+"all" / "every"; navigate the record group instead, which reports its
+real total.
+
 The response is trimmed to one row per hit:
 \`{ recordId, recordName, score, snippet, mimeType, webUrl, ... }\`.
 Highest \`score\` first; multiple hits may share the same \`recordId\`
-(different chunks of the same record).`,
+(different blocks of the same record).
+
+When presenting results to the user, link each record using its
+\`webUrl\` (when present).`,
     scopes: ["read"],
     annotations: {
       title: "Semantic search",
@@ -53690,7 +53805,7 @@ Highest \`score\` first; multiple hits may share the same \`recordId\`
       }, { fetchOptions: { signal: ctx.signal } }).$inspect();
       if (!result.ok)
         return errorResult(result.error.message);
-      const parsed = await readJson(result.value);
+      const parsed = await readJson(result.value, "PipesHub search");
       if (!parsed.ok)
         return parsed.result;
       const sr = parsed.value.searchResponse ?? {};
@@ -53966,44 +54081,306 @@ var init_connectorGetRecordContent = __esm(() => {
   init_async();
 });
 
+// src/models/lookuprecordbyidentifierop.ts
+var LookupRecordByIdentifierRequest$zodSchema;
+var init_lookuprecordbyidentifierop = __esm(() => {
+  init_zod();
+  LookupRecordByIdentifierRequest$zodSchema = object({
+    connectorName: string2().describe("Connector hint to prioritise resolution order, e.g. `JIRA`, `CONFLUENCE`, `GOOGLE_DRIVE`, `SLACK`. Cannot widen beyond the connectors the caller can access.").optional(),
+    identifiers: array(string2().min(1).max(2048)).min(1).max(10).describe("The references to resolve: URLs, issue keys such as `PA-1787`, or bare external system IDs. Paste each exactly as you found it — tracking parameters and fragments are handled. Up to 10 per call.")
+  });
+});
+
+// src/funcs/connectorLookupRecordByIdentifier.ts
+function connectorLookupRecordByIdentifier(client$, request, options) {
+  return new APIPromise($do9(client$, request, options));
+}
+async function $do9(client$, request, options) {
+  const parsed$ = safeParse4(request, (value$) => LookupRecordByIdentifierRequest$zodSchema.parse(value$), "Input validation failed");
+  if (!parsed$.ok) {
+    return [parsed$, { status: "invalid" }];
+  }
+  const payload$ = parsed$.value;
+  const body$ = null;
+  const path$ = pathToFunc("/connectors/record/lookup")();
+  const query$ = encodeFormQuery({
+    connectorName: payload$.connectorName,
+    identifiers: payload$.identifiers
+  });
+  const headers$ = new Headers(compactMap({
+    Accept: "application/json"
+  }));
+  const securityInput = await extractSecurity(client$._options.security);
+  const requestSecurity = resolveGlobalSecurity(securityInput);
+  const context = {
+    options: client$._options,
+    baseURL: options?.serverURL ?? client$._baseURL ?? "",
+    operationID: "lookupRecordByIdentifier",
+    oAuth2Scopes: ["kb:read", "connector:read"],
+    resolvedSecurity: requestSecurity,
+    securitySource: client$._options.security,
+    retryConfig: options?.retries || client$._options.retryConfig || { strategy: "none" },
+    retryCodes: options?.retryCodes || [
+      "429",
+      "500",
+      "502",
+      "503",
+      "504"
+    ]
+  };
+  const requestRes = client$._createRequest(context, {
+    security: requestSecurity,
+    method: "GET",
+    baseURL: options?.serverURL,
+    path: path$,
+    headers: headers$,
+    query: query$,
+    body: body$,
+    userAgent: client$._options.userAgent,
+    timeoutMs: options?.timeoutMs || client$._options.timeoutMs || -1
+  }, options);
+  if (!requestRes.ok) {
+    return [requestRes, { status: "invalid" }];
+  }
+  const req$ = requestRes.value;
+  const doResult = await client$._do(req$, {
+    context,
+    errorCodes: [],
+    retryConfig: context.retryConfig,
+    retryCodes: context.retryCodes
+  });
+  if (!doResult.ok) {
+    return [doResult, { status: "request-error", request: req$ }];
+  }
+  return [doResult, {
+    status: "complete",
+    request: req$,
+    response: doResult.value
+  }];
+}
+var init_connectorLookupRecordByIdentifier = __esm(() => {
+  init_encodings();
+  init_primitives();
+  init_schemas4();
+  init_security2();
+  init_url();
+  init_lookuprecordbyidentifierop();
+  init_async();
+});
+
+// src/models/navigateknowledgegraphop.ts
+var NavigateKnowledgeGraphRequest$zodSchema;
+var init_navigateknowledgegraphop = __esm(() => {
+  init_zod();
+  NavigateKnowledgeGraphRequest$zodSchema = object({
+    createdAfter: string2().describe("Filter children by source creation time. ISO 8601 `YYYY-MM-DD`, or a full datetime that MUST carry a timezone offset — a naive datetime is rejected rather than assumed to be UTC.").optional(),
+    createdBefore: string2().describe("Filter children by source creation time. `YYYY-MM-DD` is inclusive of the whole day.").optional(),
+    depth: int().min(1).max(3).describe("Levels of descendants to return in one call. Above 1, `rows` is a flat list of all descendants down to that level rather than only direct children, and each row carries its own `level`.").optional(),
+    limit: int().min(50).max(200).describe("Children per page. The minimum is 50 — smaller values are rejected rather than silently raised.").optional(),
+    modifiedAfter: string2().describe("Filter children by source modification time.").optional(),
+    modifiedBefore: string2().describe("Filter children by source modification time.").optional(),
+    nodeId: string2().min(1).max(2048).describe("The node to open. Take it from an `id` in a previous navigate or lookup response. Omit it entirely for the flat listing of everything reachable — the usual starting point. A URL or an issue key such as `PA-1787` also works: it is resolved to its record automatically.").optional(),
+    nodeTypes: array(string2()).describe("Restrict children to these node types. Repeat the parameter for multiple types: `?nodeTypes=record&nodeTypes=folder`.").optional(),
+    page: int().min(1).describe("Page number, 1-indexed.").optional()
+  });
+});
+
+// src/funcs/connectorNavigateKnowledgeGraph.ts
+function connectorNavigateKnowledgeGraph(client$, request, options) {
+  return new APIPromise($do10(client$, request, options));
+}
+async function $do10(client$, request, options) {
+  const parsed$ = safeParse4(request, (value$) => NavigateKnowledgeGraphRequest$zodSchema.optional().parse(value$), "Input validation failed");
+  if (!parsed$.ok) {
+    return [parsed$, { status: "invalid" }];
+  }
+  const payload$ = parsed$.value;
+  const body$ = null;
+  const path$ = pathToFunc("/connectors/navigate")();
+  const query$ = encodeFormQuery({
+    createdAfter: payload$?.createdAfter,
+    createdBefore: payload$?.createdBefore,
+    depth: payload$?.depth,
+    limit: payload$?.limit,
+    modifiedAfter: payload$?.modifiedAfter,
+    modifiedBefore: payload$?.modifiedBefore,
+    nodeId: payload$?.nodeId,
+    nodeTypes: payload$?.nodeTypes,
+    page: payload$?.page
+  });
+  const headers$ = new Headers(compactMap({
+    Accept: "application/json"
+  }));
+  const securityInput = await extractSecurity(client$._options.security);
+  const requestSecurity = resolveGlobalSecurity(securityInput);
+  const context = {
+    options: client$._options,
+    baseURL: options?.serverURL ?? client$._baseURL ?? "",
+    operationID: "navigateKnowledgeGraph",
+    oAuth2Scopes: ["kb:read", "connector:read"],
+    resolvedSecurity: requestSecurity,
+    securitySource: client$._options.security,
+    retryConfig: options?.retries || client$._options.retryConfig || { strategy: "none" },
+    retryCodes: options?.retryCodes || [
+      "429",
+      "500",
+      "502",
+      "503",
+      "504"
+    ]
+  };
+  const requestRes = client$._createRequest(context, {
+    security: requestSecurity,
+    method: "GET",
+    baseURL: options?.serverURL,
+    path: path$,
+    headers: headers$,
+    query: query$,
+    body: body$,
+    userAgent: client$._options.userAgent,
+    timeoutMs: options?.timeoutMs || client$._options.timeoutMs || -1
+  }, options);
+  if (!requestRes.ok) {
+    return [requestRes, { status: "invalid" }];
+  }
+  const req$ = requestRes.value;
+  const doResult = await client$._do(req$, {
+    context,
+    errorCodes: [],
+    retryConfig: context.retryConfig,
+    retryCodes: context.retryCodes
+  });
+  if (!doResult.ok) {
+    return [doResult, { status: "request-error", request: req$ }];
+  }
+  return [doResult, {
+    status: "complete",
+    request: req$,
+    response: doResult.value
+  }];
+}
+var init_connectorNavigateKnowledgeGraph = __esm(() => {
+  init_encodings();
+  init_primitives();
+  init_schemas4();
+  init_security2();
+  init_url();
+  init_navigateknowledgegraphop();
+  init_async();
+});
+
 // src/mcp-server/tools/pipeshubGetRecordContent.ts
+async function renderedResult(response) {
+  const parsed = await readJson(response);
+  if (!parsed.ok)
+    return parsed.result;
+  const text = parsed.value?.text;
+  return typeof text === "string" && text.trim().length > 0 ? { content: [{ type: "text", text }] } : jsonResult(parsed.value);
+}
 var args4, tool$pipeshubGetRecordContent;
 var init_pipeshubGetRecordContent = __esm(() => {
   init_zod();
   init_connectorGetRecordContent();
+  init_connectorLookupRecordByIdentifier();
+  init_connectorNavigateKnowledgeGraph();
   init__helpers();
   args4 = {
-    recordId: string2().min(1).describe("Record identifier — usually a UUID for connector-sourced records or " + "a 24-character ObjectId for uploaded records. Get it from a chat " + "citation (`citations[*].recordId`) or from a `pipeshub_search` hit.")
+    mode: _enum(["content", "navigate", "lookup"]).default("content").describe("`content` (default) reads a record's full text by `recordId`. " + "`lookup` resolves a URL / issue key / external ID to a recordId. " + "`navigate` browses the knowledge graph tree."),
+    recordId: string2().min(1).optional().describe("Record identifier — usually a UUID for connector-sourced records or " + "a 24-character ObjectId for uploaded records. Get it from a chat " + "citation (`citations[*].recordId`) or from a `pipeshub_search` hit. " + "Required when `mode` is `content`."),
+    nodeId: string2().min(1).max(2048).optional().describe("The node to open. Take it from a `record_id=` or `node_id=` shown in a " + "previous navigate or lookup response, from a search hit's `recordId`, " + "or from a `pipeshub_sources` id — a KB or connector id opens that " + "source directly. Omit it entirely for the flat listing of everything " + "reachable, newest first — the usual starting point. A URL or an issue " + "key such as `PA-1787` also works: it is resolved to its record " + "automatically, so no separate lookup is needed."),
+    page: int().min(1).default(1).describe("Page number, 1-indexed."),
+    limit: int().min(50).max(200).default(50).describe("Children per page. The minimum is 50 — smaller values are rejected " + "rather than silently raised."),
+    depth: int().min(1).max(3).default(1).describe("Levels of descendants to return in one call. Above 1, the listing is a " + "flat list of all descendants down to that level rather than only " + "direct children, and each row carries its own `level`."),
+    nodeTypes: array(string2()).optional().describe('Restrict children to these node types, e.g. `["record", "folder"]`.'),
+    createdAfter: string2().optional().describe("Filter children by source creation time. ISO 8601 `YYYY-MM-DD`, or a " + "full datetime that MUST carry a timezone offset — a naive datetime is " + "rejected rather than assumed to be UTC."),
+    createdBefore: string2().optional().describe("Filter children by source creation time. `YYYY-MM-DD` is inclusive of " + "the whole day."),
+    modifiedAfter: string2().optional().describe("Filter children by source modification time. Same formats as " + "`createdAfter`."),
+    modifiedBefore: string2().optional().describe("Filter children by source modification time. Same formats as " + "`createdBefore`."),
+    identifiers: union([
+      string2().min(1).max(2048),
+      array(string2().min(1).max(2048)).min(1).max(10)
+    ]).optional().describe("The reference(s) to resolve: a URL, an issue key such as `PA-1787`, or " + "a bare external system ID. Paste each exactly as you found it — " + "tracking parameters and fragments are handled. Pass a single string, " + "or an array of up to 10 to resolve them in one call. Required when " + "`mode` is `lookup`."),
+    connectorName: string2().optional().describe("Optional hint that prioritises resolution order, e.g. `JIRA`, " + "`CONFLUENCE`, `GOOGLE_DRIVE`, `SLACK`. It cannot widen the search beyond the " + "connectors you can already access. Useful on a retry when a lookup " + "came back empty.")
   };
   tool$pipeshubGetRecordContent = {
     name: "pipeshub_get_record_content",
-    description: `Read a record's full parsed content by \`recordId\` — the only way to
-see a document's COMPLETE text.
-
-Use it whenever the answer depends on a document's full content — any
-task where missing a part could make the answer wrong: summarize / key
-points / action items; extract or list ALL of something; check whether
-or where the doc mentions X; translate, rewrite, outline, or review the
-doc; compare named docs (fetch each); any question scoped to one named
-document. \`pipeshub_chat\` cannot do these — it only sees a few
-retrieved passages, never the whole document. Get the \`recordId\` from
-a \`pipeshub_search\` top hit or a chat citation.
-
-Judge by the user's INTENT, not their keywords: they need not say
-"summarize", "key points", or "extract". Reason about what a good
-answer requires — if it would need the whole document (e.g. "what's
-this doc about?", "walk me through the report", "anything in here
-about Y?"), that is a full-content task, so call this tool.
-
-Returns a single \`content\` string: a short metadata header (title,
-source, key fields, and a pre-generated summary) followed by the
-record's full parsed text — paragraphs, tables, and lists in reading
-order. For a record with no extractable content, \`content\` is the
-literal \`No record found\`. Use \`pipeshub_download_record\` only when
-you need the original file bytes.`,
+    description: `Three operations on the org's records. Pick by what you hold:
+
+  \`mode:"lookup"\`   — a URL, issue key (PA-1787), or external ID
+                    → its recordId plus the record's metadata
+  \`mode:"navigate"\` — a question about structure: what is under X,
+                    what links to Y → browses the hierarchy
+  \`mode:"content"\`  — a recordId, and you need the document's COMPLETE text
+
+**\`mode:"content"\` (default)** — the only way to see a document's complete
+text. Use it whenever missing part of the document could make the answer
+wrong: summarize, extract or list ALL of something, check whether or where
+a doc mentions X, review, or compare named docs. \`pipeshub_chat\` cannot do
+these — it never sees a whole document.
+
+Judge by the user's INTENT, not their keywords: "what's this doc about?",
+"walk me through the report", "anything in here about Y?" are all
+full-content tasks. Get the \`recordId\` from a \`pipeshub_search\` top hit, a
+chat citation, or \`mode:"lookup"\`.
+
+Returns one \`content\` string: a metadata header (title, source, key fields,
+pre-generated summary) then the full parsed text. A record with no
+extractable content returns the literal \`No record found\`. Use
+\`pipeshub_download_record\` only for the original file bytes.
+
+**\`mode:"navigate"\`** — browse the hierarchy: RecordGroup (project /
+space / drive / folder) → Record (epic / story / page / file) → children,
+with breadcrumbs, related links and record IDs.
+
+Use it when the question depends on structure rather than wording: what is
+under this epic, which pages sit in this space, what is linked to this
+ticket, what is in this folder — and every "how many" / "all of" / "every"
+question. Search ranks by content; only this shows how records relate, and
+only this gives a count you can trust.
+
+Omit \`nodeId\` for a flat listing of everything reachable, most recently
+updated first — the usual starting point. A URL, an issue key, or a
+\`pipeshub_sources\` id also works and resolves automatically.
+
+Pass \`depth:2\` or \`depth:3\` to see several levels in ONE call — an epic's
+stories AND their subtasks, a space's pages AND their children — instead of
+one call per level. Use it whenever the question needs an overview of a
+hierarchy rather than a single node.
+
+Opening a record also prints that record's own metadata — for a ticket,
+status, assignee, priority and dates — so a question about one record is
+often answered by this call alone. It returns no document text; for that,
+re-call with \`mode:"content"\`.
+
+Returns \`Path\` breadcrumbs, the current node's metadata, a children listing
+carrying \`record_id=\` or \`node_id=\` per row plus the group's total
+(\`Children 1-50 of 61\`), \`Related\` cross-references, and a \`Next:\` line.
+One page is usually every child, so only pass \`page:2\` when that \`Next:\`
+line says more exist.
+
+**\`mode:"lookup"\`** — turn an external reference into a recordId, the first
+step whenever the question names one. Returns that record's metadata (for a
+ticket: status, assignee, priority, dates) plus its recordId, which
+\`mode:"navigate"\` takes to list what is under it and \`mode:"content"\` takes
+to read it.
+
+Handles Jira keys and URLs, Confluence, Drive, Slack permalinks, Linear,
+Notion, ServiceNow sys_id, SharePoint, Gmail/Outlook, and any connector
+whose records index a web URL. Resolution searches ALL connectors you can
+access, regardless of any source filter you used elsewhere.
+
+A miss is a 200 with empty \`matches\` and the input echoed in
+\`not_found_identifiers\` — that may mean no-access, not non-existence. Use
+\`mode:"navigate"\` to confirm the record exists before telling the user it
+does not. If \`ambiguous\` is true, pick from \`matches\` rather than taking
+the first.
+
+Navigate and lookup return a rendered text view whose closing \`Next:\` line
+names the exact follow-up call — follow it. When presenting a record, link
+it using the \`Web URL\` from its metadata header (when present).`,
     scopes: ["read"],
     annotations: {
-      title: "Get a record's full parsed content",
+      title: "Read, browse, or resolve records",
       destructiveHint: false,
       idempotentHint: true,
       openWorldHint: false,
@@ -54011,9 +54388,48 @@ you need the original file bytes.`,
     },
     args: args4,
     tool: async (client, args5, ctx) => {
+      const fetchOptions = { fetchOptions: { signal: ctx.signal } };
+      if (args5.mode === "navigate") {
+        const [r] = await connectorNavigateKnowledgeGraph(client, {
+          nodeId: args5.nodeId,
+          page: args5.page,
+          limit: args5.limit,
+          depth: args5.depth,
+          nodeTypes: args5.nodeTypes,
+          createdAfter: args5.createdAfter,
+          createdBefore: args5.createdBefore,
+          modifiedAfter: args5.modifiedAfter,
+          modifiedBefore: args5.modifiedBefore
+        }, fetchOptions).$inspect();
+        if (!r.ok)
+          return errorResult(r.error.message);
+        const httpErr2 = await httpErrorResult(r.value, "Navigate knowledge graph");
+        if (httpErr2)
+          return httpErr2;
+        return renderedResult(r.value);
+      }
+      if (args5.mode === "lookup") {
+        const identifiers = typeof args5.identifiers === "string" ? [args5.identifiers] : args5.identifiers ?? [];
+        if (identifiers.length === 0) {
+          return errorResult('`identifiers` is required when mode is "lookup".');
+        }
+        const [r] = await connectorLookupRecordByIdentifier(client, {
+          identifiers,
+          connectorName: args5.connectorName
+        }, fetchOptions).$inspect();
+        if (!r.ok)
+          return errorResult(r.error.message);
+        const httpErr2 = await httpErrorResult(r.value, "Record lookup");
+        if (httpErr2)
+          return httpErr2;
+        return renderedResult(r.value);
+      }
+      if (!args5.recordId) {
+        return errorResult('`recordId` is required when mode is "content".');
+      }
       const [result] = await connectorGetRecordContent(client, {
         recordId: args5.recordId
-      }, { fetchOptions: { signal: ctx.signal } }).$inspect();
+      }, fetchOptions).$inspect();
       if (!result.ok)
         return errorResult(result.error.message);
       const httpErr = await httpErrorResult(result.value, "Get record content");
@@ -54040,9 +54456,9 @@ var init_getallusersop = __esm(() => {
 
 // src/funcs/usersGetAllUsers.ts
 function usersGetAllUsers(client$, request, options) {
-  return new APIPromise($do9(client$, request, options));
+  return new APIPromise($do11(client$, request, options));
 }
-async function $do9(client$, request, options) {
+async function $do11(client$, request, options) {
   const parsed$ = safeParse4(request, (value$) => GetAllUsersRequest$zodSchema.optional().parse(value$), "Input validation failed");
   if (!parsed$.ok) {
     return [parsed$, { status: "invalid" }];
@@ -54127,9 +54543,9 @@ var init_getuserbyidop = __esm(() => {
 
 // src/funcs/usersGetUserById.ts
 function usersGetUserById(client$, request, options) {
-  return new APIPromise($do10(client$, request, options));
+  return new APIPromise($do12(client$, request, options));
 }
-async function $do10(client$, request, options) {
+async function $do12(client$, request, options) {
   const parsed$ = safeParse4(request, (value$) => GetUserByIdRequest$zodSchema.parse(value$), "Input validation failed");
   if (!parsed$.ok) {
     return [parsed$, { status: "invalid" }];
@@ -54216,9 +54632,9 @@ var init_getallusergroupsop = __esm(() => {
 
 // src/funcs/userGroupsGetAllUserGroups.ts
 function userGroupsGetAllUserGroups(client$, request, options) {
-  return new APIPromise($do11(client$, request, options));
+  return new APIPromise($do13(client$, request, options));
 }
-async function $do11(client$, request, options) {
+async function $do13(client$, request, options) {
   const parsed$ = safeParse4(request, (value$) => GetAllUserGroupsRequest$zodSchema.optional().parse(value$), "Input validation failed");
   if (!parsed$.ok) {
     return [parsed$, { status: "invalid" }];
@@ -54308,9 +54724,9 @@ var init_getuserteamsop = __esm(() => {
 
 // src/funcs/teamsGetUserTeams.ts
 function teamsGetUserTeams(client$, request, options) {
-  return new APIPromise($do12(client$, request, options));
+  return new APIPromise($do14(client$, request, options));
 }
-async function $do12(client$, request, options) {
+async function $do14(client$, request, options) {
   const parsed$ = safeParse4(request, (value$) => GetUserTeamsRequest$zodSchema.optional().parse(value$), "Input validation failed");
   if (!parsed$.ok) {
     return [parsed$, { status: "invalid" }];
@@ -54404,7 +54820,7 @@ var init_pipeshubDirectory = __esm(() => {
       "list_groups",
       "list_my_teams"
     ]).describe(`What to do:
-` + "- `whoami` — return the authenticated user's identity (decoded from " + `the bearer JWT). No other args needed.
+` + "- `whoami` — return the authenticated user's identity, confirmed " + `against the server. No other args needed.
 ` + "- `list_users` — paginated list of org users. Optional `page`, " + "`limit`, `search` (substring match against name or email).\n" + "- `get_user` — full profile for one user. Required `userId`. " + "Use `whoami` to find your own id first if needed.\n" + "- `list_groups` — paginated list of user groups (with `userCount`).\n" + "- `list_my_teams` — teams the authenticated user belongs to, with " + "capability flags."),
     userId: string2().optional().describe("Required when `action` is `get_user`. 24-character ObjectId."),
     page: number2().int().min(1).optional().describe("Pagination — 1-based page number. Used by list_* actions."),
@@ -54418,7 +54834,8 @@ actions — pick the right \`action\`:
 
 - \`whoami\` — who is the caller?  Use this whenever you need the
   authenticated user's own id, email, or full name (e.g. before
-  \`get_user\` on themselves).
+  \`get_user\` on themselves). Errors if the credential is expired
+  or revoked.
 - \`list_users\` — search / page through org users.
 - \`get_user\` — full \`User\` document for one user (requires \`userId\`).
 - \`list_groups\` — list user groups with \`userCount\`.
@@ -54443,13 +54860,39 @@ Output shape varies by action; see each action's docs above.`,
           if (!claims) {
             return errorResult("No bearer token configured on the SDK client, so `whoami` " + "cannot resolve the caller's identity. Ask the user for " + "their email and use `list_users` with `search`.");
           }
+          const exp = claims["exp"];
+          const expired = expiredTokenError(exp);
+          if (expired)
+            return expired;
+          const tokenExpiresAt = typeof exp === "number" ? new Date(exp * 1000).toISOString() : undefined;
+          const userId = claims["userId"];
+          let verified = "unchecked";
+          let unverifiedReason = "No userId claim in the token, so the identity could not be " + "confirmed with the server.";
+          if (typeof userId === "string" && userId) {
+            const [probe] = await usersGetUserById(client, { id: userId }, {
+              fetchOptions
+            }).$inspect();
+            if (!probe.ok) {
+              unverifiedReason = `Could not reach PipesHub to confirm the ` + `identity (${probe.error.message}). The details below come ` + `from the token itself.`;
+            } else if (probe.value.status === 401) {
+              return errorResult("PipesHub rejected this access token (HTTP 401 Unauthorized), " + "so the identity in it is no longer valid — it has most " + "likely been revoked. Mint a new personal access token " + "under Developer Settings → Personal Access Tokens.");
+            } else if (probe.value.ok) {
+              verified = true;
+              unverifiedReason = undefined;
+            } else {
+              unverifiedReason = `PipesHub returned HTTP ${probe.value.status} ` + `when confirming the identity, so it could not be checked. ` + `The details below come from the token itself.`;
+            }
+          }
           return jsonResult({
             userId: claims["userId"],
             orgId: claims["orgId"],
             email: claims["email"],
             fullName: claims["fullName"],
             mobile: claims["mobile"],
-            userSlug: claims["userSlug"]
+            userSlug: claims["userSlug"],
+            tokenExpiresAt,
+            identityVerified: verified,
+            note: unverifiedReason
           });
         }
         case "list_users": {
@@ -54460,7 +54903,7 @@ Output shape varies by action; see each action's docs above.`,
           }, { fetchOptions }).$inspect();
           if (!result.ok)
             return errorResult(result.error.message);
-          const parsed = await readJson(result.value);
+          const parsed = await readJson(result.value, "User listing");
           if (!parsed.ok)
             return parsed.result;
           return jsonResult(parsed.value);
@@ -54474,7 +54917,7 @@ Output shape varies by action; see each action's docs above.`,
           }, { fetchOptions }).$inspect();
           if (!result.ok)
             return errorResult(result.error.message);
-          const parsed = await readJson(result.value);
+          const parsed = await readJson(result.value, "User lookup");
           if (!parsed.ok)
             return parsed.result;
           return jsonResult(parsed.value);
@@ -54487,7 +54930,7 @@ Output shape varies by action; see each action's docs above.`,
           }, { fetchOptions }).$inspect();
           if (!result.ok)
             return errorResult(result.error.message);
-          const parsed = await readJson(result.value);
+          const parsed = await readJson(result.value, "Group listing");
           if (!parsed.ok)
             return parsed.result;
           return jsonResult(parsed.value);
@@ -54500,7 +54943,7 @@ Output shape varies by action; see each action's docs above.`,
           }, { fetchOptions }).$inspect();
           if (!result.ok)
             return errorResult(result.error.message);
-          const parsed = await readJson(result.value);
+          const parsed = await readJson(result.value, "Team listing");
           if (!parsed.ok)
             return parsed.result;
           return jsonResult(parsed.value);
@@ -54540,9 +54983,9 @@ var init_getknowledgehubrootnodesop = __esm(() => {
 
 // src/funcs/knowledgeHubGetKnowledgeHubRootNodes.ts
 function knowledgeHubGetKnowledgeHubRootNodes(client$, request, options) {
-  return new APIPromise($do13(client$, request, options));
+  return new APIPromise($do15(client$, request, options));
 }
-async function $do13(client$, request, options) {
+async function $do15(client$, request, options) {
   const parsed$ = safeParse4(request, (value$) => GetKnowledgeHubRootNodesRequest$zodSchema.optional().parse(value$), "Input validation failed");
   if (!parsed$.ok) {
     return [parsed$, { status: "invalid" }];
@@ -54658,9 +55101,9 @@ var init_getavailablemodelsbytypeop = __esm(() => {
 
 // src/funcs/aiModelsProvidersGetAvailableModelsByType.ts
 function aiModelsProvidersGetAvailableModelsByType(client$, request, options) {
-  return new APIPromise($do14(client$, request, options));
+  return new APIPromise($do16(client$, request, options));
 }
-async function $do14(client$, request, options) {
+async function $do16(client$, request, options) {
   const parsed$ = safeParse4(request, (value$) => GetAvailableModelsByTypeRequest$zodSchema.parse(value$), "Input validation failed");
   if (!parsed$.ok) {
     return [parsed$, { status: "invalid" }];
@@ -54785,7 +55228,7 @@ are returned by default; pass \`include\` to override.`,
         }, { fetchOptions }).$inspect();
         if (!r.ok)
           return errorResult(`sources: ${r.error.message}`);
-        const parsed = await readJson(r.value);
+        const parsed = await readJson(r.value, "Knowledge base listing");
         if (!parsed.ok)
           return parsed.result;
         result["sources"] = (parsed.value.items ?? []).map((n) => ({
@@ -54807,7 +55250,7 @@ are returned by default; pass \`include\` to override.`,
         }, { fetchOptions }).$inspect();
         if (!r.ok)
           return errorResult(`${key}: ${r.error.message}`);
-        const parsed = await readJson(r.value);
+        const parsed = await readJson(r.value, "Model listing");
         if (!parsed.ok)
           return parsed.result;
         result[key] = (parsed.value.models ?? []).map((m) => ({
@@ -54986,31 +55429,39 @@ var init_tool_names = __esm(() => {
     },
     {
       name: "pipeshub_chat",
-      description: `**Primary chat tool — handles both internal knowledge queries and web search.**
-
-**Internal search** (default, \`chatMode: "internal_search"\`): Use whenever
-the user asks about their documents, files, knowledge base, company policies,
-or anything that could plausibly be answered by content in their PipesHub-indexed
-sources (Drive, Box, Confluence, Slack, Gmail, Jira, the org's KB, ...).
-Grounds the answer in the user's actual data and returns citations.
-Answers come from a few retrieved passages, not whole documents — for
-any task needing a document's full content, use
-\`pipeshub_get_record_content\` instead.
-
-**Web search** (\`chatMode: "web_search"\`): Use when the user asks about
-current events, public information, or anything unlikely to be in the org's
-internal knowledge base. Pass \`chatMode: "web_search"\` and this tool will
-search the public web instead.
-
-**When to pick this over other tools:**
-- "Summarize <doc>" / "key points of <doc>" / "what does <document> say
-  about X?" → NOT this tool. Use \`pipeshub_search\` →
-  \`pipeshub_get_record_content\`: answering for a specific document
-  requires its full content, and chat only sees a few retrieved
-  passages, never the whole document.
+      description: `Ask a question, get an answer grounded in the org's indexed data with
+citations. It reads a few retrieved passages — never a whole document,
+never a complete list.
+
+**Three questions this tool gets WRONG. Check them first:**
+- **Structure** — "what's under this epic?", "which pages are in this
+  space?", "what links to this ticket?", "what's in this folder?" →
+  \`pipeshub_get_record_content\` \`mode:"navigate"\`. Ranking cannot see how
+  records relate.
+- **Exhaustive** — "how many X?", "list ALL the Y", "every Z" →
+  \`mode:"navigate"\`, which reports the group's real total. This tool
+  undercounts and will not say so.
+- **One named document** — summarize it, extract from it, what does it say
+  about X → \`pipeshub_search\` for the \`recordId\`, then \`mode:"content"\`.
+
+Everything else about the org's knowledge belongs here: policies,
+processes, decisions, history, "what do we know about X", and any question
+spanning several documents.
+
+**Internal search** (default, \`chatMode: "internal_search"\`): the user's
+documents, files, knowledge base, company policies — anything in their
+PipesHub-indexed sources (Drive, Box, Confluence, Slack, Gmail, Jira, the
+org's KB, ...).
+
+**Web search** (\`chatMode: "web_search"\`): current events or public
+information unlikely to be in the org's knowledge base.
+
+Both are plain-chat modes. **Agent chat** — pass an \`agentId\` from
+\`pipeshub_agents\` — runs against that agent's own prompt, tools and knowledge;
+\`quick\` is its only mode, requires the \`agentId\`, and is sent automatically.
+
 - "What's our policy on Y?" → \`pipeshub_chat\` (internal_search)
 - "What's in the news about Z?" → \`pipeshub_chat\` (web_search)
-- "What is the latest version of <library>?" → \`pipeshub_chat\` (web_search)
 - "Find / locate the file named X" → \`pipeshub_search\` (then
   \`pipeshub_download_record\` if the user wants the bytes).
 
@@ -55049,10 +55500,23 @@ Typical uses:
 - Show the user a ranked list of matching files when they ask "find /
   search for X".
 
+Not for structural questions — what is under this epic, which pages are
+in this space, what links to this ticket. Ranking by content cannot show
+how records relate; use \`pipeshub_get_record_content\` \`mode:"navigate"\`.
+
+**A ranked sample, never a complete list.** Hits are the top-scoring
+blocks from the best-matching records — not all blocks of any record, and
+not every record that matches. Never count them to answer "how many" /
+"all" / "every"; navigate the record group instead, which reports its
+real total.
+
 The response is trimmed to one row per hit:
 \`{ recordId, recordName, score, snippet, mimeType, webUrl, ... }\`.
 Highest \`score\` first; multiple hits may share the same \`recordId\`
-(different chunks of the same record).`
+(different blocks of the same record).
+
+When presenting results to the user, link each record using its
+\`webUrl\` (when present).`
     },
     {
       name: "pipeshub_download_record",
@@ -55060,34 +55524,84 @@ Highest \`score\` first; multiple hits may share the same \`recordId\`
     },
     {
       name: "pipeshub_get_record_content",
-      description: `Read a record's full parsed content by \`recordId\` — the only way to
-see a document's COMPLETE text.
-
-Use it whenever the answer depends on a document's full content — any
-task where missing a part could make the answer wrong: summarize / key
-points / action items; extract or list ALL of something; check whether
-or where the doc mentions X; translate, rewrite, outline, or review the
-doc; compare named docs (fetch each); any question scoped to one named
-document. \`pipeshub_chat\` cannot do these — it only sees a few
-retrieved passages, never the whole document. Get the \`recordId\` from
-a \`pipeshub_search\` top hit or a chat citation.
-
-Judge by the user's INTENT, not their keywords: they need not say
-"summarize", "key points", or "extract". Reason about what a good
-answer requires — if it would need the whole document (e.g. "what's
-this doc about?", "walk me through the report", "anything in here
-about Y?"), that is a full-content task, so call this tool.
-
-Returns a single \`content\` string: a short metadata header (title,
-source, key fields, and a pre-generated summary) followed by the
-record's full parsed text — paragraphs, tables, and lists in reading
-order. For a record with no extractable content, \`content\` is the
-literal \`No record found\`. Use \`pipeshub_download_record\` only when
-you need the original file bytes.`
+      description: `Three operations on the org's records. Pick by what you hold:
+
+  \`mode:"lookup"\`   — a URL, issue key (PA-1787), or external ID
+                    → its recordId plus the record's metadata
+  \`mode:"navigate"\` — a question about structure: what is under X,
+                    what links to Y → browses the hierarchy
+  \`mode:"content"\`  — a recordId, and you need the document's COMPLETE text
+
+**\`mode:"content"\` (default)** — the only way to see a document's complete
+text. Use it whenever missing part of the document could make the answer
+wrong: summarize, extract or list ALL of something, check whether or where
+a doc mentions X, review, or compare named docs. \`pipeshub_chat\` cannot do
+these — it never sees a whole document.
+
+Judge by the user's INTENT, not their keywords: "what's this doc about?",
+"walk me through the report", "anything in here about Y?" are all
+full-content tasks. Get the \`recordId\` from a \`pipeshub_search\` top hit, a
+chat citation, or \`mode:"lookup"\`.
+
+Returns one \`content\` string: a metadata header (title, source, key fields,
+pre-generated summary) then the full parsed text. A record with no
+extractable content returns the literal \`No record found\`. Use
+\`pipeshub_download_record\` only for the original file bytes.
+
+**\`mode:"navigate"\`** — browse the hierarchy: RecordGroup (project /
+space / drive / folder) → Record (epic / story / page / file) → children,
+with breadcrumbs, related links and record IDs.
+
+Use it when the question depends on structure rather than wording: what is
+under this epic, which pages sit in this space, what is linked to this
+ticket, what is in this folder — and every "how many" / "all of" / "every"
+question. Search ranks by content; only this shows how records relate, and
+only this gives a count you can trust.
+
+Omit \`nodeId\` for a flat listing of everything reachable, most recently
+updated first — the usual starting point. A URL, an issue key, or a
+\`pipeshub_sources\` id also works and resolves automatically.
+
+Pass \`depth:2\` or \`depth:3\` to see several levels in ONE call — an epic's
+stories AND their subtasks, a space's pages AND their children — instead of
+one call per level. Use it whenever the question needs an overview of a
+hierarchy rather than a single node.
+
+Opening a record also prints that record's own metadata — for a ticket,
+status, assignee, priority and dates — so a question about one record is
+often answered by this call alone. It returns no document text; for that,
+re-call with \`mode:"content"\`.
+
+Returns \`Path\` breadcrumbs, the current node's metadata, a children listing
+carrying \`record_id=\` or \`node_id=\` per row plus the group's total
+(\`Children 1-50 of 61\`), \`Related\` cross-references, and a \`Next:\` line.
+One page is usually every child, so only pass \`page:2\` when that \`Next:\`
+line says more exist.
+
+**\`mode:"lookup"\`** — turn an external reference into a recordId, the first
+step whenever the question names one. Returns that record's metadata (for a
+ticket: status, assignee, priority, dates) plus its recordId, which
+\`mode:"navigate"\` takes to list what is under it and \`mode:"content"\` takes
+to read it.
+
+Handles Jira keys and URLs, Confluence, Drive, Slack permalinks, Linear,
+Notion, ServiceNow sys_id, SharePoint, Gmail/Outlook, and any connector
+whose records index a web URL. Resolution searches ALL connectors you can
+access, regardless of any source filter you used elsewhere.
+
+A miss is a 200 with empty \`matches\` and the input echoed in
+\`not_found_identifiers\` — that may mean no-access, not non-existence. Use
+\`mode:"navigate"\` to confirm the record exists before telling the user it
+does not. If \`ambiguous\` is true, pick from \`matches\` rather than taking
+the first.
+
+Navigate and lookup return a rendered text view whose closing \`Next:\` line
+names the exact follow-up call — follow it. When presenting a record, link
+it using the \`Web URL\` from its metadata header (when present).`
     },
     {
       name: "pipeshub_directory",
-      description: "Look up people, groups, and teams in PipesHub. One tool with five\nactions — pick the right `action`:\n\n- `whoami` — who is the caller?  Use this whenever you need the\n  authenticated user's own id, email, or full name (e.g. before\n  `get_user` on themselves).\n- `list_users` — search / page through org users.\n- `get_user` — full `User` document for one user (requires `userId`).\n- `list_groups` — list user groups with `userCount`.\n- `list_my_teams` — teams the caller belongs to, with capability flags\n  (`canEdit` / `canDelete` / `canManageMembers`).\n\nOutput shape varies by action; see each action's docs above."
+      description: "Look up people, groups, and teams in PipesHub. One tool with five\nactions — pick the right `action`:\n\n- `whoami` — who is the caller?  Use this whenever you need the\n  authenticated user's own id, email, or full name (e.g. before\n  `get_user` on themselves). Errors if the credential is expired\n  or revoked.\n- `list_users` — search / page through org users.\n- `get_user` — full `User` document for one user (requires `userId`).\n- `list_groups` — list user groups with `userCount`.\n- `list_my_teams` — teams the caller belongs to, with capability flags\n  (`canEdit` / `canDelete` / `canManageMembers`).\n\nOutput shape varies by action; see each action's docs above."
     },
     {
       name: "pipeshub_agents",
@@ -58720,5 +59234,5 @@ export {
   app
 };
 
-//# debugId=59975E6F38134B6C64756E2164756E21
+//# debugId=B3EADAB5212D24DD64756E2164756E21
 //# sourceMappingURL=mcp-server.js.map