@nestr/mcp 0.1.72 → 0.1.89

package/build/tools/index.js

@@ -5,6 +5,27 @@
 import { z } from "zod";
 import { NestrApiError } from "../api/client.js";
 import { appResources } from "../apps/index.js";
+import { getCorrelationId } from "../util/request-context.js";
+import { VERSION } from "../version.js";
+import { PRIME_LABELS, PrimeLabelConflictError, validatePrimeLabels, ensureMeetingModifier } from "./validation.js";
+// Tools exposed on the PUBLIC (unauthenticated) MCP surface. These three make
+// zero authenticated Nestr API calls: nestr_help and nestr_diagnose never touch
+// the API, and nestr_get_me is short-circuited to a guest payload in public mode
+// (see _handleToolCall). Everything else stays behind auth on POST /mcp.
+export const PUBLIC_TOOL_NAMES = new Set([
+    "nestr_help",
+    "nestr_diagnose",
+    "nestr_get_me",
+]);
+// Guest identity returned by nestr_get_me on the public surface. No Nestr API
+// call is made — this is a fixed payload telling the agent it has product-help
+// access only and how to unlock workspace tools.
+export const PUBLIC_GUEST_ME = {
+    authMode: "public",
+    user: null,
+    mode: "guest",
+    hint: "Guest mode: product help only. Add AI credit / sign in for workspace tools.",
+};
 // MCP Apps UI metadata for tools that can render in the completable list app.
 // IMPORTANT: Only use for completable items (tasks, projects, todos, inbox items).
 // Do NOT use for structural nests like roles, circles, metrics, policies, etc.
@@ -82,6 +103,24 @@ const HINT_URL_PATTERNS = [
             return result;
         },
     },
+    // /nests/{id}/search?search=... → nestr_search scoped to that nest with in:{id}
+    {
+        pattern: /^\/nests\/([^/]+)\/search$/,
+        tool: "nestr_search",
+        params: (m, sp, workspaceId) => {
+            const search = sp.get("search") || "";
+            const result = { query: `in:${m[1]} ${search}`.trim() };
+            if (workspaceId)
+                result.workspaceId = workspaceId;
+            return result;
+        },
+    },
+    // /workspaces/{id}/search?search=... → nestr_search at workspace scope
+    {
+        pattern: /^\/workspaces\/([^/]+)\/search$/,
+        tool: "nestr_search",
+        params: (m, sp) => ({ workspaceId: m[1], query: sp.get("search") || "" }),
+    },
     // /nests/{id}/posts → nestr_get_comments
     { pattern: /^\/nests\/([^/]+)\/posts$/, tool: "nestr_get_comments", params: (m) => ({ nestId: m[1] }) },
     // /nests/{id}/tensions → nestr_list_tensions
@@ -89,6 +128,119 @@ const HINT_URL_PATTERNS = [
     // /nests/{id} → nestr_get_nest (must be last — catches all /nests/{id} patterns)
     { pattern: /^\/nests\/([^/]+)$/, tool: "nestr_get_nest", params: (m) => ({ nestId: m[1] }) },
 ];
