@nestr/mcp 0.1.106 → 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 = [];
@@ -777,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
@@ -810,6 +878,52 @@ 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.";
@@ -953,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."),
@@ -1072,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."),
@@ -1131,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)
@@ -1651,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" },
@@ -1702,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: {
@@ -2291,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",
@@ -2979,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.",
@@ -3528,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);
@@ -3842,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);
@@ -4320,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);