@nestr/mcp 0.1.105 → 0.1.107

package/build/tools/index.js

@@ -390,6 +390,43 @@ const HINT_ENDPOINT_TOOL_MAPPINGS = [
         pathParamNames: ["nestId", "tensionId"],
         bodyParams: new Set([]),
     },
+    // Recurrence. One occurrence (`/recurrence/:instant`) before the series routes.
+    {
+        method: "DELETE",
+        pattern: /^\/nests\/([^/]+)\/recurrence\/([^/]+)\/?$/,
+        tool: "nestr_skip_occurrence",
+        pathParamNames: ["nestId", "instant"],
+        bodyParams: new Set([]),
+        queryParams: { scope: "scope" },
+        numericParams: new Set(["instant"]),
+    },
+    {
+        method: "PATCH",
+        pattern: /^\/nests\/([^/]+)\/recurrence\/([^/]+)\/?$/,
+        tool: "nestr_update_occurrence",
+        pathParamNames: ["nestId", "instant"],
+        bodyParams: new Set([
+            "title", "description", "purpose", "parentId", "labels",
+            "fields", "users", "data", "due", "completed",
+        ]),
+        numericParams: new Set(["instant"]),
+    },
+    {
+        method: "GET",
+        pattern: /^\/nests\/([^/]+)\/recurrence\/?$/,
+        tool: "nestr_list_occurrences",
+        pathParamNames: ["nestId"],
+        bodyParams: new Set([]),
+        queryParams: { direction: "direction", cursor: "cursor", limit: "limit" },
+        numericParams: new Set(["cursor", "limit"]),
+    },
+    {
+        method: "DELETE",
+        pattern: /^\/nests\/([^/]+)\/recurrence\/?$/,
+        tool: "nestr_delete_series",
+        pathParamNames: ["nestId"],
+        bodyParams: new Set([]),
+    },
 ];
 /**
  * Strip optional host + /api prefix so we match against canonical routes, and split the
@@ -436,6 +473,13 @@ export function translateEndpoint(endpoint) {
                     value === "true" || value === "false" ? value === "true" : value;
             }
         }
+        // An instant or a limit arrives as URL text; only an all-digit value is a number
+        // (a cursor may also be an ISO date, which stays a string).
+        mapping.numericParams?.forEach((name) => {
+            const value = parametersExample[name];
+            if (typeof value === "string" && /^-?\d+$/.test(value))
+                parametersExample[name] = Number(value);
+        });
         if (mapping.extraParams)
             Object.assign(parametersExample, mapping.extraParams);
         const droppedFields = [];
@@ -492,6 +536,93 @@ export function nestrWebBase(apiBase) {
     return base.replace(/\/api\/?$/, "").replace(/\/+$/, "") || "https://app.nestr.io";
 }
 const NESTR_WEB_BASE = nestrWebBase(process.env.NESTR_API_BASE);
+/**
+ * Turn the tool-level `hints` argument into what the API should be sent.
+ *
+ * `false` means none. A level passes through. `undefined` and `true` both take the
+ * caller-appropriate default, which differs by call shape on purpose: a single read
+ * wants the teaching prose, a listing wants it once from nestr_help rather than once
+ * per row.
+ */
+export function resolveHintLevel(value, fallback) {
+    if (value === false)
+        return false;
+    if (value === "full" || value === "summary")
+        return value;
+    return fallback;
+}
+/**
+ * Append `strict:true` unless the caller already asked for it.
+ *
+ * Without it an unrecognised operator, label or field filter is silently dropped and the
+ * search returns a broader result that looks like a real answer. That is fine for
+ * browsing and wrong for counting, so the tool exposes it as a flag rather than making
+ * every caller remember the operator.
+ */
+export function withStrict(query, strict) {
+    if (!strict)
+        return query;
+    if (/(^|\s)strict:true(\s|$)/i.test(query))
+        return query;
+    return `${query} strict:true`;
+}
+/**
+ * Reduce an OpenAPI document to something a model can read.
+ *
+ * The whole document is far too large to return, and returning nothing useful is how a
+ * caller ends up guessing whether an endpoint exists. So: an operation index by default,
+ * one operation in full when asked for by path, and a keyword filter in between. The
+ * counts matter as much as the rows — "0 of 94 operations match 'duration'" is the
+ * answer to "does the API store meeting duration", and it is a real negative rather than
+ * a failed search.
+ */
+export function summariseApiSpec(spec, filter = {}) {
+    const paths = (spec?.paths || {});
+    const allPaths = Object.keys(paths);
+    if (filter.path) {
+        const match = allPaths.find((p) => { return p === filter.path; })
+            || allPaths.find((p) => { return p.toLowerCase() === filter.path.toLowerCase(); });
+        if (!match) {
+            return {
+                found: false,
+                requested: filter.path,
+                totalPaths: allPaths.length,
+                note: "No such path in this deployment's spec. This is a definitive negative, not a failed lookup.",
+                // Intentionally broad rather than precise: the first path segment, so
+                // `/nests/{id}/nonsense` suggests everything under `/nests/`. A caller who got the
+                // path wrong usually has the resource right, and a wide list they can scan beats a
+                // narrow one that misses the route they meant. Capped so it stays readable.
+                didYouMean: allPaths.filter((p) => { return p.includes(filter.path.split("/")[1] || ""); }).slice(0, 10),
+            };
+        }
+        return { found: true, path: match, operations: paths[match] };
+    }
+    const rows = [];
+    for (const p of allPaths) {
+        for (const [method, op] of Object.entries(paths[p] || {})) {
+            if (typeof op !== "object" || op === null)
+                continue;
+            const summary = (op.summary || op.description || "").split("\n")[0].slice(0, 160);
+            rows.push({ method: method.toUpperCase(), path: p, summary });
+        }
+    }
+    const needle = filter.search?.toLowerCase();
+    const matched = needle
+        ? rows.filter((r) => {
+            return r.path.toLowerCase().includes(needle) || r.summary.toLowerCase().includes(needle);
+        })
+        : rows;
+    return {
+        totalOperations: rows.length,
+        matchedOperations: matched.length,
+        ...(needle ? { query: filter.search } : {}),
+        ...(needle && matched.length === 0
+            ? { note: `No operation mentions "${filter.search}". This deployment does not serve one, which is a definitive answer rather than a failed search.` }
+            : {}),
+        operations: matched.slice(0, 200),
+        ...(matched.length > 200 ? { truncated: true } : {}),
+    };
+}
 export function enrichHints(data) {
     if (!data || typeof data !== "object")
         return data;
@@ -690,6 +821,30 @@ const coerceFromJson = (schema) => z.preprocess((val) => {
     }
     return val;
 }, schema);
+// The instant an occurrence keys on, as integer epoch milliseconds. An ISO-8601 date
+// is accepted only with an explicit Z or offset: without one this host's timezone
+// would silently decide the instant.
+const occurrenceInstant = z.union([z.number(), z.string()]).transform((val, ctx) => {
+    const refuse = (message) => {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message });
+        return z.NEVER;
+    };
+    const useListing = "Use the `instant` value from nestr_list_occurrences (integer epoch milliseconds)";
+    if (typeof val === "number") {
+        return Number.isInteger(val) ? val : refuse(`not an instant: ${val}. ${useListing}.`);
+    }
+    const text = val.trim();
+    if (/^-?\d+$/.test(text))
+        return Number(text);
+    const at = Date.parse(text);
+    if (!Number.isFinite(at)) {
+        return refuse(`not an instant: "${val}". ${useListing}, or an ISO-8601 date with a Z or an offset.`);
+    }
+    if (!/T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})$/i.test(text)) {
+        return refuse(`"${val}" has no timezone, so which instant it means depends on where this server runs. ${useListing}, or give the date with a Z or an offset.`);
+    }
+    return at;
+});
 // 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