+const HINT_ENDPOINT_TOOL_MAPPINGS = [
+    {
+        method: "POST",
+        pattern: /^\/nests\/?$/,
+        tool: "nestr_create_nest",
+        pathParamNames: [],
+        bodyParams: new Set([
+            "parentId", "title", "description", "purpose", "labels",
+            "fields", "users", "accountabilities", "domains", "workspaceId",
+        ]),
+    },
+    {
+        method: "POST",
+        pattern: /^\/nests\/([^/]+)\/tensions\/?$/,
+        tool: "nestr_create_tension",
+        pathParamNames: ["nestId"],
+        bodyParams: new Set(["title", "description", "feeling", "needs"]),
+    },
+    {
+        method: "POST",
+        pattern: /^\/nests\/([^/]+)\/tensions\/([^/]+)\/parts\/?$/,
+        tool: "nestr_add_tension_part",
+        pathParamNames: ["nestId", "tensionId"],
+        bodyParams: new Set([
+            "_id", "title", "labels", "description", "purpose",
+            "parentId", "users", "due", "accountabilities", "domains",
+            "roleId", // election mode
+        ]),
+    },
+    // PATCH /parts (body has _id) — propose a change to an existing item.
+    // Same tool as POST /parts (which proposes a new item); the _id discriminates.
+    {
+        method: "PATCH",
+        pattern: /^\/nests\/([^/]+)\/tensions\/([^/]+)\/parts\/?$/,
+        tool: "nestr_add_tension_part",
+        pathParamNames: ["nestId", "tensionId"],
+        bodyParams: new Set([
+            "_id", "title", "labels", "description", "purpose",
+            "parentId", "users", "due", "accountabilities", "domains",
+        ]),
+    },
+    // DELETE /parts (body has _id) — propose deletion of an existing item.
+    // Same tool, with removeNest:true to disambiguate from a change proposal.
+    {
+        method: "DELETE",
+        pattern: /^\/nests\/([^/]+)\/tensions\/([^/]+)\/parts\/?$/,
+        tool: "nestr_add_tension_part",
+        pathParamNames: ["nestId", "tensionId"],
+        bodyParams: new Set(["_id"]),
+        extraParams: { removeNest: true },
+    },
+    {
+        method: "DELETE",
+        pattern: /^\/nests\/([^/]+)\/tensions\/([^/]+)\/?$/,
+        tool: "nestr_delete_tension",
+        pathParamNames: ["nestId", "tensionId"],
+        bodyParams: new Set([]),
+    },
+];
+/** Strip optional host + /api prefix so we match against canonical routes. */
+function normalizeEndpointPath(path) {
+    const hostStripped = path.replace(/^https?:\/\/[^/]+/, "");
+    return hostStripped.replace(/^\/api(?=\/)/, "");
+}
+/**
+ * Translate one API hint endpoint into an MCP tool-call suggestion.
+ * Returns null for routes we don't have a mapping for — never guesses a tool.
+ */
+export function translateEndpoint(endpoint) {
+    if (!endpoint || typeof endpoint !== "object")
+        return null;
+    const method = (endpoint.method || "").toUpperCase();
+    if (!method)
+        return null;
+    const path = normalizeEndpointPath(endpoint.path || "");
+    for (const mapping of HINT_ENDPOINT_TOOL_MAPPINGS) {
+        if (mapping.method !== method)
+            continue;
+        const match = path.match(mapping.pattern);
+        if (!match)
+            continue;
+        const parametersExample = {};
+        mapping.pathParamNames.forEach((name, i) => {
+            parametersExample[name] = match[i + 1];
+        });
+        if (mapping.extraParams)
+            Object.assign(parametersExample, mapping.extraParams);
+        const droppedFields = [];
+        const body = endpoint.body_example;
+        if (body && typeof body === "object" && !Array.isArray(body)) {
+            for (const [key, value] of Object.entries(body)) {
+                if (mapping.bodyParams.has(key)) {
+                    parametersExample[key] = value;
+                }
+                else {
+                    droppedFields.push(key);
+                }
+            }
+        }
+        const toolCall = {
+            tool: mapping.tool,
+            purpose: endpoint.purpose,
+            parametersExample,
+        };
+        if (droppedFields.length > 0) {
+            toolCall.notes =
+                `Body fields not exposed by ${mapping.tool} (set these manually if needed): ` +
+                    droppedFields.join(", ");
+        }
+        return toolCall;
+    }
+    return null;
+}
 // Enrich hints with tool call parameters so models can act on hints directly.
 // Extracts workspaceId from nest ancestors (last element) for search-based hints.
 export function enrichHints(data) {
@@ -109,28 +261,91 @@ export function enrichHints(data) {
         const ancestors = record.ancestors;
         const workspaceId = ancestors?.length ? ancestors[ancestors.length - 1] : undefined;
         record.hints = record.hints.map((hint) => {
-            if (!hint.url)
-                return hint;
-            // Parse URL and query params — strip absolute URL prefix if present
-            let rawUrl = hint.url;
-            const apiPrefixMatch = rawUrl.match(/^https?:\/\/[^/]+\/api(\/.*)/);
-            if (apiPrefixMatch)
-                rawUrl = apiPrefixMatch[1];
-            const [path, queryString] = rawUrl.split("?");
-            const searchParams = new URLSearchParams(queryString || "");
-            for (const { pattern, tool, params } of HINT_URL_PATTERNS) {
-                const match = path.match(pattern);
-                if (match) {
-                    return { ...hint, toolCall: { tool, params: params(match, searchParams, workspaceId) } };
+            const enriched = { ...hint };
+            // Legacy: single URL → toolCall. Kept for backwards compatibility with
+            // hints that pre-date the endpoints[] payload.
+            if (hint.url) {
+                let rawUrl = hint.url;
+                const apiPrefixMatch = rawUrl.match(/^https?:\/\/[^/]+\/api(\/.*)/);
+                if (apiPrefixMatch)
+                    rawUrl = apiPrefixMatch[1];
+                const [path, queryString] = rawUrl.split("?");
+                const searchParams = new URLSearchParams(queryString || "");
+                let matched = false;
+                for (const { pattern, tool, params } of HINT_URL_PATTERNS) {
+                    const match = path.match(pattern);
+                    if (match) {
+                        enriched.toolCall = { tool, params: params(match, searchParams, workspaceId) };
+                        matched = true;
+                        break;
+                    }
+                }
+                if (!matched) {
+                    console.error(`[nestr-mcp] Unrecognized hint URL pattern: "${hint.url}" (hint type: ${hint.type})`);
+                }
+            }
+            // New: endpoints[] → toolCalls[]. Each endpoint becomes one tool-call
+            // suggestion; unmapped routes are dropped silently (no invented tools).
+            if (Array.isArray(hint.endpoints) && hint.endpoints.length > 0) {
+                const toolCalls = hint.endpoints
+                    .map((endpoint) => translateEndpoint(endpoint))
+                    .filter((tc) => tc !== null);
+                if (toolCalls.length > 0) {
+                    enriched.toolCalls = toolCalls;
                 }
             }
-            // Log unrecognized hint URLs so we can add mappings when the API adds new patterns
-            console.error(`[nestr-mcp] Unrecognized hint URL pattern: "${hint.url}" (hint type: ${hint.type})`);
-            return hint;
+            return enriched;
         });
     }
     return data;
 }
+// Canonical web URL for a nest in the Nestr app.
+// Pattern: /n/{parentId}/{id} when a parent context is known, /n/{id} otherwise.
+// Parent 'inbox' is treated as no parent — inbox is not a navigable container.
+const NESTR_WEB_BASE = "https://app.nestr.io";
+function buildNestUrl(id, parentId) {
+    if (parentId && parentId.toLowerCase() !== "inbox") {
+        return `${NESTR_WEB_BASE}/n/${parentId}/${id}`;
+    }
+    return `${NESTR_WEB_BASE}/n/${id}`;
+}
+// Heuristic: does this object look like a nest (vs. a user, label, error, etc.)?
+// Nests have _id plus at least one of parentId, ancestors, or a labels[] array.
+// Workspaces qualify via labels[]; circles/roles/projects/tasks/comments via parentId.
+function looksLikeNest(obj) {
+    if (typeof obj._id !== "string")
+        return false;
+    if ("username" in obj)
+        return false; // users
+    if (typeof obj.parentId === "string")
+        return true;
+    if (Array.isArray(obj.ancestors))
+        return true;
+    if (Array.isArray(obj.labels))
+        return true;
+    return false;
+}
+// Recursively add a `url` field to every nest-shaped object in the response.
+// Walks arrays, wrapped { data: [...] } responses, and any nested object/array
+// values. Skips non-nest shapes (users, labels, errors, tension parts).
+export function addNestUrls(data) {
+    if (!data || typeof data !== "object")
+        return data;
+    if (Array.isArray(data)) {
+        return data.map((item) => addNestUrls(item));
+    }
+    const record = data;
+    const out = { ...record };
+    if (looksLikeNest(record) && typeof out.url !== "string") {
+        out.url = buildNestUrl(record._id, record.parentId);
+    }
+    for (const [key, value] of Object.entries(out)) {
+        if (value && typeof value === "object") {
+            out[key] = addNestUrls(value);
+        }
+    }
+    return out;
+}
 // Coerce JSON-stringified arrays/objects before Zod validation.
 // Some MCP clients send array/object params as JSON strings (e.g., "[\"project\"]" instead of ["project"]).
 const coerceFromJson = (schema) => z.preprocess((val) => {
@@ -144,6 +359,32 @@ const coerceFromJson = (schema) => z.preprocess((val) => {
     }
     return val;
 }, schema);
+// Coerce an integer-array param to number[] even when a client serialises it as
+// a string — e.g. a stale/cached tool schema that doesn't know the array type
+// sends "[4,5,6]", "4,5,6", or a bare 4. Non-numeric tokens are dropped and the
+// wrapped schema validates the rest. Prevents "Expected array, received string".
+const coerceIntArray = (schema) => z.preprocess((val) => {
+    const toNums = (arr) => arr.map(Number).filter(Number.isFinite);
+    if (typeof val === 'number')
+        return [val];
+    if (Array.isArray(val))
+        return toNums(val);
+    if (typeof val === 'string') {
+        const s = val.trim();
+        if (!s)
+            return undefined;
+        try {
+            const parsed = JSON.parse(s);
+            if (Array.isArray(parsed))
+                return toNums(parsed);
+            if (typeof parsed === 'number')
+                return [parsed];
+        }
+        catch { /* not JSON — fall through to delimiter split */ }
+        return toNums(s.replace(/[[\]]/g, '').split(/[\s,]+/).filter(Boolean));
+    }
+    return val;
+}, schema);
 // Tool input schemas using Zod
 export const schemas = {
     listWorkspaces: z.object({
@@ -215,11 +456,13 @@ export const schemas = {
     }),
     addComment: z.object({
         nestId: z.string().describe("Nest ID to comment on"),
-        body: z.string().describe("Comment text (supports HTML and @mentions: @{userId}, @{email}, @{circle})"),
+        body: z.string().describe("Comment text. Supports HTML and @mentions. **Mentions MUST be wrapped in literal curly braces** — write `@{aBcD1234eFgH5678i:roleNestId}`, NOT `@aBcD1234eFgH5678i`. Without the braces the platform will not link the mention or notify the user. Forms: `@{userId:roleId}` (preferred — addresses the user in a specific role/circle), `@{userId}` (legacy — no role context), `@{email}`, `@{circle}` (all role fillers in nearest ancestor circle)."),
+        labels: z.array(z.string()).optional().describe("Optional label IDs to attach to the comment at creation time (e.g., 'decision', 'question', or a custom label ID). Personal labels are auto-scoped to the authenticated user. Use nestr_list_labels / nestr_list_personal_labels to discover IDs."),
     }),
     updateComment: z.object({
         commentId: z.string().describe("Comment ID to update"),
-        body: z.string().describe("Updated comment text (supports HTML and @mentions: @{userId}, @{email}, @{circle})"),
+        body: z.string().describe("Updated comment text. Supports HTML and @mentions. **Mentions MUST be wrapped in literal curly braces** — write `@{aBcD1234eFgH5678i:roleNestId}`, NOT `@aBcD1234eFgH5678i`. Without the braces the platform will not link the mention or notify the user. Forms: `@{userId:roleId}` (preferred — addresses the user in a specific role/circle), `@{userId}` (legacy — no role context), `@{email}`, `@{circle}` (all role fillers in nearest ancestor circle)."),
+        labels: z.array(z.string()).optional().describe("Optional full set of label IDs for the comment. When provided, this REPLACES the comment's existing labels. To incrementally add or remove a single label without replacing the rest, use nestr_add_label / nestr_remove_label with the commentId as the nestId."),
     }),
     deleteComment: z.object({
         commentId: z.string().describe("Comment ID to delete"),
@@ -270,8 +513,8 @@ export const schemas = {
         _listTitle: z.string().optional().describe("Short descriptive title for the list UI (e.g., \"Engineering projects\"). Omit for default."),
     }),
     getComments: z.object({
-        nestId: z.string().describe("Nest ID to get comments from"),
-        depth: z.number().optional().describe("Comment thread depth (default: all)"),
+        nestId: z.string().describe("Nest ID to get comments from. Pass a workspace ID to gather communication across the whole workspace (combine with depth='all')."),
+        depth: z.union([z.number(), z.literal("all")]).optional().describe("How deep below the context nest to look for comments. 0 (default) returns only comments directly on this nest; N includes comments on descendants up to N levels deep; 'all' includes comments on this nest and every descendant. Use 'all' on a workspace or circle nest to analyse large sets of communication in one call."),
     }),
     getCircle: z.object({
         workspaceId: z.string().describe("Workspace ID"),
@@ -425,11 +668,13 @@ export const schemas = {
         description: z.string().optional().describe("The primary content field — detailed information about the item. Supports Markdown and HTML."),
         purpose: z.string().optional().describe("ONLY for roles/circles — a short aspirational statement. Do NOT put detailed information here; use description instead. Supports HTML."),
         parentId: z.string().optional().describe("Parent ID — use to move/restructure items (e.g., move role to different circle)"),
-        users: coerceFromJson(z.array(z.string())).optional().describe("User IDs to assign (e.g., for role elections: assign the elected user to the role)"),
-        due: z.string().optional().describe("Due date / re-election date (ISO format)"),
+        users: coerceFromJson(z.array(z.string())).optional().describe("User IDs to assign. For an election (with roleId), the single user being elected, e.g. [\"userId\"]."),
+        due: z.string().optional().describe("Due date / re-election date (ISO format). For an election (with roleId), the term end — omit to elect without a term."),
         accountabilities: coerceFromJson(z.array(z.string())).optional().describe("Accountability titles to set on a role (replaces all — use children endpoint for individual management)"),
         domains: coerceFromJson(z.array(z.string())).optional().describe("Domain titles to set on a role (replaces all — use children endpoint for individual management)"),
-    }),
+        roleId: z.string().optional().describe("Hold an ELECTION: the electable role to fill (Facilitator/Secretary/Rep Link or any electable role). Assigns or reconfirms the role's filler for a term WITHOUT changing its accountabilities/domains — provide users:[userId] (one person) and optional due (term). Do not combine with _id."),
+        removeNest: z.boolean().optional().describe("Set true with _id to propose deletion of the referenced governance item (when the proposal is accepted, the item is removed). Distinct from nestr_remove_tension_part, which undoes a proposal part you already added. Requires _id; other body fields are ignored."),
+    }).refine((data) => !data.removeNest || !!data._id, { message: "removeNest:true requires _id to identify which item to propose for deletion" }).refine((data) => !data.roleId || (Array.isArray(data.users) && data.users.length === 1), { message: "An election (roleId) requires exactly one user to elect — users: [userId]." }).refine((data) => !(data.roleId && data._id), { message: "Provide either roleId (to hold an election) or _id (to change/delete an existing item), not both." }),
     modifyTensionPart: z.object({
         nestId: z.string().describe("ID of the circle or role the tension belongs to"),
         tensionId: z.string().describe("Tension ID"),
@@ -507,8 +752,13 @@ export const schemas = {
         targetId: z.string().describe("Target nest ID to unlink"),
     }),
     help: z.object({
-        topic: z.string().describe("Topic key (e.g., 'search', 'labels', 'tensions'). Use 'topics' for the full list."),
-    }),
+        topic: z.string().optional().describe("Topic key (e.g., 'search', 'labels', 'tensions'). Use 'topics' for the full list. If the key isn't a known internal topic, it's tried as a help-article slug from nestr.io/help/articles/<slug>; the response's 'Resolved as:' line says which matched."),
+        search: z.string().optional().describe("Free-text query against the public help-article index (nestr.io/help/articles/*). Tolerates typos and common synonyms. Returns ranked matches, each with a title and one-line summary; fetch one with `topic: <slug>`."),
+        includeImages: z.boolean().optional().describe("Help-article mode only. Default false: a fetch returns markdown + a numbered image-URL list, with NO image blocks. Set true to also attach the first maxImages content screenshots as inline image content (base64, downscaled to bound token cost), in document order. Decorative images (uncaptioned, or the header/thumbnail before the first content heading) are never auto-attached — request them by index via imageIndexes. Use when the user wants to *see* how something looks. Ignored for internal topics and search."),
+        imageIndexes: coerceIntArray(z.array(z.number().int().nonnegative()).optional()).describe("Help-article mode only. Attach specific screenshots by their [index] from the numbered 'Images in this article' list shown in the response footer of a prior fetch. Pass an array of integers, e.g. [4,5,6]. Overrides the default selection AND the maxImages cap — exactly these indexes attach, in order (a [decorative] image attaches only when explicitly listed here). Ignored for internal topics and search."),
+        maxImages: coerceFromJson(z.number().int().positive().optional()).describe("Help-article mode only. Cap on how many screenshots the default selection attaches (the first N content images in document order). Default 3, max 6. Ignored when imageIndexes is provided."),
+    }).refine((v) => Boolean(v.topic) || Boolean(v.search), { message: "Provide either `topic` or `search`." }),
+    diagnose: z.object({}).describe("No arguments — diagnose reads session state from the server."),
 };
 // Tool annotations for MCP - hints for clients on tool behavior
 const readOnly = { annotations: { readOnlyHint: true, destructiveHint: false } };
@@ -518,13 +768,25 @@ const destructive = { annotations: { readOnlyHint: false, destructiveHint: true
 export const toolDefinitions = [
     {
         name: "nestr_help",
-        description: "Get detailed Nestr documentation by topic. Call before unfamiliar operations. Topics: search, labels, nest-model, inbox, daily-plan, notifications, insights, tension-processing, skills, mcp-apps, authentication, and more. Use topic 'topics' for the full list.",
+        description: "Get Nestr documentation. Three modes: (1) internal MCP-flavoured topic — pass `topic` with one of the curated keys (search, labels, nest-model, inbox, daily-plan, notifications, insights, tension-processing, skills, mcp-apps, authentication, scrum, okr, ...); use topic 'topics' for the full list. (2) Help-article fetch — pass `topic` with a slug from nestr.io/help/articles/<slug>; returns the article as markdown plus a numbered list of its images (with URLs and captions). Images are NOT attached by default. Pass `includeImages: true` to also attach the first `maxImages` (default 3, max 6) content screenshots as renderable image blocks (downscaled; decorative header/thumbnail/uncaptioned images skipped), or `imageIndexes: [..]` to attach specific ones from the numbered list (e.g. a burndown chart further down, ignoring the cap). Use images when the user wants to *see* how something looks. The tool tries internal topics first, then falls back to article fetch. (3) Help-article search — pass `search` with a free-text query; returns ranked matches, each with a title and one-line summary. Search tolerates typos and common synonyms (e.g. kanban/sprint→scrum). Every response opens with a 'Resolved as:' line stating which mode answered, and internal topics and articles cross-link to each other. Call this before unfamiliar operations. Auth: none required.",
         inputSchema: {
             type: "object",
             properties: {
-                topic: { type: "string", description: "Topic key. Use 'topics' for the full list." },
+                topic: { type: "string", description: "Internal topic key or help-article slug. Use 'topics' for the full list of internal topics." },
+                search: { type: "string", description: "Free-text query against the public help articles. Returns slugs to fetch via `topic`." },
+                includeImages: { type: "boolean", description: "Help-article mode only. Default false (markdown + numbered image-URL list, no image blocks). Set true to attach the first maxImages content screenshots as inline image content (base64, downscaled). Decorative header/thumbnail/uncaptioned images are never auto-attached — use imageIndexes for those. Ignored for internal topics and search." },
+                imageIndexes: { type: "array", items: { type: "integer", minimum: 0 }, description: "Help-article mode only. Attach specific screenshots by their [index] from the numbered 'Images in this article' list in a prior response's footer, e.g. [4,5,6]. Overrides the default selection and the maxImages cap; attaches exactly these indexes in order. Ignored for internal topics and search." },
+                maxImages: { type: "integer", minimum: 1, description: "Help-article mode only. Cap on screenshots in the default selection (first N content images). Default 3, max 6. Ignored when imageIndexes is provided." },
             },
-            required: ["topic"],
+        },
+        ...readOnly,
+    },
+    {
+        name: "nestr_diagnose",
+        description: "Server-side auth and session diagnostics. Call this FIRST when any other tool returns an auth error (AUTH_TOKEN_REJECTED_BY_NESTR / AUTH_REFRESH_FAILED / AUTH_SCOPE_INSUFFICIENT / AUTH_PROXY_HEADER_DROPPED). Returns: flow (A=server-managed refresh, B=client-managed refresh, unknown=API key), tokenPresented, tokenFingerprint, lastUpstream401At, lastRefreshAttempt, sessionCorrelationId, serverVersion, mcpClient, mcpClientVersion. Auth: none required — works whether or not the bearer is valid.",
+        inputSchema: {
+            type: "object",
+            properties: {},
         },
         ...readOnly,
     },
@@ -557,7 +819,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_create_workspace",
-        description: "Create a new workspace. OAuth only. See nestr_help('workspace-setup') for guided setup.",
+        description: "Create a new workspace. Auth: OAuth only (user-scoped — workspace API keys cannot create new workspaces). On auth failure call nestr_diagnose. See nestr_help('workspace-setup') for guided setup.",
         inputSchema: {
             type: "object",
             properties: {
@@ -648,7 +910,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_create_nest",
-        description: "Create a nest under a parent. Use labels to define type (e.g., ['project'], ['role']). For governance changes in established workspaces, prefer the tension flow. See nestr_help('labels') for available types.",
+        description: "Create a nest under a parent. Use labels to define type (e.g., ['project'], ['role']). Apply at most ONE prime label per nest (project, tension, role, circle, anchor-circle, meeting, metric, goal, result, checklist, feedback, userstory, sprint, epic, milestone) — they define the nest's core identity and cannot coexist. Sole exception: userstory may pair with project (userstory implies project); sprint/epic/milestone may not, and stories link to those containers via graph relations instead. For governance changes in established workspaces, prefer the tension flow. See nestr_help('labels') for available types.",
         inputSchema: {
             type: "object",
             properties: {
@@ -691,7 +953,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_update_nest",
-        description: "Update nest properties. Set parentId to move. Only send fields you want to change. For governance changes, prefer tensions. See nestr_help('nest-model') for fields and data namespacing.",
+        description: "Update nest properties. Set parentId to move. Only send fields you want to change. When replacing `labels`, keep at most ONE prime label (project, tension, role, circle, anchor-circle, meeting, metric, goal, result, checklist, feedback, userstory, sprint, epic, milestone) — they define the nest's core identity. Sole exception: userstory may pair with project (userstory implies project). For governance changes, prefer tensions. See nestr_help('nest-model') for fields and data namespacing.",
         inputSchema: {
             type: "object",
             properties: {
@@ -759,12 +1021,17 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_add_comment",
-        description: "Add a comment to a nest. Supports HTML and @mentions (@{userId}, @{email}, @{circle}). Use for progress updates and discussion.",
+        description: "Add a comment to a nest. Supports HTML and @mentions — **mentions MUST be wrapped in literal curly braces** (e.g. `@{aBcD1234eFgH5678i:roleNestId}`, NOT `@aBcD1234eFgH5678i`); without the braces the user is not notified. Prefer `@{userId:roleId}` so the recipient knows which role they're being addressed in. Use for progress updates and discussion. Optionally attach labels at creation time via the `labels` parameter.",
         inputSchema: {
             type: "object",
             properties: {
                 nestId: { type: "string", description: "Nest ID to comment on" },
-                body: { type: "string", description: "Comment text (supports HTML and @mentions: @{userId}, @{email}, @{circle})" },
+                body: { type: "string", description: "Comment text. Supports HTML and @mentions. **Mentions MUST be wrapped in literal curly braces** — write `@{aBcD1234eFgH5678i:roleNestId}`, NOT `@aBcD1234eFgH5678i`. Without the braces the platform will not link the mention or notify the user. Forms: `@{userId:roleId}` (preferred — addresses the user in a specific role/circle), `@{userId}` (legacy — no role context), `@{email}`, `@{circle}` (all role fillers in nearest ancestor circle)." },
+                labels: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional label IDs to attach to the comment at creation time (e.g., 'decision', 'question', or a custom label ID). Personal labels are auto-scoped to the authenticated user. Use nestr_list_labels / nestr_list_personal_labels to discover IDs.",
+                },
             },
             required: ["nestId", "body"],
         },
@@ -772,12 +1039,17 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_update_comment",
-        description: "Update an existing comment's body. Supports HTML and @mentions.",
+        description: "Update an existing comment's body and/or labels. Supports HTML and @mentions — **mentions MUST be wrapped in literal curly braces** (e.g. `@{aBcD1234eFgH5678i:roleNestId}`, NOT `@aBcD1234eFgH5678i`); without the braces the user is not notified. When `labels` is provided it REPLACES the existing label set — use nestr_add_label / nestr_remove_label for incremental changes.",
         inputSchema: {
             type: "object",
             properties: {
                 commentId: { type: "string", description: "Comment ID to update" },
-                body: { type: "string", description: "Updated comment text (supports HTML and @mentions: @{userId}, @{email}, @{circle})" },
+                body: { type: "string", description: "Updated comment text. Supports HTML and @mentions. **Mentions MUST be wrapped in literal curly braces** — write `@{aBcD1234eFgH5678i:roleNestId}`, NOT `@aBcD1234eFgH5678i`. Without the braces the platform will not link the mention or notify the user. Forms: `@{userId:roleId}` (preferred — addresses the user in a specific role/circle), `@{userId}` (legacy — no role context), `@{email}`, `@{circle}` (all role fillers in nearest ancestor circle)." },
+                labels: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional full set of label IDs for the comment. When provided, this REPLACES the comment's existing labels. To incrementally add or remove a single label without replacing the rest, use nestr_add_label / nestr_remove_label with the commentId as the nestId.",
+                },
             },
             required: ["commentId", "body"],
         },
@@ -919,12 +1191,15 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_get_comments",
-        description: "Get comments and discussion history on a nest.",
+        description: "Get comments and discussion history on a nest, including full nested reply threads. By default returns only comments posted directly on the given nest. Widen with depth to also include comments on descendant nests, or pass a workspace/circle nest ID with depth='all' to gather large sets of communication for analysis.",
         inputSchema: {
             type: "object",
             properties: {
-                nestId: { type: "string", description: "Nest ID to get comments from" },
-                depth: { type: "number", description: "Comment thread depth (default: all)" },
+                nestId: { type: "string", description: "Nest ID to get comments from. Pass a workspace ID to gather communication across the whole workspace (combine with depth='all')." },
+                depth: {
+                    oneOf: [{ type: "number" }, { type: "string", enum: ["all"] }],
+                    description: "How deep below the context nest to look for comments. 0 (default) returns only comments directly on this nest; N includes comments on descendants up to N levels deep; 'all' includes comments on this nest and every descendant.",
+                },
             },
             required: ["nestId"],
         },
@@ -1016,7 +1291,7 @@ export const toolDefinitions = [
     // Inbox tools (require OAuth token - won't work with workspace API keys)
     {
         name: "nestr_list_inbox",
-        description: "List items in the user's personal inbox. Spans all workspaces. OAuth only.",
+        description: "List items in the user's personal inbox. Spans all workspaces. Auth: OAuth only (user-scoped — workspace API keys lack user identity). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1029,7 +1304,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_create_inbox_item",
-        description: "Quick capture: add an item to the inbox for later processing. OAuth only.",
+        description: "Quick capture: add an item to the inbox for later processing. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1042,7 +1317,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_get_inbox_item",
-        description: "Get details of a specific inbox item. Requires OAuth token.",
+        description: "Get details of a specific inbox item. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1055,7 +1330,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_update_inbox_item",
-        description: "Update an inbox item. Set completed:true when processed. Use nestr_update_nest with parentId to move out of inbox. OAuth only.",
+        description: "Update an inbox item. Set completed:true when processed. Use nestr_update_nest with parentId to move out of inbox. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1071,7 +1346,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_reorder_inbox",
-        description: "Reorder inbox items. Provide a subset of IDs — they go to the top in given order, rest unchanged. OAuth only.",
+        description: "Reorder inbox items. Provide a subset of IDs — they go to the top in given order, rest unchanged. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1087,7 +1362,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_reorder_inbox_item",
-        description: "Reorder a single inbox item by positioning it before or after another inbox item. Requires OAuth token.",
+        description: "Reorder a single inbox item by positioning it before or after another inbox item. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1102,7 +1377,7 @@ export const toolDefinitions = [
     // Personal labels (require OAuth token - user's own labels, not workspace labels)
     {
         name: "nestr_list_personal_labels",
-        description: "List the current user's personal labels (not workspace labels). OAuth only.",
+        description: "List the current user's personal labels (not workspace labels). Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {},
@@ -1111,7 +1386,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_create_personal_label",
-        description: "Create a personal label. Can be used across workspaces. OAuth only.",
+        description: "Create a personal label. Can be used across workspaces. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1159,7 +1434,7 @@ export const toolDefinitions = [
     // Daily plan (requires OAuth token)
     {
         name: "nestr_get_daily_plan",
-        description: "Get the user's daily plan — items marked for today. Spans all workspaces. OAuth only.",
+        description: "Get the user's daily plan — items marked for today. Spans all workspaces. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1172,7 +1447,7 @@ export const toolDefinitions = [
     // Label management
     {
         name: "nestr_add_label",
-        description: "Add a label to a nest. Personal labels (like 'now') are automatically scoped to the authenticated user by the API.",
+        description: "Add a label to a nest. Personal labels (like 'now') are automatically scoped to the authenticated user by the API. Will reject any attempt to add a prime label (project, tension, role, circle, anchor-circle, meeting, metric, goal, result, checklist, feedback) to a nest that already has one — a nest can only have one core identity.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1198,7 +1473,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_add_to_daily_plan",
-        description: "Add one or more items to the daily plan by applying the 'now' label. Requires OAuth token.",
+        description: "Add one or more items to the daily plan by applying the 'now' label. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1214,7 +1489,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_remove_from_daily_plan",
-        description: "Remove one or more items from the daily plan by removing the 'now' label. Requires OAuth token.",
+        description: "Remove one or more items from the daily plan by removing the 'now' label. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1243,7 +1518,7 @@ export const toolDefinitions = [
     // User tension tools (requires OAuth token)
     {
         name: "nestr_list_my_tensions",
-        description: "List tensions created by or assigned to the current user. Check at session start and natural breakpoints. OAuth only.",
+        description: "List tensions created by or assigned to the current user. Check at session start and natural breakpoints. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1254,7 +1529,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_list_tensions_awaiting_consent",
-        description: "List tensions awaiting the current user's consent vote. Check proactively. OAuth only.",
+        description: "List tensions awaiting the current user's consent vote. Check proactively. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1266,7 +1541,7 @@ export const toolDefinitions = [
     // Notification tools (requires OAuth token)
     {
         name: "nestr_list_notifications",
-        description: "List notifications. Use type 'me' for direct (mentions, replies) or 'relevant' for organizational changes. OAuth only.",
+        description: "List notifications. Use type 'me' for direct (mentions, replies) or 'relevant' for organizational changes. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1281,7 +1556,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_mark_notifications_read",
-        description: "Mark all unread in-app notifications as read for the current user. Returns { status, data: { markedCount } }. Requires OAuth token.",
+        description: "Mark all unread in-app notifications as read for the current user. Returns { status, data: { markedCount } }. Auth: OAuth only (user-scoped). On auth failure call nestr_diagnose.",
         inputSchema: {
             type: "object",
             properties: {},
@@ -1378,7 +1653,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_add_tension_part",
-        description: "Add or modify a governance proposal on a tension. To add new: omit _id. To modify existing: include _id with changed fields. See nestr_help('tension-processing').",
+        description: "Add a governance proposal part to a tension. Four modes: (1) propose a new item — omit _id, provide title/labels/etc.; (2) propose changes to an existing item — provide _id plus the fields to change (note: editing a role this way copies its existing accountabilities/domains into the proposal, so it reads as a full role edit); (3) propose deletion of an existing item — provide _id and removeNest:true; (4) hold an election — provide roleId (the electable role to fill) plus users:[userId] and optional due (term), which assigns/reconfirms the role's filler WITHOUT changing its accountabilities/domains. See nestr_help('tension-processing').",
         inputSchema: {
             type: "object",
             properties: {
@@ -1390,10 +1665,12 @@ export const toolDefinitions = [
                 description: { type: "string", description: "The primary content field — detailed information about the item. Supports Markdown and HTML." },
                 purpose: { type: "string", description: "ONLY for roles/circles — a short aspirational statement. Do NOT put detailed information here; use description instead. Supports HTML." },
                 parentId: { type: "string", description: "Parent ID — use to move/restructure items (e.g., move role to different circle)" },
-                users: { type: "array", items: { type: "string" }, description: "User IDs to assign (e.g., for elections: assign elected user to the role)" },
-                due: { type: "string", description: "Due date / re-election date (ISO format)" },
+                users: { type: "array", items: { type: "string" }, description: "User IDs to assign. For an election (with roleId), the single user being elected, e.g. [\"userId\"]." },
+                due: { type: "string", description: "Due date / re-election date (ISO format). For an election (with roleId), the term end — omit to elect without a term." },
                 accountabilities: { type: "array", items: { type: "string" }, description: "Accountability titles to set on a role (replaces all — use children endpoint for individual management)" },
                 domains: { type: "array", items: { type: "string" }, description: "Domain titles to set on a role (replaces all — use children endpoint for individual management)" },
+                roleId: { type: "string", description: "Hold an ELECTION: the electable role to fill (Facilitator/Secretary/Rep Link or any electable role). Assigns/reconfirms the role's filler for a term WITHOUT changing its accountabilities/domains — provide users:[userId] (one person) and optional due (term). Do not combine with _id." },
+                removeNest: { type: "boolean", description: "Set true with _id to propose deletion of the referenced governance item (when the proposal is accepted, the item is removed). Distinct from nestr_remove_tension_part, which undoes a proposal part you already added." },
             },
             required: ["nestId", "tensionId"],
         },
@@ -1630,32 +1907,208 @@ export function unescapeRichTextFields(args) {
     }
     return changed ? result : args;
 }
-export async function handleToolCall(client, name, args) {
+export async function handleToolCall(client, name, args, context) {
     const sanitizedArgs = unescapeRichTextFields(args);
     const shouldStripDescription = sanitizedArgs.stripDescription === true;
-    const result = await _handleToolCall(client, name, sanitizedArgs);
+    const result = await _handleToolCall(client, name, sanitizedArgs, context);
     if (shouldStripDescription && !result.isError) {
-        try {
-            const parsed = JSON.parse(result.content[0].text);
-            result.content[0].text = JSON.stringify(stripDescriptionFields(parsed), null, 2);
-        }
-        catch {
-            // If parsing fails, return as-is
+        const first = result.content[0];
+        if (first && first.type === "text") {
+            try {
+                const parsed = JSON.parse(first.text);
+                first.text = JSON.stringify(stripDescriptionFields(parsed), null, 2);
+            }
+            catch {
+                // If parsing fails, return as-is
+            }
         }
     }
     return result;
 }
-async function _handleToolCall(client, name, args) {
+async function _handleToolCall(client, name, args, context) {
     try {
+        // PUBLIC surface gate (defense in depth — the public route also filters the
+        // advertised tool list). Refuse anything outside the public allow-list so a
+        // hand-crafted tools/call can never reach an authenticated Nestr path, and
+        // serve nestr_get_me from a fixed guest payload without an API call.
+        if (context?.isPublic) {
+            if (!PUBLIC_TOOL_NAMES.has(name)) {
+                return formatError({
+                    error: true,
+                    code: "AUTH_SCOPE_INSUFFICIENT",
+                    message: `Tool '${name}' is not available on the public Nestr MCP. Guest mode exposes product help only (${[...PUBLIC_TOOL_NAMES].join(", ")}).`,
+                    retryable: false,
+                    hint: "Add AI credit / sign in and connect to the authenticated MCP endpoint to use workspace tools.",
+                });
+            }
+            if (name === "nestr_get_me") {
+                schemas.getMe.parse(args);
+                return formatResult(PUBLIC_GUEST_ME);
+            }
+        }
         switch (name) {
             case "nestr_help": {
                 const parsed = schemas.help.parse(args);
                 const { HELP_TOPICS } = await import("../help/topics.js");
-                const content = HELP_TOPICS[parsed.topic];
-                if (!content) {
-                    return { content: [{ type: "text", text: `Unknown topic: "${parsed.topic}". Call nestr_help({ topic: "topics" }) to see available topics.` }] };
+                const { relatedArticlesForTopic, relatedTopicForArticle } = await import("../help/cross-links.js");
+                // Search mode: query the public help-article index. Returns a ranked
+                // list of slugs; the caller pulls a specific article with a second
+                // call passing `topic: <slug>`.
+                if (parsed.search) {
+                    const { loadArticleIndex, searchArticleIndex, fetchArticleMeta } = await import("../help/articles.js");
+                    try {
+                        const entries = await loadArticleIndex();
+                        const hits = searchArticleIndex(entries, parsed.search, 8);
+                        if (hits.length === 0) {
+                            return { content: [{ type: "text", text: `_Resolved as: help-article search._\n\nNo help articles matched "${parsed.search}". Try broader terms or a synonym, or call nestr_help({ topic: "topics" }) for internal MCP topics.` }] };
+                        }
+                        // Enrich the top hits with a title + one-line summary so the caller
+                        // can pick the right article without a blind fetch. Best-effort:
+                        // a meta-fetch failure just falls back to the bare slug for that row.
+                        const ENRICH = 5;
+                        const metas = await Promise.allSettled(hits.slice(0, ENRICH).map(h => fetchArticleMeta(h.slug)));
+                        const lines = hits.map((h, i) => {
+                            const settled = i < ENRICH ? metas[i] : undefined;
+                            const meta = settled?.status === "fulfilled" ? settled.value : undefined;
+                            const topic = relatedTopicForArticle(h.slug);
+                            const seeAlso = topic ? ` _(see also internal topic \`${topic}\`)_` : "";
+                            if (meta?.title) {
+                                const summary = meta.description ? ` — ${meta.description}` : "";
+                                return `- \`${h.slug}\` — **${meta.title}**${summary}${seeAlso}`;
+                            }
+                            return `- \`${h.slug}\` — ${h.url}${seeAlso}`;
+                        });
+                        const body = [
+                            `_Resolved as: help-article search._`,
+                            ``,
+                            `Found ${hits.length} help article${hits.length === 1 ? "" : "s"} for "${parsed.search}". Fetch one with nestr_help({ topic: "<slug>" }).`,
+                            ``,
+                            ...lines,
+                        ].join("\n");
+                        return { content: [{ type: "text", text: body }] };
+                    }
+                    catch (err) {
+                        const message = err instanceof Error ? err.message : String(err);
+                        return { content: [{ type: "text", text: `Help-article search failed: ${message}. Internal topics still available via nestr_help({ topic: "topics" }).` }], isError: true };
+                    }
+                }
+                // Topic mode: prefer the curated internal topic; if there's no match,
+                // try the slug as a help article. Network failures on the fallback are
+                // surfaced rather than masked — a stale link is more useful than a
+                // generic "not found". Every branch opens with a "Resolved as:" line so
+                // the caller knows which source answered, even if a slug ever shadows
+                // an internal key.
+                const topic = parsed.topic;
+                const content = HELP_TOPICS[topic];
+                if (content) {
+                    const related = relatedArticlesForTopic(topic);
+                    const footer = related.length
+                        ? `\n\n---\nRelated public help article${related.length === 1 ? "" : "s"} (fetch with nestr_help({ topic: "<slug>" })): ${related.map(s => `\`${s}\``).join(", ")}`
+                        : "";
+                    return { content: [{ type: "text", text: `_Resolved as: internal MCP topic "${topic}"._\n\n${content}${footer}` }] };
+                }
+                const { fetchArticleMarkdown, extractImages, collectArticleImages, selectImageIndexes, clampMaxImages } = await import("../help/articles.js");
+                try {
+                    const article = await fetchArticleMarkdown(topic);
+                    const images = extractImages(article.markdown);
+                    const relatedTopic = relatedTopicForArticle(article.slug);
+                    // Image attachment is opt-in: only when the caller explicitly asks via
+                    // includeImages:true (default selection) or imageIndexes (exact
+                    // entries). A plain fetch returns markdown + the numbered URL list, so
+                    // the agent/user can decide whether the screenshots are worth the
+                    // tokens, then re-call to pull them. Fetch first so the text list can
+                    // mark which entries were attached; best-effort — failures just leave
+                    // the text list, which always carries every image's URL.
+                    const imageOpts = { indexes: parsed.imageIndexes, max: parsed.maxImages };
+                    const hasExplicitIndexes = (parsed.imageIndexes?.length ?? 0) > 0;
+                    const wantImages = parsed.includeImages === true || hasExplicitIndexes;
+                    const selectedCount = wantImages && images.length ? selectImageIndexes(images, imageOpts).length : 0;
+                    const inlined = wantImages && images.length ? await collectArticleImages(images, imageOpts) : [];
+                    const attached = new Set(inlined.map(img => img.index));
+                    // Surface a clear, prominent hint whenever the article has screenshots
+                    // so the caller knows they exist and how to pull them in (images are
+                    // opt-in). Adapts to whether any are already attached.
+                    const cap = clampMaxImages(parsed.maxImages);
+                    const contentCount = images.filter(img => !img.decorative).length;
+                    let imageHint = "";
+                    if (inlined.length > 0) {
+                        const more = images.length - inlined.length;
+                        imageHint = more > 0
+                            ? `_${inlined.length} screenshot${inlined.length === 1 ? "" : "s"} attached below as viewable image${inlined.length === 1 ? "" : "s"}. ${more} more are listed under the article — request any by [index] with imageIndexes:[..]._`
+                            : `_${inlined.length} screenshot${inlined.length === 1 ? "" : "s"} attached below as viewable image${inlined.length === 1 ? "" : "s"}._`;
+                    }
+                    else if (contentCount > 0) {
+                        imageHint = `_This article has ${contentCount} screenshot${contentCount === 1 ? "" : "s"} you can view — not attached by default. Re-call nestr_help with includeImages:true to attach the first ${cap}, or imageIndexes:[..] for specific ones (see the numbered list below)._`;
+                    }
+                    const parts = [
+                        `_Resolved as: help article "${article.slug}" (fetched from ${article.url})._`,
+                        ``,
+                        `# ${article.title || article.slug}`,
+                    ];
+                    if (article.description)
+                        parts.push(``, `> ${article.description}`);
+                    if (imageHint)
+                        parts.push(``, imageHint);
+                    parts.push(``, article.markdown);
+                    if (images.length) {
+                        parts.push(``, `---`, `Images in this article (${images.length}) — [index] is stable; [decorative] = header/thumbnail (not auto-attached). Attach with includeImages:true (first ${cap} content images) or imageIndexes:[..]:`, ...images.map((img, i) => {
+                            const tag = img.decorative ? " [decorative]" : "";
+                            const captionText = img.caption ? `"${img.caption}"` : "(no caption)";
+                            const mark = attached.has(i) ? " — attached inline below" : "";
+                            return `- [${i}]${tag} ${captionText} — ${img.url}${mark}`;
+                        }));
+                        if (wantImages && inlined.length === 0) {
+                            const why = selectedCount === 0
+                                ? (parsed.imageIndexes?.length ? "the requested imageIndexes were out of range" : "this article has no non-decorative content screenshots")
+                                : "the selected images could not be fetched";
+                            parts.push(``, `_(No images attached — ${why}.)_`);
+                        }
+                    }
+                    if (relatedTopic) {
+                        parts.push(``, `---`, `Related internal MCP topic (agent-flavoured tool-call guidance): \`${relatedTopic}\` — fetch with nestr_help({ topic: "${relatedTopic}" }).`);
+                    }
+                    parts.push(``, `---`, `Source: ${article.url}`);
+                    const content = [{ type: "text", text: parts.join("\n") }];
+                    for (const img of inlined) {
+                        content.push({ type: "image", data: img.data, mimeType: img.mimeType });
+                    }
+                    return { content };
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    return { content: [{ type: "text", text: `_Resolved as: not found._\n\nUnknown topic: "${topic}". Tried internal topics (call nestr_help({ topic: "topics" }) for the full list) and the help-article fetch (failed: ${message}). To search the help site instead, call nestr_help({ search: "<query>" }).` }] };
                 }
-                return { content: [{ type: "text", text: content }] };
+            }
+            case "nestr_diagnose": {
+                schemas.diagnose.parse(args);
+                const snapshot = context?.getDiagnose?.();
+                const correlationId = getCorrelationId();
+                const result = {
+                    serverVersion: VERSION,
+                    correlationId,
+                    // No request context (e.g. stdio mode): we still report the basic facts.
+                    flow: snapshot?.flow ?? "unknown",
+                    tokenPresented: snapshot?.tokenPresented ?? false,
+                    tokenFingerprint: snapshot?.tokenFingerprint ?? "none",
+                    tokenAge: snapshot?.tokenAge ?? null,
+                    lastUpstream401At: snapshot?.lastUpstream401At
+                        ? new Date(snapshot.lastUpstream401At).toISOString()
+                        : null,
+                    lastRefreshAttempt: snapshot?.lastRefreshAttempt
+                        ? {
+                            at: new Date(snapshot.lastRefreshAttempt.at).toISOString(),
+                            success: snapshot.lastRefreshAttempt.success,
+                            error: snapshot.lastRefreshAttempt.error,
+                        }
+                        : null,
+                    sessionCorrelationId: snapshot?.sessionCorrelationId,
+                    authMode: snapshot?.isApiKey ? "api-key" : snapshot?.tokenPresented ? "oauth" : "none",
+                    mcpClient: snapshot?.mcpClient,
+                    mcpClientVersion: snapshot?.mcpClientVersion,
+                    userId: snapshot?.userId,
+                    hint: buildDiagnoseHint(snapshot),
+                };
+                return formatResult(result);
             }
             case "nestr_list_workspaces": {
                 const parsed = schemas.listWorkspaces.parse(args);
@@ -1713,6 +2166,8 @@ async function _handleToolCall(client, name, args) {
             }
             case "nestr_create_nest": {
                 const parsed = schemas.createNest.parse(args);
+                validatePrimeLabels(parsed.labels);
+                parsed.labels = ensureMeetingModifier(parsed.labels);
                 const hasGovernanceLabels = parsed.labels?.some(l => ["role", "circle"].includes(l));
                 const hasInlineGovernance = parsed.accountabilities?.length || parsed.domains?.length;
                 // Route to self-organization API when creating roles/circles with accountabilities/domains
@@ -1751,6 +2206,8 @@ async function _handleToolCall(client, name, args) {
             }
             case "nestr_update_nest": {
                 const parsed = schemas.updateNest.parse(args);
+                validatePrimeLabels(parsed.labels);
+                parsed.labels = ensureMeetingModifier(parsed.labels);
                 const hasInlineGovernance = parsed.accountabilities?.length || parsed.domains?.length;
                 // Route to self-organization API when updating roles/circles with accountabilities/domains
                 if (hasInlineGovernance && parsed.workspaceId) {
@@ -1797,13 +2254,16 @@ async function _handleToolCall(client, name, args) {
             }
             case "nestr_add_comment": {
                 const parsed = schemas.addComment.parse(args);
-                const post = await client.createPost(parsed.nestId, parsed.body);
+                const post = await client.createPost(parsed.nestId, parsed.body, {
+                    labels: parsed.labels,
+                });
                 return formatResult({ message: "Comment added successfully", post });
             }
             case "nestr_update_comment": {
                 const parsed = schemas.updateComment.parse(args);
                 const updated = await client.updateNest(parsed.commentId, {
                     title: parsed.body,
+                    ...(parsed.labels !== undefined ? { labels: parsed.labels } : {}),
                 });
                 return formatResult({ message: "Comment updated successfully", comment: updated });
             }
@@ -1993,6 +2453,13 @@ async function _handleToolCall(client, name, args) {
             // Label management
             case "nestr_add_label": {
                 const parsed = schemas.addLabel.parse(args);
+                // Only fetch existing labels when applying a prime label — for all
+                // other labels there's no possible conflict, so skip the extra call.
+                if (PRIME_LABELS.has(parsed.labelId)) {
+                    const existing = await client.getNest(parsed.nestId);
+                    const existingNest = Array.isArray(existing) ? existing[0] : existing;
+                    validatePrimeLabels([...(existingNest?.labels ?? []), parsed.labelId]);
+                }
                 const nest = await client.addLabel(parsed.nestId, parsed.labelId);
                 return formatResult({ message: `Label '${parsed.labelId}' added successfully`, nest: compactResponse(nest) });
             }
@@ -2055,8 +2522,8 @@ async function _handleToolCall(client, name, args) {
                 catch (err) {
                     // 401 means the token itself is invalid — propagate so callers don't
                     // see a false "success" here while every other tool fails on the
-                    // same auth state.
-                    if (err instanceof NestrApiError && err.code === "AUTH_FAILED") {
+                    // same auth state. Match by status (any AUTH_* 401 code).
+                    if (err instanceof NestrApiError && err.status === 401) {
                         throw err;
                     }
                     // 403 likely means the token is valid but has no user scope (workspace
@@ -2064,7 +2531,7 @@ async function _handleToolCall(client, name, args) {
                     // endpoint that accepts both OAuth and workspace keys before reporting
                     // "workspace mode" — that way a forbidden coming from anywhere else
                     // (e.g. an unauthorized token that happens to 403) doesn't get masked.
-                    if (err instanceof NestrApiError && err.code === "FORBIDDEN") {
+                    if (err instanceof NestrApiError && err.code === "AUTH_SCOPE_INSUFFICIENT") {
                         const workspaceModeResponse = formatResult({
                             authMode: "api-key",
                             user: null,
@@ -2078,7 +2545,7 @@ async function _handleToolCall(client, name, args) {
                         catch (verifyErr) {
                             // The verification's job is to rule out "this token is bad". An
                             // explicit auth failure on listWorkspaces does that — propagate.
-                            if (verifyErr instanceof NestrApiError && verifyErr.code === "AUTH_FAILED") {
+                            if (verifyErr instanceof NestrApiError && verifyErr.status === 401) {
                                 throw verifyErr;
                             }
                             // Anything else (5xx, network, rate limit) is a transient hiccup
@@ -2134,17 +2601,17 @@ async function _handleToolCall(client, name, args) {
                     description: parsed.description,
                     ...(Object.keys(fields).length > 0 ? { fields } : {}),
                 });
-                return formatResult({ message: "Tension created successfully", tension });
+                return formatResult({ message: "Tension created successfully", tension: enrichHints(tension) });
             }
             case "nestr_get_tension": {
                 const parsed = schemas.getTension.parse(args);
                 const tension = await client.getTension(parsed.nestId, parsed.tensionId, { cleanText: true });
-                return formatResult(tension);
+                return formatResult(enrichHints(tension));
             }
             case "nestr_list_tensions": {
                 const parsed = schemas.listTensions.parse(args);
                 const tensions = await client.listTensions(parsed.nestId, parsed.search, { limit: parsed.limit, order: parsed.order, cleanText: true });
-                return formatResult(compactResponse(tensions));
+                return formatResult(compactResponse(enrichHints(tensions)));
             }
             case "nestr_update_tension": {
                 const parsed = schemas.updateTension.parse(args);
@@ -2172,8 +2639,24 @@ async function _handleToolCall(client, name, args) {
             }
             case "nestr_add_tension_part": {
                 const parsed = schemas.addTensionPart.parse(args);
-                const { nestId, tensionId, ...body } = parsed;
-                if (body._id) {
+                const { nestId, tensionId, removeNest, roleId, ...body } = parsed;
+                if (roleId) {
+                    // Hold an election: assign/reconfirm the role's filler for a term without
+                    // changing its accountabilities/domains. Reuses `users` (the elected person)
+                    // and `due` (the term). The schema guarantees exactly one user here.
+                    const part = await client.createElection(nestId, tensionId, {
+                        roleId,
+                        users: body.users ?? [],
+                        ...(body.due !== undefined ? { due: body.due } : {}),
+                    });
+                    return formatResult({ message: "Election added to the tension successfully", part });
+                }
+                else if (body._id && removeNest === true) {
+                    // Propose deletion of an existing structural item.
+                    const part = await client.proposeTensionDeletion(nestId, tensionId, body._id);
+                    return formatResult({ message: "Deletion proposal added successfully", part });
+                }
+                else if (body._id) {
                     // Propose change to existing item (existing children auto-copied if accountabilities/domains not provided)
                     const part = await client.proposeTensionChange(nestId, tensionId, body);
                     return formatResult({ message: "Change proposal added successfully", part });
@@ -2261,7 +2744,9 @@ async function _handleToolCall(client, name, args) {
         }
     }
     catch (error) {
-        // Handle Nestr API errors with structured response
+        // Handle Nestr API errors with structured response. NestrApiError.toToolError
+        // already attaches the correlationId from the active request context, so no
+        // extra wiring is needed here.
         if (error instanceof NestrApiError) {
             return formatError(error.toToolError());
         }
@@ -2273,6 +2758,18 @@ async function _handleToolCall(client, name, args) {
                 message: error.errors.map(e => `${e.path.join(".")}: ${e.message}`).join("; "),
                 retryable: false,
                 hint: "Check the tool parameters match the expected schema.",
+                correlationId: getCorrelationId(),
+            });
+        }
+        // Prime-label conflicts (e.g. ['project', 'tension'] on one nest)
+        if (error instanceof PrimeLabelConflictError) {
+            return formatError({
+                error: true,
+                code: "VALIDATION",
+                message: error.message,
+                retryable: false,
+                hint: `Prime labels (one per nest): ${[...PRIME_LABELS].join(", ")}. Sole allowed pair: userstory+project (userstory implies project). Drop one label and retry, or create separate nests linked via nestr_add_graph_link (stories link to containers via userstory_sprint / userstory_epic / userstory_milestone).`,
+                correlationId: getCorrelationId(),
             });
         }
         // Handle other errors
@@ -2282,15 +2779,34 @@ async function _handleToolCall(client, name, args) {
             code: "UNKNOWN",
             message,
             retryable: false,
+            correlationId: getCorrelationId(),
         });
     }
 }
+function buildDiagnoseHint(snapshot) {
+    if (!snapshot || !snapshot.tokenPresented) {
+        return "No bearer was presented to the server. The MCP client should run the OAuth flow (or pass an X-Nestr-API-Key header) and retry.";
+    }
+    if (snapshot.lastRefreshAttempt && snapshot.lastRefreshAttempt.success === false) {
+        return "Most recent refresh failed. Tell the user to reconnect Nestr.";
+    }
+    if (snapshot.lastUpstream401At) {
+        if (snapshot.flow === "B") {
+            return "Nestr recently rejected the bearer. For Flow B, refresh is the client's responsibility — the MCP client should call /oauth/token with grant_type=refresh_token, then retry. If refresh also fails, tell the user to reconnect Nestr.";
+        }
+        return "Nestr recently rejected the bearer. Tell the user to reconnect Nestr.";
+    }
+    if (snapshot.tokenAge?.exp && snapshot.tokenAge.exp < snapshot.tokenAge.now) {
+        return "Bearer is expired (exp < now). The client should refresh.";
+    }
+    return "Server-side state looks healthy. If a tool is failing, include sessionCorrelationId in the bug report.";
+}
 function formatResult(data) {
     return {
         content: [
             {
                 type: "text",
-                text: JSON.stringify(data, null, 2),
+                text: JSON.stringify(addNestUrls(data), null, 2),
             },
         ],
     };