@@ -723,9 +878,73 @@ const MENTION_DESC = "Supports HTML and @mentions. Mentions MUST use literal cur
 const PRIME_LABEL_RULE = "At most ONE prime label per nest (project, tension, role, circle, anchor-circle, meeting, metric, goal, result, checklist, feedback, userstory, sprint, epic, milestone): they are the nest's identity and cannot coexist. Only exception: userstory may pair with project.";
 const PURPOSE_DESC = "Only for workspaces, circles and roles: a short aspirational statement. Details belong in description, not here. Supports HTML.";
 const CONTENT_DESC = "The primary content field: details, context, acceptance criteria. Structured data goes in fields, progress in comments. Supports Markdown and HTML.";
+// The editable fields of PATCH /nests/:id, shared by nestr_update_nest and
+// nestr_update_occurrence so the two cannot drift apart.
+const nestUpdateFieldSchemas = {
+    title: z.string().optional().describe("New title (plain text, HTML stripped)"),
+    description: z.string().optional().describe("The primary content field — use for project details, task context, acceptance criteria, and any detailed information. Supports Markdown and HTML."),
+    purpose: z.string().optional().describe(PURPOSE_DESC),
+    parentId: z.string().optional().describe("New parent ID (move nest to different location, e.g., move inbox item to a role or project)"),
+    labels: coerceFromJson(z.array(z.string())).optional().describe("Label IDs to set (e.g., ['project'] to convert an item into a project)"),
+    fields: coerceFromJson(z.record(z.unknown())).optional().describe("Field updates (e.g., { 'project.status': 'Current' })"),
+    users: coerceFromJson(z.array(z.string())).optional().describe("User IDs to assign"),
+    data: coerceFromJson(z.record(z.unknown())).optional().describe("Key-value data store shared with Nestr internals — never overwrite existing keys. Namespace your own data under 'mcp.' (e.g., { 'mcp.lastSync': '...' }). For AI knowledge persistence, use skills instead."),
+    due: z.string().optional().describe("Due date (ISO format). For projects/tasks: deadline. For roles: re-election date. For meetings: start time."),
+    completed: z.boolean().optional().describe("Mark task as completed (root-level field, not in fields). Note: Projects use fields['project.status'] = 'Done' instead."),
+};
+const NEST_UPDATE_FIELD_PROPERTIES = {
+    title: { type: "string", description: "New title (plain text, HTML tags stripped)" },
+    description: { type: "string", description: CONTENT_DESC },
+    purpose: { type: "string", description: PURPOSE_DESC },
+    parentId: { type: "string", description: "New parent ID (move nest to different location)" },
+    labels: {
+        type: "array",
+        items: { type: "string" },
+        description: "Label IDs to set (e.g., ['project'] to convert an item into a project)",
+    },
+    fields: {
+        type: "object",
+        description: "Field updates (e.g., { 'project.status': 'Current' })",
+    },
+    users: {
+        type: "array",
+        items: { type: "string" },
+        description: "User IDs to assign",
+    },
+    data: {
+        type: "object",
+        description: "Key-value data store shared with Nestr internals — never overwrite existing keys. Namespace your own data under 'mcp.' (e.g., { 'mcp.lastSync': '...' }). For AI knowledge persistence, use skills instead.",
+    },
+    due: {
+        type: "string",
+        description: "Due date (ISO format). For projects/tasks: deadline. For roles: re-election date. For meetings: start time.",
+    },
+    completed: {
+        type: "boolean",
+        description: "Mark task as completed (root-level field, not in fields). Note: Projects use fields['project.status'] = 'Done' instead.",
+    },
+};
+const HINTS_DESC = "Contextual hints. 'summary' keeps the per-nest signal (type, severity, count, url, and the "
+    + "`query` that finds every other nest with the same problem) and drops the fixed teaching prose "
+    + "and endpoint list. 'full' is the whole payload. false for none.";
 const STRIP_DESCRIPTION = "Strip description fields to shrink the response. Use for bulk or index reads.";
 const SORT_DESCRIPTION = "Sort field: title, createdAt, updatedAt, due, activityAt, order. Prefix '-' to reverse. For 'recently active' use '-activityAt' (includes children), not '-updatedAt' (own edits only).";
 // Tool input schemas using Zod
+/**
+ * `hints` is a level, not a flag. `summary` keeps what varies per nest and drops the
+ * teaching prose and endpoint list, which are identical for every nest of a type; `full`
+ * is the whole payload. Booleans still work: the API reads a bare `true` on a listing as
+ * `summary`, which is the difference between one paragraph and fifty copies of it.
+ */
+const hintLevelSchema = z.union([z.boolean(), z.enum(["full", "summary"])]).optional();
+const hintFilterSchemas = {
+    hintTypes: coerceFromJson(z.array(z.string())).optional()
+        .describe("Keep only these hint types, e.g. ['project_waiting_no_reason','unassigned_role']."),
+    minSeverity: z.enum(["info", "suggestion", "warning", "alert"]).optional()
+        .describe("Drop hints below this severity. 'warning' is the useful floor when sweeping."),
+};
+const linkedUsersSchema = z.boolean().optional()
+    .describe("Resolve every user id in the results to a full user, returned once in linked.users.");
 export const schemas = {
     listWorkspaces: z.object({
         search: z.string().optional().describe("Search query to filter workspaces"),
@@ -790,6 +1009,8 @@ export const schemas = {
     search: z.object({
         workspaceId: z.string().describe("Workspace ID to search in"),
         query: z.string().describe("Search query"),
+        strict: z.boolean().optional().describe("Reject the search if any operator, label or field filter in it was not recognised, instead of silently returning a broader result. Use it whenever you are counting rather than browsing: without it a typo'd filter reads as a real, larger answer."),
+        linkedUsers: linkedUsersSchema,
         sort: z.string().optional().describe(`${SORT_DESCRIPTION} Takes precedence over sort:/sort-order: operators in the query.`),
         limit: z.number().optional().describe("Max results per page. Omit on first call to see meta.total count."),
         page: z.number().optional().describe("Page number (1-indexed) for pagination"),
@@ -798,7 +1019,8 @@ export const schemas = {
     getNest: z.object({
         nestId: z.string().describe("Nest ID. Supports comma-separated IDs to fetch multiple nests in one call (e.g., 'id1,id2,id3') — returns an array instead of a single object. Keep total URL under 2000 chars to avoid HTTP limits."),
         fieldsMetaData: z.boolean().optional().describe("Set to true to include field schema metadata (e.g., available options for project.status)"),
-        hints: z.boolean().optional().describe("Include contextual hints on each nest (default: true). Hints surface actionable signals like unassigned roles, stale projects, or unread comments. Set to false for bulk lookups where you only need structural data, not contextual guidance."),
+        hints: hintLevelSchema.describe("Contextual hints: 'full' (default on a single read), 'summary', or false. 'summary' keeps type, severity, count, url and the sibling query, and drops the teaching prose and endpoints. Hints surface signals like unassigned roles, stale projects or unread comments."),
+        ...hintFilterSchemas,
         provenance: z.boolean().optional().describe("Single-nest only. Include field/property provenance: which label (and circle context) defines each field and property."),
         rights: z.boolean().optional().describe("Single-nest only. Include the caller's composed rights on the nest plus a deny trace naming the profiles that block each op."),
         forUser: z.string().optional().describe("Single nest, with rights=true. Rights for this user id instead of the caller. Caller must be a nest admin."),
@@ -811,12 +1033,25 @@ export const schemas = {
     }),
     getNestChildren: z.object({
         nestId: z.string().describe("Parent nest ID"),
+        search: z.string().optional().describe("Search scoped to this nest, full operator syntax. Ask for the subset you want rather than fetching every child and filtering: 'label:role' for a circle's roles, 'label:project fields.project.status:Waiting' for its waiting projects. depth:1 is applied when you set no depth, and the response says so in appliedDefaults."),
         sort: z.string().optional().describe(SORT_DESCRIPTION),
         limit: z.number().optional().describe("Max results per page. Omit to see full count in meta.total."),
         page: z.number().optional().describe("Page number for pagination"),
-        hints: z.boolean().optional().describe("Include contextual hints on each child nest (default: true). Set to false for large result sets or bulk operations where contextual signals aren't needed."),
+        hints: hintLevelSchema.describe("Contextual hints: 'summary' (default on a listing), 'full', or false. A listing at 'full' repeats the same teaching prose once per row."),
+        ...hintFilterSchemas,
+        linkedUsers: linkedUsersSchema,
         _listTitle: z.string().optional().describe("Short descriptive title for the list UI (e.g., \"Tasks for Website Redesign\"). Omit for default."),
     }),
+    hintsRollup: z.object({
+        nestId: z.string().describe("Nest to roll up. A circle or workspace root is the useful scope."),
+        hintTypes: coerceFromJson(z.array(z.string())).optional().describe("Count only these hint types."),
+        minSeverity: z.enum(["info", "suggestion", "warning", "alert"]).optional().describe("Drop rules below this severity."),
+        sampleSize: z.number().optional().describe("Example nests per type. Default 10, max 100, 0 for counts only."),
+    }),
+    apiSpec: z.object({
+        search: z.string().optional().describe("Filter operations by keyword against path and summary, e.g. 'meeting' or 'tension'."),
+        path: z.string().optional().describe("Return the full schema for one path, e.g. '/nests/{id}/children'."),
+    }),
     createNest: z.object({
         parentId: z.string().describe("Parent nest ID (workspace, circle, or project)"),
         title: z.string().describe("Title of the new nest (plain text, HTML stripped)"),
@@ -832,16 +1067,7 @@ export const schemas = {
     }),
     updateNest: z.object({
         nestId: z.string().describe("Nest ID to update"),
-        title: z.string().optional().describe("New title (plain text, HTML stripped)"),
-        description: z.string().optional().describe("The primary content field — use for project details, task context, acceptance criteria, and any detailed information. Supports Markdown and HTML."),
-        purpose: z.string().optional().describe(PURPOSE_DESC),
-        parentId: z.string().optional().describe("New parent ID (move nest to different location, e.g., move inbox item to a role or project)"),
-        labels: coerceFromJson(z.array(z.string())).optional().describe("Label IDs to set (e.g., ['project'] to convert an item into a project)"),
-        fields: coerceFromJson(z.record(z.unknown())).optional().describe("Field updates (e.g., { 'project.status': 'Current' })"),
-        users: coerceFromJson(z.array(z.string())).optional().describe("User IDs to assign"),
-        data: coerceFromJson(z.record(z.unknown())).optional().describe("Key-value data store shared with Nestr internals — never overwrite existing keys. Namespace your own data under 'mcp.' (e.g., { 'mcp.lastSync': '...' }). For AI knowledge persistence, use skills instead."),
-        due: z.string().optional().describe("Due date (ISO format). For projects/tasks: deadline. For roles: re-election date. For meetings: start time."),
-        completed: z.boolean().optional().describe("Mark task as completed (root-level field, not in fields). Note: Projects use fields['project.status'] = 'Done' instead."),
+        ...nestUpdateFieldSchemas,
         accountabilities: coerceFromJson(z.array(z.string())).optional().describe("Accountability titles for roles/circles (replaces existing). Only used when updating a role or circle. Requires workspaceId."),
         domains: coerceFromJson(z.array(z.string())).optional().describe("Domain titles for roles/circles (replaces existing). Only used when updating a role or circle. Requires workspaceId."),
         workspaceId: z.string().optional().describe("Workspace ID. Required when updating accountabilities or domains on roles/circles."),
@@ -880,6 +1106,7 @@ export const schemas = {
         sort: z.string().optional().describe(SORT_DESCRIPTION),
         limit: z.number().optional().describe("Max results per page. Omit to see full count in meta.total."),
         page: z.number().optional().describe("Page number for pagination"),
+        linkedUsers: linkedUsersSchema,
     }),
     listUserRoles: z.object({
         userId: z.string().optional().describe("User ID to look up. Omit for yourself. Requires workspaceId when set."),
@@ -914,6 +1141,7 @@ export const schemas = {
         sort: z.string().optional().describe(SORT_DESCRIPTION),
         limit: z.number().optional().describe("Max results per page. Omit to see full count in meta.total."),
         page: z.number().optional().describe("Page number for pagination"),
+        linkedUsers: linkedUsersSchema,
         _listTitle: z.string().optional().describe("Short descriptive title for the list UI (e.g., \"Engineering projects\"). Omit for default."),
     }),
     getComments: z.object({
@@ -949,6 +1177,12 @@ export const schemas = {
     getWorkspaceApps: z.object({
         workspaceId: z.string().describe("Workspace ID"),
     }),
+    workspaceDocs: z.object({
+        workspaceId: z.string().optional(),
+        search: z.string().optional(),
+        fileId: z.string().optional(),
+        offset: z.number().optional(),
+    }),
     // Inbox tools (require OAuth token)
     listInbox: z.object({
         completedAfter: z.string().optional().describe("Include completed items from this date (ISO format). If omitted, only non-completed items are returned. For reordering, this default is usually sufficient — nestr_reorder_inbox only requires the IDs of items you want to reposition."),
@@ -1008,6 +1242,30 @@ export const schemas = {
         workspaceId: z.string().describe("Workspace ID"),
         nestIds: coerceFromJson(z.array(z.string())).describe("Array of nest IDs in the desired order"),
     }),
+    // Schedule / recurrence
+    setRecurrence: z.object({
+        nestId: z.string().describe("Nest ID to set or remove recurrence on"),
+        rrule: z.string().nullable().describe("RFC-5545 RRULE string (e.g. 'FREQ=WEEKLY;BYDAY=MO,WE,FR;COUNT=10') to set recurrence, or null to remove it. Required: pass null explicitly to remove rather than omitting the field."),
+    }),
+    listOccurrences: z.object({
+        nestId: z.string().describe("The series, or any occurrence of it. Both resolve to the same series."),
+        direction: z.enum(["future", "past"]).optional().describe("'future' (default) lists upcoming occurrences, soonest first. 'past' lists history, most recent first."),
+        cursor: z.union([z.number(), z.string()]).optional().describe("Walk outward from this instant, exclusive. Pass back the nextCursor from the previous page. Defaults to now."),
+        limit: z.number().optional().describe("Occurrences per page. Default 10, capped at 50."),
+    }),
+    skipOccurrence: z.object({
+        nestId: z.string().describe("The series, or any occurrence of it."),
+        instant: occurrenceInstant.describe("Which occurrence. Use the `instant` value from nestr_list_occurrences verbatim."),
+        scope: z.enum(["occurrence", "following"]).optional().describe("'occurrence' (default) skips this one and never ends the series. 'following' deletes this one and every later one."),
+    }),
+    updateOccurrence: z.object({
+        nestId: z.string().describe("The series, or any occurrence of it."),
+        instant: occurrenceInstant.describe("Which occurrence. Use the `instant` value from nestr_list_occurrences verbatim."),
+        ...nestUpdateFieldSchemas,
+    }),
+    deleteSeries: z.object({
+        nestId: z.string().describe("The series, or any occurrence of it."),
+    }),
     // Daily plan (requires OAuth token)
     getDailyPlan: z.object({}),
     // Current user identity (requires OAuth token)
@@ -1058,7 +1316,6 @@ export const schemas = {
         sort: z.string().optional().describe(SORT_DESCRIPTION),
         limit: z.number().optional().describe("Max results to return"),
         page: z.number().optional().describe("Page number for pagination"),
-        order: z.string().optional().describe("Deprecated alias of sort"),
     }),
     updateTension: z.object({
         nestId: z.string().describe("ID of the circle or role the tension belongs to"),
@@ -1369,12 +1626,14 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_search",
-        description: "Search nests in a workspace. Supports operators like label:, assignee:, createdby:, completed:, in:, sort:. createdby: accepts me, an email address, or a user id. Always use completed:false for active work. See nestr_help('search') for full syntax. Results carry user ids; when presenting to a person, show names and/or emails, resolving ids via nestr_get_user or nestr_list_users.",
+        description: "Search nests in a workspace. Supports operators like label:, assignee:, createdby:, completed:, in:, sort:. createdby: accepts me, an email address, or a user id. Always use completed:false for active work. See nestr_help('search') for full syntax. Results carry user ids; when presenting to a person, show names and/or emails. Pass `linkedUsers: true` to get them all resolved in the same request rather than calling nestr_get_user per id.",
         inputSchema: {
             type: "object",
             properties: {
                 workspaceId: { type: "string", description: "Workspace ID to search in" },
                 query: { type: "string", description: "Search query with optional operators (e.g., 'label:role', 'assignee:me completed:false')" },
+                strict: { type: "boolean", description: "Reject the search when any operator, label or field filter in it was not recognised, rather than silently returning a broader result. Use it whenever you are counting rather than browsing: without it, a mistyped filter comes back as a real and larger answer with nothing to say the filter was dropped." },
+                linkedUsers: { type: "boolean", description: "Resolve every user id in the results to a full user, returned once in `linked.users`. Prefer this over calling nestr_get_user per id." },
                 sort: { type: "string", description: `${SORT_DESCRIPTION} Takes precedence over sort:/sort-order: operators in the query.` },
                 limit: { type: "number", description: "Max results per page. Omit on the first call so meta.total shows the match count." },
                 page: { type: "number", description: "Page number (1-indexed) for fetching additional pages" },
@@ -1395,7 +1654,9 @@ export const toolDefinitions = [
             properties: {
                 nestId: { type: "string", description: "Nest ID, or comma-separated IDs for a batch (e.g. 'id1,id2'). Keep the URL under 2000 chars." },
                 fieldsMetaData: { type: "boolean", description: "Set to true to include field schema metadata (available options, field types)" },
-                hints: { type: "boolean", description: "Contextual hints, default true. False for bulk lookups needing only structure." },
+                hints: { type: ["string", "boolean"], enum: ["summary", "full", true, false], description: `${HINTS_DESC} Defaults to 'full' on a single read, which is what you want when you asked about one nest.` },
+                hintTypes: { type: "array", items: { type: "string" }, description: "Keep only these hint types." },
+                minSeverity: { type: "string", enum: ["info", "suggestion", "warning", "alert"], description: "Drop hints below this severity." },
                 stripDescription: { type: "boolean", description: STRIP_DESCRIPTION },
                 provenance: { type: "boolean", description: "Single nest. Which label and circle context defines each field and property, e.g. why a role has a given icon." },
                 rights: { type: "boolean", description: "Single nest. The caller's composed rights (self read/update/delete) plus a deny trace naming what blocks each op, and why." },
@@ -1422,15 +1683,19 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_get_nest_children",
-        description: "Get children of a nest. Paginated. Add hints=true for contextual signals.",
+        description: "Get children of a nest, or just the ones you want. Pass `search` with the full operator syntax to ask for a subset rather than fetching everything and filtering: `search: 'label:role'` returns a circle's roles in one call. Paginated at 50 per page; read meta.total for the match count.",
         inputSchema: {
             type: "object",
             properties: {
                 nestId: { type: "string", description: "Parent nest ID" },
+                search: { type: "string", description: "Search scoped to this nest, full operator syntax. Ask for the subset you want instead of fetching every child and filtering: `label:role` for a circle's roles, `label:project fields.project.status:Waiting` for its waiting projects. `depth:1` is applied when you set no depth and the response says so in `appliedDefaults`; pass `depth:2` or higher to reach further down." },
                 sort: { type: "string", description: SORT_DESCRIPTION },
                 limit: { type: "number", description: "Omit on first call to see meta.total count" },
                 page: { type: "number", description: "Page number (1-indexed)" },
-                hints: { type: "boolean", description: "Include contextual hints (default: true). Set to false for large result sets or bulk operations." },
+                hints: { type: ["string", "boolean"], enum: ["summary", "full", true, false], description: `${HINTS_DESC} Defaults to 'summary' here: a listing at 'full' repeats the same paragraph once per row.` },
+                hintTypes: { type: "array", items: { type: "string" }, description: "Keep only these hint types." },
+                minSeverity: { type: "string", enum: ["info", "suggestion", "warning", "alert"], description: "Drop hints below this severity." },
+                linkedUsers: { type: "boolean", description: "Resolve every user id in the results to a full user, returned once in `linked.users`. One request instead of one per id." },
                 stripDescription: { type: "boolean", description: STRIP_DESCRIPTION },
                 _listTitle: { type: "string", description: "Short descriptive title for the list UI header (e.g., \"Tasks for Website Redesign\", \"API project sub-tasks\"). Include the parent name for context." },
             },
@@ -1440,6 +1705,33 @@ export const toolDefinitions = [
         // The completable list app should only be used when results are confirmed to be completable items.
         ...readOnly,
     },
+    {
+        name: "nestr_hints_rollup",
+        description: "Count hints across a whole circle or workspace in one call. A hint on a single nest says \"this one has this problem\"; this says how many have it, which is the question you actually ask of a circle. Answers \"how healthy is this circle\", \"how many projects are waiting with no reason\", \"how many roles have nobody in them\" without reading every nest. Each result carries type, severity, count and a small sample to open. Read `notComputed`: it names every hint type this cannot count in one query, so a type listed there is unknown rather than zero. Do not sum counts across types, one nest can carry several; ask for a single hintTypes when you want a number that adds up.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                nestId: { type: "string", description: "Nest to roll up. A circle or the workspace root is the useful scope." },
+                hintTypes: { type: "array", items: { type: "string" }, description: "Count only these hint types. Omit for every type this can compute." },
+                minSeverity: { type: "string", enum: ["info", "suggestion", "warning", "alert"], description: "Drop rules below this severity. 'warning' is the useful floor for \"what needs attention\"." },
+                sampleSize: { type: "number", description: "Example nests per type. Default 10, max 100, 0 for counts only." },
+            },
+            required: ["nestId"],
+        },
+        ...readOnly,
+    },
+    {
+        name: "nestr_api_spec",
+        description: "The deployment's own OpenAPI document, so you can check whether the API has something rather than concluding \"I did not find it\" and guessing. Call with no arguments for the operation index (method, path, one-line summary). `search` filters by keyword against path and summary. `path` returns the full schema for one operation, including its parameters. Use this to answer \"is there an endpoint for X\" with certainty, and note that a negative here is a real negative: if it is not in the spec, this deployment does not serve it. For the search query language rather than the HTTP surface, use nestr_help('search'); for a filter you are unsure of, `strict: true` on nestr_search tells you whether it applied.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                search: { type: "string", description: "Filter operations by keyword against path and summary, e.g. 'meeting', 'tension', 'duration'." },
+                path: { type: "string", description: "Return the full schema for one path, e.g. '/nests/{id}/children'." },
+            },
+        },
+        ...readOnly,
+    },
     {
         name: "nestr_create_nest",
         description: `Create a nest under a parent. Labels define the type, e.g. ['project'], ['role']. ${PRIME_LABEL_RULE} Sprint/epic/milestone never pair; stories link to those via graph relations. In established workspaces prefer the tension flow for governance. Meetings attach to a circle that ALREADY exists — the workspace anchor circle counts, and is the right parent when no sub-circle fits. Never create a circle to hold a meeting. Use \`['meeting','circle-meeting']\` for a tactical meeting, \`['meeting','governance']\` for a governance meeting, and set \`due\` to the start time. See nestr_help('labels') and nestr_help('meetings').`,
@@ -1494,36 +1786,7 @@ export const toolDefinitions = [
             type: "object",
             properties: {
                 nestId: { type: "string", description: "Nest ID to update" },
-                title: { type: "string", description: "New title (plain text, HTML tags stripped)" },
-                description: { type: "string", description: CONTENT_DESC },
-                purpose: { type: "string", description: PURPOSE_DESC },
-                parentId: { type: "string", description: "New parent ID (move nest to different location)" },
-                labels: {
-                    type: "array",
-                    items: { type: "string" },
-                    description: "Label IDs to set (e.g., ['project'] to convert an item into a project)",
-                },
-                fields: {
-                    type: "object",
-                    description: "Field updates (e.g., { 'project.status': 'Current' })",
-                },
-                users: {
-                    type: "array",
-                    items: { type: "string" },
-                    description: "User IDs to assign",
-                },
-                data: {
-                    type: "object",
-                    description: "Key-value data store shared with Nestr internals — never overwrite existing keys. Namespace your own data under 'mcp.' (e.g., { 'mcp.lastSync': '...' }). For AI knowledge persistence, use skills instead.",
-                },
-                due: {
-                    type: "string",
-                    description: "Due date (ISO format). For projects/tasks: deadline. For roles: re-election date. For meetings: start time.",
-                },
-                completed: {
-                    type: "boolean",
-                    description: "Mark task as completed (root-level field, not in fields). Note: Projects use fields['project.status'] = 'Done' instead.",
-                },
+                ...NEST_UPDATE_FIELD_PROPERTIES,
                 accountabilities: {
                     type: "array",
                     items: { type: "string" },
@@ -1545,7 +1808,7 @@ export const toolDefinitions = [
     },
     {
         name: "nestr_delete_nest",
-        description: "Delete a nest. For governance items in established workspaces, use tensions instead.",
+        description: "Delete a nest. For governance items in established workspaces, use tensions instead. On a recurring item this deletes only that one nest and never ends the series: deleting an occurrence skips it, and deleting the series nest hands the series to its next occurrence, which carries on as the series. To skip an occurrence use nestr_skip_occurrence, to delete it and every later one use nestr_skip_occurrence with scope 'following', and to delete the whole series use nestr_delete_series. The delete is checked against the rights of the person behind the token, including a workspace-bound OAuth or agent token, so a caller who could not delete the nest themselves is refused with 403.",
         inputSchema: {
             type: "object",
             properties: {
@@ -1659,6 +1922,7 @@ export const toolDefinitions = [
                 limit: { type: "number", description: "Omit on first call to see meta.total count" },
                 page: { type: "number", description: "Page number (1-indexed)" },
                 stripDescription: { type: "boolean", description: STRIP_DESCRIPTION },
+                linkedUsers: { type: "boolean", description: "Resolve every user id in the results to a full user, returned once in `linked.users`. One request instead of one per id." },
             },
             required: ["workspaceId"],
         },
@@ -1874,6 +2138,7 @@ export const toolDefinitions = [
                 page: { type: "number", description: "Page number (1-indexed)" },
                 stripDescription: { type: "boolean", description: STRIP_DESCRIPTION },
                 _listTitle: { type: "string", description: "Short descriptive title for the list UI header (e.g., \"Engineering projects\", \"All projects\"). Omit for default." },
+                linkedUsers: { type: "boolean", description: "Resolve every user id in the results to a full user, returned once in `linked.users`. One request instead of one per id." },
             },
             required: ["workspaceId"],
         },
@@ -1891,6 +2156,7 @@ export const toolDefinitions = [
                     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.",
                 },
+                unread: { type: "boolean", description: "true for comments you have not read, false for the ones you have. Omit for all. Combine with depth to sweep a circle for what you have missed." },
             },
             required: ["nestId"],
         },
@@ -2131,6 +2397,94 @@ export const toolDefinitions = [
         },
         ...mutating,
     },
+    {
+        name: "nestr_set_recurrence",
+        description: "Set or remove a task/project/meeting's recurrence rule. Pass an RFC-5545 RRULE string (e.g. 'FREQ=WEEKLY;BYDAY=MO,WE,FR;COUNT=10') to set it, or rrule: null to remove it. Setting a rule creates NO nests: occurrences are computed from the rule and stay virtual until something touches one (completing it, moving its dates, opening it), at which point that occurrence alone becomes a real nest. Do not tell the user their occurrences have been created. The rule expands from the nest's start, or its due when it has no start, and is refused when it has neither, so set a date first. An invalid RRULE is rejected before anything is written. Removing the rule stops future occurrences and keeps anything already materialized, detached from the series. Do not use this to leave out dates: bounding the series with a COUNT or UNTIL and creating a second recurring nest after the gap leaves two nests with the same title, and a later change to the pattern reaches only one of them. To skip an occurrence, use nestr_skip_occurrence; to edit one occurrence, nestr_update_occurrence.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                nestId: { type: "string", description: "Nest ID to set or remove recurrence on" },
+                rrule: {
+                    type: ["string", "null"],
+                    description: "RFC-5545 RRULE string to set recurrence, or null to remove it. Required: pass null explicitly rather than omitting the field.",
+                },
+            },
+            required: ["nestId", "rrule"],
+        },
+        ...mutating,
+    },
+    {
+        name: "nestr_list_occurrences",
+        description: "List the occurrences of a recurring task, project or meeting, so you can name the one you want to act on. This is the ONLY way to see them: occurrences beyond the next one are virtual, meaning the rule produces the instant and no nest exists for it, so nestr_search and nestr_get_nest_children find nothing and asking them is not evidence the occurrences are missing. Returns one page mixing both kinds in date order, each entry carrying `instant` (epoch milliseconds, the key that identifies one occurrence), `virtual` (false means a real nest exists and `nestId` names it), `excluded` (this instant is skipped by the series) and `completed`. Cursor-paged, not page-paged: a rule with no end produces occurrences forever, so there is no total. Pass `nextCursor` back as `cursor` while `hasMore` is true, and `direction: 'past'` to read history. What to do with an `instant`: skip that occurrence with nestr_skip_occurrence (scope 'following' deletes it and every later one), edit that one occurrence with nestr_update_occurrence, or delete the whole series with nestr_delete_series.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                nestId: { type: "string", description: "The series, or any occurrence of it. Both resolve to the same series." },
+                direction: {
+                    type: "string",
+                    enum: ["future", "past"],
+                    description: "'future' (default) lists upcoming occurrences, soonest first. 'past' lists history, most recent first.",
+                },
+                cursor: {
+                    type: ["number", "string"],
+                    description: "Walk outward from this instant, exclusive. Pass back nextCursor from the previous page. Defaults to now.",
+                },
+                limit: { type: "number", description: "Occurrences per page. Default 10, capped at 50." },
+            },
+            required: ["nestId"],
+        },
+        ...readOnly,
+    },
+    {
+        name: "nestr_skip_occurrence",
+        description: "Skip ONE occurrence of a recurring series, or with scope 'following' delete it and every later one. With scope 'occurrence' (the default) it is for the person away that week, the meeting cancelled once, the task that does not apply this time. It excludes that single instant and nothing else. It does NOT end the series (unless the occurrence skipped is the first and nothing follows it, see below), does not change the rule, does not move any other occurrence, and does not destroy history: every past occurrence stays exactly as it was, and the skipped instant stays visible in nestr_list_occurrences marked `excluded`, so the skip is a visible decision rather than a silent gap. If the occurrence already exists as a real nest it is deleted along with the exclusion. The first occurrence is the series item itself: skipping it deletes that nest and hands the series to its next occurrence, which is the series nest from then on, and a series with nothing after it ends; the response then carries `restoreId`, and `seriesId` only when the series carries on. Skipping an instant that is already skipped succeeds and changes nothing. This is NOT the same as splitting the series in two: bounding the rule with a COUNT and creating a second recurring nest after the gap leaves two nests with the same title, and a later edit to the pattern reaches only one of them. Use this instead. With scope 'following' it deletes this occurrence and every later one: the series is split at the instant, the occurrences before it keep their history under a rule that now ends there, and cutting at the first occurrence ends the whole series. It answers with `restoreId`, the nest to restore in the Nestr app: restoring it brings back that nest only, and the occurrences deleted with it are restored separately. `instant` must be an occurrence the series actually has: read it from nestr_list_occurrences and pass it through unchanged. An instant off by a second or by a timezone is refused, not silently accepted. A skip needs update rights on the series, plus delete rights on the occurrence if it already exists as a nest. Skipping the first occurrence deletes the series item itself, so it needs delete rights on the series item. It is refused for workspaces and for governance items unless the caller is a governance admin. Scope 'following' needs delete rights on the series and on every occurrence it removes, and a refusal writes nothing.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                nestId: { type: "string", description: "The series, or any occurrence of it." },
+                instant: {
+                    type: ["number", "string"],
+                    description: "Which occurrence: the `instant` value from nestr_list_occurrences, in epoch milliseconds. An ISO-8601 date is accepted only with a Z or an offset, and must be the exact instant the rule produces.",
+                },
+                scope: {
+                    type: "string",
+                    enum: ["occurrence", "following"],
+                    description: "'occurrence' (default) skips this one occurrence and never ends the series. 'following' deletes this occurrence and every later one, keeping the history before it.",
+                },
+            },
+            required: ["nestId", "instant"],
+        },
+        ...destructive,
+    },
+    {
+        name: "nestr_update_occurrence",
+        description: "Edit ONE occurrence of a recurring series: move this week's meeting, retitle one instance, assign one occurrence to someone else. Takes the same edit fields as nestr_update_nest, but not accountabilities, domains or workspaceId. If the occurrence is still virtual it is materialized first, then the changes are applied to that occurrence only; the rule and every other occurrence are untouched. With no fields it only materializes the occurrence. Answers with the nest: use its `_id` with every other nest tool from then on. Not all-or-nothing: the occurrence is materialized before the changes are applied, so if the edit is refused the occurrence may already exist as a real nest, and nestr_list_occurrences shows its `nestId`. The first occurrence is the series item itself and is refused here: change it with nestr_update_nest on the series nest, which also changes occurrences not created yet. A skipped occurrence is refused too, since there is nothing to change. To change the pattern of the whole series, use nestr_set_recurrence instead. `instant` must be an occurrence the series actually has: read it from nestr_list_occurrences and pass it through unchanged.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                nestId: { type: "string", description: "The series, or any occurrence of it." },
+                instant: {
+                    type: ["number", "string"],
+                    description: "Which occurrence: the `instant` value from nestr_list_occurrences, in epoch milliseconds. An ISO-8601 date is accepted only with a Z or an offset, and must be the exact instant the rule produces.",
+                },
+                ...NEST_UPDATE_FIELD_PROPERTIES,
+            },
+            required: ["nestId", "instant"],
+        },
+        ...mutating,
+    },
+    {
+        name: "nestr_delete_series",
+        description: "Delete a whole recurring series: the series nest and every occurrence, past ones included. Use only when the series and its history should go. To stop repeating but keep the nests, use nestr_set_recurrence with rrule: null. To skip one occurrence, or remove one and every later one while keeping history, use nestr_skip_occurrence. Answers with `restoreId`, the series nest: restoring it in the Nestr app brings back that nest only, and the occurrences deleted with it are restored separately. Needs delete rights on the series and on every occurrence it removes, and a refusal writes nothing. Refused when the nest has no recurrence.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                nestId: { type: "string", description: "The series, or any occurrence of it." },
+            },
+            required: ["nestId"],
+        },
+        ...destructive,
+    },
     // Daily plan (requires OAuth token)
     {
         name: "nestr_get_daily_plan",
@@ -2331,9 +2685,6 @@ export const toolDefinitions = [
                 sort: { type: "string", description: SORT_DESCRIPTION },
                 limit: { type: "number", description: "Max results to return" },
                 page: { type: "number", description: "Page number (1-indexed)" },
-                // The legacy `order` alias is deliberately not advertised — the Zod
-                // schema still accepts it so existing callers keep working, but new
-                // clients should only learn the canonical `sort` param.
             },
             required: ["nestId"],
         },
@@ -2822,6 +3173,20 @@ export const toolDefinitions = [
         },
         ...mutating,
     },
+    {
+        name: "nestr_workspace_docs",
+        description: "The workspace's reference documents: an organisation constitution, a staff handbook, an onboarding guide, whatever this workspace uploaded for its agents to draw on. CALL THIS WITH NO ARGUMENTS FIRST to see what exists — the index lists each document with a description of what it holds and when to read it, and costs almost nothing. Then `search` across them for the passage that answers a question, or `fileId` to read one document. Prefer `search` over reading a whole document: the large ones run past half a million characters, and the answer is usually one section. These are the organisation's own words about how it works, so they outrank your general knowledge about how organisations work; where a document covers the question, quote it rather than reasoning from first principles. Nothing here is guaranteed to exist: a workspace that uploaded nothing returns an empty index, which is an answer, not an error. Auth: any valid token with access to the workspace.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspaceId: { type: "string", description: "Workspace whose documents to read. Omit when you can only reach one." },
+                search: { type: "string", description: "Find the passages across all the documents that match this. Use words the document would use, not the user's phrasing." },
+                fileId: { type: "string", description: "Read one document, from the index or from a search hit." },
+                offset: { type: "number", description: "With fileId, continue from a previous nextOffset, or from a search hit's offset." },
+            },
+        },
+        ...readOnly,
+    },
     {
         name: "nestr_get_nest_files",
         description: "List a nest's file attachments. Images pasted into the nest's text are deliberately excluded — they belong to the text that references them; the inline_images hint counts those and their ids come from the references in the content. A comment ID works too — files are keyed by nestId, so pass a comment ID to see files attached to that comment. Returns each file's id, name, contentType and size. Use nestr_read_file with a returned id to read one (images come back as viewable image content). Auth: any valid token with access to the nest.",
@@ -3219,11 +3584,12 @@ async function _handleToolCall(client, name, args, context) {
             case "nestr_search": {
                 const parsed = schemas.search.parse(args);
                 const directives = extractSearchDirectives(parsed.query);
-                const results = await client.searchWorkspace(parsed.workspaceId, parsed.query, {
+                const results = await client.searchWorkspace(parsed.workspaceId, withStrict(parsed.query, parsed.strict), {
                     sort: parsed.sort ?? directives.sort,
                     limit: parsed.limit ?? directives.limit,
                     page: parsed.page,
                     cleanText: true,
+                    linkedUsers: parsed.linkedUsers,
                 });
                 return formatResult(completableResponse(compactResponse(results), "search", parsed._listTitle || `Search: ${parsed.query}`));
             }
@@ -3232,7 +3598,9 @@ async function _handleToolCall(client, name, args, context) {
                 const nest = await client.getNest(parsed.nestId, {
                     cleanText: true,
                     fieldsMetaData: parsed.fieldsMetaData,
-                    hints: parsed.hints !== false,
+                    hints: resolveHintLevel(parsed.hints, "full"),
+                    hintTypes: parsed.hintTypes,
+                    minSeverity: parsed.minSeverity,
                     provenance: parsed.provenance,
                     rights: parsed.rights,
                     forUser: parsed.forUser,
@@ -3256,14 +3624,32 @@ async function _handleToolCall(client, name, args, context) {
             case "nestr_get_nest_children": {
                 const parsed = schemas.getNestChildren.parse(args);
                 const children = await client.getNestChildren(parsed.nestId, {
+                    search: parsed.search,
                     sort: parsed.sort,
                     limit: parsed.limit,
                     page: parsed.page,
                     cleanText: true,
-                    hints: parsed.hints !== false,
+                    hints: resolveHintLevel(parsed.hints, "summary"),
+                    hintTypes: parsed.hintTypes,
+                    minSeverity: parsed.minSeverity,
+                    linkedUsers: parsed.linkedUsers,
                 });
                 return formatResult(completableResponse(compactResponse(enrichHints(children)), "children", parsed._listTitle || "Sub-items"));
             }
+            case "nestr_hints_rollup": {
+                const parsed = schemas.hintsRollup.parse(args);
+                const rollup = await client.getHintsRollup(parsed.nestId, {
+                    hintTypes: parsed.hintTypes,
+                    minSeverity: parsed.minSeverity,
+                    sampleSize: parsed.sampleSize,
+                });
+                return formatResult(rollup);
+            }
+            case "nestr_api_spec": {
+                const parsed = schemas.apiSpec.parse(args);
+                const spec = await client.getApiSpec();
+                return formatResult(summariseApiSpec(spec, parsed));
+            }
             case "nestr_create_nest": {
                 const parsed = schemas.createNest.parse(args);
                 validatePrimeLabels(parsed.labels);
@@ -3350,8 +3736,17 @@ async function _handleToolCall(client, name, args, context) {
             }
             case "nestr_delete_nest": {
                 const parsed = schemas.deleteNest.parse(args);
-                await client.deleteNest(parsed.nestId);
-                return formatResult({ message: `Nest ${parsed.nestId} deleted successfully` });
+                const response = await client.deleteNest(parsed.nestId);
+                const restoreId = response?.data?.restoreId;
+                // A recurring target answers with a recurring_series hint naming the series routes.
+                const hints = Array.isArray(response?.hints) && response.hints.length > 0
+                    ? enrichHints({ hints: response.hints }).hints
+                    : undefined;
+                return formatResult({
+                    message: `Nest ${parsed.nestId} deleted successfully`,
+                    ...(restoreId ? { restoreId } : {}),
+                    ...(hints ? { hints } : {}),
+                });
             }
             case "nestr_add_comment": {
                 const parsed = schemas.addComment.parse(args);
@@ -3400,6 +3795,7 @@ async function _handleToolCall(client, name, args, context) {
                     limit: parsed.limit,
                     page: parsed.page,
                     cleanText: true,
+                    linkedUsers: parsed.linkedUsers,
                 });
                 return formatResult(compactResponse(roles, "role"));
             }
@@ -3456,6 +3852,7 @@ async function _handleToolCall(client, name, args, context) {
                     limit: parsed.limit,
                     page: parsed.page,
                     cleanText: true,
+                    linkedUsers: parsed.linkedUsers,
                 });
                 return formatResult(completableResponse(compactResponse(projects), "projects", parsed._listTitle || "Projects"));
             }
@@ -3662,6 +4059,100 @@ async function _handleToolCall(client, name, args, context) {
                 const result = await client.bulkReorder(parsed.workspaceId, parsed.nestIds);
                 return formatResult({ message: "Nests reordered successfully", nests: result });
             }
+            case "nestr_set_recurrence": {
+                const parsed = schemas.setRecurrence.parse(args);
+                const result = await client.setRecurrence(parsed.nestId, parsed.rrule);
+                // The server returns the stored rule and nothing else. It does not
+                // create occurrence nests, so there is no count to report: saying one
+                // would tell the user work exists that does not.
+                const message = "removed" in result
+                    ? "Recurrence removed. Future occurrences stop; anything already materialized is kept, detached from the series."
+                    : `Recurrence set to ${result.rrule}. Occurrences stay virtual until one is touched.`;
+                return formatResult({ message, recurrence: result });
+            }
+            case "nestr_list_occurrences": {
+                const parsed = schemas.listOccurrences.parse(args);
+                const page = await client.listOccurrences(parsed.nestId, {
+                    direction: parsed.direction,
+                    cursor: parsed.cursor,
+                    limit: parsed.limit,
+                });
+                if (!page.seriesId) {
+                    return formatResult({
+                        message: "This nest has no recurrence rule, so it has no occurrences. Set one with nestr_set_recurrence.",
+                        ...page,
+                    });
+                }
+                // Named, because the count an agent reports back is the count of rows it
+                // can see, not the size of the series: an open-ended rule has no end and
+                // the route returns no total.
+                const virtual = page.occurrences.filter((o) => o.virtual).length;
+                const message = `${page.occurrences.length} occurrence(s) on this page, ${virtual} of them virtual (no nest exists yet).`
+                    + " Act on one by its `instant`: nestr_skip_occurrence to skip it, nestr_update_occurrence to edit it."
+                    + (page.hasMore ? " More beyond this page: pass nextCursor back as cursor." : "");
+                return formatResult({ message, ...page });
+            }
+            case "nestr_skip_occurrence": {
+                const parsed = schemas.skipOccurrence.parse(args);
+                const result = await client.skipOccurrence(parsed.nestId, parsed.instant, parsed.scope);
+                const at = new Date(parsed.instant).toISOString();
+                if (result && "deleted" in result) {
+                    const restore = `Restoring nest ${result.restoreId} in the Nestr app brings back that nest only; the occurrences deleted with it are restored separately.`;
+                    // A cut at the first occurrence leaves no history, so the whole series is gone.
+                    const message = result.restoreId === result.seriesId
+                        ? `The cut at ${at} was the first occurrence, so the whole series was deleted. ${restore}`
+                        : `Occurrence at ${at} and every later one deleted. The history before it is kept, under a rule that now ends there. ${restore}`;
+                    return formatResult({ message, occurrence: result });
+                }
+                if (result?.restoreId) {
+                    const restore = `Restoring nest ${result.restoreId} in the Nestr app brings back that nest only; the occurrences deleted with it are restored separately.`;
+                    const outcome = result.seriesId
+                        ? `so it was deleted and the series continues from nest ${result.seriesId}.`
+                        : "so it was deleted, and nothing followed it, so the series has ended.";
+                    return formatResult({
+                        message: `Occurrence at ${at} skipped. The first occurrence is the series item itself, ${outcome} ${restore}`,
+                        occurrence: result,
+                    });
+                }
+                return formatResult({
+                    message: `Occurrence at ${at} skipped. The series continues: the rule is unchanged and every other occurrence, past and future, is untouched.`,
+                    occurrence: result,
+                });
+            }
+            case "nestr_update_occurrence": {
+                const { nestId, instant, ...updates } = schemas.updateOccurrence.parse(args);
+                validatePrimeLabels(updates.labels);
+                updates.labels = ensureMeetingModifier(updates.labels);
+                const edited = Object.values(updates).some((value) => value !== undefined);
+                try {
+                    const nest = await client.updateOccurrence(nestId, instant, {
+                        ...updates,
+                        data: updates.data,
+                    });
+                    const at = new Date(instant).toISOString();
+                    const message = `${edited ? "Occurrence updated" : "Occurrence materialized"} at ${at}. Only this occurrence changed.`
+                        + (nest?._id ? ` It is nest ${nest._id} now: use that id with every other nest tool.` : "");
+                    return formatResult({ message, nest });
+                }
+                catch (err) {
+                    // The route materializes before it applies the body, so a refused edit is not a no-op.
+                    // Except the two refusals that write nothing: the first occurrence and a skipped one.
+                    const writesNothing = err instanceof NestrApiError
+                        && /series item itself|has been skipped/i.test(err.message);
+                    if (err instanceof NestrApiError && err.status >= 400 && err.status < 500 && !writesNothing) {
+                        err.hint = `${err.hint ? `${err.hint} ` : ""}The occurrence may already be materialized even though the edit was refused: nestr_list_occurrences shows its nestId.`;
+                    }
+                    throw err;
+                }
+            }
+            case "nestr_delete_series": {
+                const parsed = schemas.deleteSeries.parse(args);
+                const result = await client.deleteSeries(parsed.nestId);
+                return formatResult({
+                    message: `Series deleted: the series nest and every occurrence, past ones included. Restoring nest ${result.restoreId} in the Nestr app brings back that nest only; the occurrences deleted with it are restored separately.`,
+                    series: result,
+                });
+            }
             // Label management
             case "nestr_add_label": {
                 const parsed = schemas.addLabel.parse(args);
@@ -3838,9 +4329,7 @@ async function _handleToolCall(client, name, args, context) {
             case "nestr_list_tensions": {
                 const parsed = schemas.listTensions.parse(args);
                 const tensions = await client.listTensions(parsed.nestId, parsed.search, {
-                    // `order` is the legacy name for this option — it was never honored
-                    // by the API (which reads `sort`), so route both through sort.
-                    sort: parsed.sort ?? parsed.order,
+                    sort: parsed.sort,
                     limit: parsed.limit,
                     page: parsed.page,
                     cleanText: true,
@@ -4142,6 +4631,94 @@ async function _handleToolCall(client, name, args, context) {
                     ...result,
                 });
             }
+            case "nestr_workspace_docs": {
+                const parsed = schemas.workspaceDocs.parse(args);
+                const CONTEXT = "nestradamus_files";
+                // A key scoped to one workspace should not have to name it, and a user
+                // with exactly one has nothing to disambiguate. More than one and we ask
+                // rather than guess: reading the wrong organisation's constitution is a
+                // confident wrong answer, not a missing one.
+                let workspaceId = parsed.workspaceId;
+                if (!workspaceId) {
+                    const workspaces = await client.listWorkspaces({ limit: 5, cleanText: true });
+                    if (workspaces.length === 1) {
+                        workspaceId = workspaces[0]._id;
+                    }
+                    else if (workspaces.length === 0) {
+                        return { content: [{ type: "text", text: "No workspace is reachable with this token." }] };
+                    }
+                    else {
+                        const names = workspaces.map((w) => `- ${w._id} — ${w.title || "Untitled"}`).join("\n");
+                        return {
+                            content: [{
+                                    type: "text",
+                                    text: `_Resolved as: needs a workspace._\n\nThis token reaches several workspaces, so name one rather than have me pick:\n\n${names}`,
+                                }],
+                        };
+                    }
+                }
+                // Read one document.
+                if (parsed.fileId) {
+                    const doc = await client.getNestFileText(workspaceId, parsed.fileId, parsed.offset);
+                    const more = doc.nextOffset === null
+                        ? "End of document."
+                        : `More to read: nestr_workspace_docs({ fileId: "${parsed.fileId}", offset: ${doc.nextOffset} }). Prefer a search if you are looking for something specific.`;
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `_Resolved as: document read._\n\n**${doc.name}** (${doc.offset}–${doc.offset + doc.text.length} of ${doc.total} characters)\n\n${doc.text}\n\n---\n${more}`,
+                            }],
+                    };
+                }
+                const files = await client.getNestFiles(workspaceId, {
+                    context: CONTEXT,
+                    search: parsed.search,
+                });
+                // Search.
+                if (parsed.search) {
+                    if (files.length === 0) {
+                        return {
+                            content: [{
+                                    type: "text",
+                                    text: `_Resolved as: document search._\n\nNothing in this workspace's reference documents matches "${parsed.search}". The search reads the documents' text, so an exact phrase can miss where a synonym would hit. An empty result is not evidence the organisation has no position on this: say you could not find it documented, never that it does not exist.`,
+                                }],
+                        };
+                    }
+                    const blocks = files.map((f) => {
+                        const hits = (f.matches || [])
+                            .map((m) => `> ${m.excerpt}\n\n_Read on from here: nestr_workspace_docs({ fileId: "${f.id}", offset: ${m.offset} })_`)
+                            .join("\n\n");
+                        return `### ${f.name}\n\n${hits}`;
+                    });
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `_Resolved as: document search._\n\nPassages matching "${parsed.search}" in ${files.length} document${files.length === 1 ? "" : "s"}. These are the organisation's own words, so prefer them to your general knowledge.\n\n${blocks.join("\n\n")}`,
+                            }],
+                    };
+                }
+                // The index.
+                if (files.length === 0) {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: "_Resolved as: document index._\n\nThis workspace has uploaded no reference documents. That is an answer, not a failure: there is nothing here to consult, so do not keep looking.",
+                            }],
+                    };
+                }
+                const lines = files.map((f) => {
+                    const described = f.description
+                        ? f.description
+                        : "No description yet, so the filename is the only clue to what it holds.";
+                    return `- **${f.name}** (id: ${f.id}, ${formatBytes(f.size)})\n  ${described}`;
+                });
+                return {
+                    content: [{
+                            type: "text",
+                            text: `_Resolved as: document index._\n\n${files.length} reference document${files.length === 1 ? "" : "s"} in this workspace. Search them with nestr_workspace_docs({ search: "..." }) rather than reading one whole.\n\n${lines.join("\n")}`,
+                        }],
+                };
+            }
             case "nestr_get_nest_files": {
                 const parsed = schemas.getNestFiles.parse(args);
                 const files = await client.getNestFiles(parsed.nestId);