@nimara-app/mcp 0.2.0 → 0.4.0

package/dist/index.js

@@ -6,6 +6,76 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
+// package.json
+var package_default = {
+  name: "@nimara-app/mcp",
+  version: "0.4.0",
+  private: false,
+  mcpName: "io.github.langskip-studios/nimara",
+  description: "Nimara MCP server \u2014 AI tool integration for Claude, Codex, and others",
+  license: "MIT",
+  type: "module",
+  main: "dist/index.js",
+  bin: {
+    "nimara-mcp": "dist/index.js"
+  },
+  files: [
+    "dist",
+    "README.md"
+  ],
+  keywords: [
+    "mcp",
+    "model-context-protocol",
+    "nimara",
+    "claude",
+    "ai",
+    "convex"
+  ],
+  repository: {
+    type: "git",
+    url: "git+https://github.com/Langskip-Studios/Nimara.git",
+    directory: "packages/mcp"
+  },
+  homepage: "https://github.com/Langskip-Studios/Nimara/tree/master/packages/mcp#readme",
+  publishConfig: {
+    access: "public"
+  },
+  scripts: {
+    build: "node build.mjs",
+    dev: "node build.mjs",
+    start: "node dist/index.js",
+    typecheck: "tsc --noEmit",
+    prepublishOnly: "npm run typecheck && npm run build"
+  },
+  dependencies: {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    convex: "^1.18.0",
+    zod: "^3.23.0"
+  },
+  devDependencies: {
+    "@nimara/convex": "workspace:*",
+    "@types/node": "^20.0.0",
+    esbuild: "^0.23.0",
+    typescript: "^5.0.0"
+  },
+  engines: {
+    node: ">=20"
+  }
+};
+
+// src/instructions.ts
+var INSTRUCTIONS = `Nimara is the team's work tracker. Work items have a type (epic > feature > task > subtask), a status from the project's own workflow, and a displayId like NIM-T42 that people read and type.
+
+Start with list_orgs \u2192 list_projects \u2192 get_active_block (the committed work; position 0 is next) and list_ai_review_queue (what a person has asked an agent to do; read \`answer\` first). Use get_work_items / search_work_items for items you already know of; list_work_items only to survey.
+
+Titles are plain language a teammate understands at a glance: what is wrong or what changes for a person, not the file, function or mechanism. No em dashes, no "Area: thing, thing" shapes. Descriptions carry the why, acceptance criteria and file paths; a spec, design or long report goes in a document (create_document) linked from the item.
+
+A status must be one of the project's \`statuses\` from list_projects, spelled exactly; never invent one. Labels come from list_labels; do not invent those either.
+
+When you pick up an item: update_work_item { status: <in-progress status>, agentWorking: true }. That lights its row for 15 minutes; any write or read of the item renews it, and on a long stretch with no Nimara calls, heartbeat_work_item every few minutes keeps it lit. Post a comment at real milestones. If you stop early, agentWorking: false. Moving to the last status clears it.
+
+Mention a person in a comment as [@Name](user:<userId>) and they are notified. Append agent research to a description under the exact heading "## Research (auto)", never editing the human text above it. When you open a PR, put the displayId in its title.`;
+
 // ../convex/convex/_generated/api.js
 import { anyApi, componentsGeneric } from "convex/server";
 var api = anyApi;
@@ -230,7 +300,7 @@ function registerListAiReviewQueue(server) {
   server.registerTool(
     "list_ai_review_queue",
     {
-      description: "List work items in a project that a human has flagged for AI review (aiReviewRequested). Descriptions come back in full here, since enrichment needs the whole text. Returns { items, nextCursor, hasMore } \u2014 when hasMore is true, call again with cursor set to nextCursor. Process each item, then clear its flag by calling update_work_item with aiReviewRequested: false. Call list_projects first to find the projectId.",
+      description: "List work items in a project that a human has flagged for AI review (aiReviewRequested). Descriptions come back in full here, since enrichment needs the whole text. Each item also carries recentComments (the last few, oldest first) and, when a person has written one, `answer`: the newest human comment. READ `answer` FIRST. When you flagged an item with a question and it is back in this queue, `answer` is the person's reply to that question; act on it rather than asking again. Returns { items, nextCursor, hasMore } \u2014 when hasMore is true, call again with cursor set to nextCursor. Process each item, then clear its flag by calling update_work_item with aiReviewRequested: false. Call list_projects first to find the projectId.",
       inputSchema: {
         projectId: z5.string().describe("projectId from list_projects"),
         limit: z5.number().int().min(1).max(200).optional().describe("Items per page (default 50, max 200)."),
@@ -257,8 +327,35 @@ function registerListAiReviewQueue(server) {
   );
 }
 
-// src/tools/create-work-item.ts
+// src/tools/get-active-block.ts
 import { z as z6 } from "zod";
+function registerGetActiveBlock(server) {
+  server.registerTool(
+    "get_active_block",
+    {
+      description: "The project's ACTIVE BLOCK: the small, ordered set of work a person has committed to right now. Call this BEFORE list_work_items when deciding what to work on \u2014 position 0 is the next thing to do, and the wider backlog is not on the table until the block is empty. Each item carries a lane: 'person' means a human owes it (flagged for review, or parked in a Review status) and you should not touch it; 'agent' means a human asked an agent to act on it, so it is yours first, and it carries recentComments and `answer` (the newest human comment: read it before anything else); 'open' is uncommitted-to-anyone work in priority order; 'done' is finished. Returns null when the project has no active block, in which case fall back to list_work_items. Descriptions are previewed; use get_work_items for the full text of an item you pick up. Call list_projects first for the projectId.",
+      inputSchema: {
+        projectId: z6.string().describe("projectId from list_projects")
+      },
+      annotations: {
+        readOnlyHint: true,
+        openWorldHint: false
+      }
+    },
+    async ({ projectId }) => {
+      const block = await getConvexClient().action(api.mcp.getActiveBlock, {
+        token: getToken(),
+        projectId
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify(block, null, 2) }]
+      };
+    }
+  );
+}
+
+// src/tools/create-work-item.ts
+import { z as z7 } from "zod";
 
 // src/tools/titleGuidance.ts
 var TITLE_GUIDANCE = 'A title a teammate can understand at a glance, without opening the item or knowing the codebase. Say what is wrong or what changes FOR A PERSON, in plain words \u2014 not the mechanism, the file, or the symbol. Good: "Sorted list shows an expand arrow that does nothing". Bad: "Fix hasChildren computation in list.tsx". Good: "Long titles wrap to three lines and are hard to read". Bad: "Adjust COLUMNS.title min-width constant". Prefer ordinary words over internal abbreviations, and only name a file, function or identifier when it genuinely is the clearest way to say it (a tool or endpoint the user calls by name, for instance). No ticket prefixes or status markers \u2014 the board renders those already. Root cause, file paths, and reproduction steps belong in the description, which has room for them. Keep it to one plain clause. Do NOT use an em dash, and do not use the "Area: thing, other thing" shape \u2014 both are ways of stapling a second title on and they are what makes these hard to read. Bad: "Gantt: tighten row density, match app typography, stop the chart falling short of its container". Good: "Gantt chart looks nothing like the rest of the app". If the title needs a comma-spliced list to be accurate, that is a sign the item is really several items, not a sign it needs a longer title.';
@@ -266,6 +363,14 @@ var TITLE_GUIDANCE = 'A title a teammate can understand at a glance, without ope
 // src/tools/statusGuidance.ts
 var STATUS_GUIDANCE = 'Must be one of the names in the project\'s `statuses`, returned by list_projects. Read it rather than guessing \u2014 a status is the board column, so a name the workflow does not have is rejected, and before that check existed such items rendered in the first column while claiming otherwise. Match the existing name exactly, including its wording: if the workflow says "Review", do not write "In Review". Do NOT invent a status to capture something about an item. Statuses are shared across the whole project and aggregated on the dashboard, so each new one is a permanent extra band there. Anything that describes an item rather than locating it in the flow belongs in a LABEL \u2014 see create_label and add_label_to_work_item. Defaults to the first status when omitted.';
 
+// ../convex/convex/lib/descriptionLimits.ts
+var DESCRIPTION_MAX_CHARS = 32e3;
+var DESCRIPTION_TOO_LONG = `A description can be at most ${DESCRIPTION_MAX_CHARS.toLocaleString("en-US")} characters. Put specs, research and long reports in a document and link it to the item.`;
+
+// src/tools/descriptionGuidance.ts
+var DESCRIPTION_MAX = DESCRIPTION_MAX_CHARS;
+var DESCRIPTION_GUIDANCE = `Markdown. The what and the why: the problem, acceptance criteria, reproduction steps, file paths, root cause. Keep it to what someone picking the item up needs. A spec, a design, research, or a long report goes in a document (create_document) linked from here, not inline. At most ${DESCRIPTION_MAX_CHARS.toLocaleString("en-US")} characters.`;
+
 // src/tools/create-work-item.ts
 function registerCreateWorkItem(server) {
   server.registerTool(
@@ -273,17 +378,17 @@ function registerCreateWorkItem(server) {
     {
       description: "Create a new work item in a project. Hierarchy rules: epics live at the root; features go under epics; tasks go under epics or features (or root); subtasks must go under a task. Returns the new workItemId and its display ID (e.g. NIM-42).",
       inputSchema: {
-        projectId: z6.string().describe("projectId from list_projects"),
-        type: z6.enum(["epic", "feature", "task", "subtask"]).describe("Item type \u2014 drives hierarchy validation"),
-        title: z6.string().min(1).describe(TITLE_GUIDANCE),
-        description: z6.string().optional().describe("Optional markdown body"),
-        parentId: z6.string().optional().describe(
+        projectId: z7.string().describe("projectId from list_projects"),
+        type: z7.enum(["epic", "feature", "task", "subtask"]).describe("Item type \u2014 drives hierarchy validation"),
+        title: z7.string().min(1).describe(TITLE_GUIDANCE),
+        description: z7.string().max(DESCRIPTION_MAX).optional().describe(DESCRIPTION_GUIDANCE),
+        parentId: z7.string().optional().describe(
           "workItemId of the parent. Required for subtask, optional otherwise."
         ),
-        status: z6.string().optional().describe(
+        status: z7.string().optional().describe(
           STATUS_GUIDANCE
         ),
-        priority: z6.enum(["p0", "p1", "p2", "p3"]).optional().describe("p0 highest, p3 lowest. Defaults to p2.")
+        priority: z7.enum(["p0", "p1", "p2", "p3"]).optional().describe("p0 highest, p3 lowest. Defaults to p2.")
       },
       annotations: {
         readOnlyHint: false,
@@ -306,23 +411,23 @@ function registerCreateWorkItem(server) {
 }
 
 // src/tools/create-project.ts
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 function registerCreateProject(server) {
   server.registerTool(
     "create_project",
     {
       description: "Create a new project in an org. Prefix must be unique within the org and is uppercased (e.g. 'NIM' yields work items NIM-1, NIM-2\u2026). Caller becomes the project admin. Returns the new projectId.",
       inputSchema: {
-        orgId: z7.string().describe("orgId from list_orgs"),
-        name: z7.string().min(1).describe("Project name"),
-        prefix: z7.string().min(1).max(8).describe(
+        orgId: z8.string().describe("orgId from list_orgs"),
+        name: z8.string().min(1).describe("Project name"),
+        prefix: z8.string().min(1).max(8).describe(
           "Short uppercase prefix for work item IDs (e.g. 'NIM'). Unique per org."
         ),
-        description: z7.string().optional().describe("Optional markdown description"),
-        isPrivate: z7.boolean().optional().describe(
+        description: z8.string().optional().describe("Optional markdown description"),
+        isPrivate: z8.boolean().optional().describe(
           "If true, only explicitly added members see it. Defaults to false."
         ),
-        workflowTemplate: z7.enum(["default", "simple", "kanban", "bug"]).optional().describe(
+        workflowTemplate: z8.enum(["default", "simple", "kanban", "bug"]).optional().describe(
           "Status workflow. Defaults to 'default' (Backlog/Todo/In Progress/Review/Done)."
         )
       },
@@ -347,7 +452,7 @@ function registerCreateProject(server) {
 }
 
 // src/tools/update-work-item.ts
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 
 // src/tools/researchFormat.ts
 var RESEARCH_FORMAT = `When appending automated research to a description, use EXACTLY this format, after the human-written text:
@@ -383,22 +488,25 @@ function registerUpdateWorkItem(server) {
     {
       description: "Update an existing work item: title, description, status, priority, parent, or review flags. Any update also stamps the item as AI-touched.",
       inputSchema: {
-        workItemId: z8.string().describe("workItemId from list_work_items"),
-        title: z8.string().min(1).optional().describe(TITLE_GUIDANCE),
-        description: z8.string().optional().describe(
-          "Full markdown body, replacing what is there. " + RESEARCH_FORMAT
+        workItemId: z9.string().describe("workItemId from list_work_items"),
+        title: z9.string().min(1).optional().describe(TITLE_GUIDANCE),
+        description: z9.string().max(DESCRIPTION_MAX).optional().describe(
+          "Full markdown body, replacing what is there. " + DESCRIPTION_GUIDANCE + " " + RESEARCH_FORMAT
         ),
-        status: z8.string().optional().describe(STATUS_GUIDANCE),
-        priority: z8.enum(["p0", "p1", "p2", "p3"]).optional(),
-        parentId: z8.string().nullable().optional().describe("New parent workItemId, null to move to root."),
-        needsReview: z8.boolean().optional().describe(
+        status: z9.string().optional().describe(STATUS_GUIDANCE),
+        priority: z9.enum(["p0", "p1", "p2", "p3"]).optional(),
+        parentId: z9.string().nullable().optional().describe("New parent workItemId, null to move to root."),
+        needsReview: z9.boolean().optional().describe(
           "Flag the item for manual human review \u2014 set true when your enrichment was thin or uncertain."
         ),
-        reviewReason: z8.string().optional().describe(
+        reviewReason: z9.string().optional().describe(
           "Short reason the item needs manual review (shown to the human)."
         ),
-        aiReviewRequested: z8.boolean().optional().describe(
+        aiReviewRequested: z9.boolean().optional().describe(
           "The human\u2192AI review flag. Set false to clear it after you have reviewed/enriched an item from list_ai_review_queue."
+        ),
+        agentWorking: z9.boolean().optional().describe(
+          "Set true when you start working on this item: the app lights its row so the person can see it is in flight. It is a 15-minute lease renewed by any later MCP write on the item (updates, comments), by reading it (get_work_items, list_work_item_comments), or by heartbeat_work_item \u2014 call that every few minutes on a long task with no other Nimara calls, or the row goes quiet while you are still at it. Set false when you stop without finishing; moving the item to the last status clears it for you."
         )
       },
       annotations: {
@@ -421,7 +529,7 @@ function registerUpdateWorkItem(server) {
 }
 
 // src/tools/move-work-item.ts
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 function registerMoveWorkItem(server) {
   server.registerTool(
     "move_work_item",
@@ -432,8 +540,8 @@ function registerMoveWorkItem(server) {
       // changes, and labels/milestones do not survive.
       description: "Move a work item to a different project, taking its whole subtree with it \u2014 children and grandchildren move too, and the hierarchy is preserved. Both projects must be in the same organization, and you need write access to both. Not reversible by calling this again: the item is renumbered in the destination, so NIM-T44 might become SKA-T18 and the old ID stops resolving. Labels and milestone assignments are dropped, because both belong to the project being left; a status the destination doesn't define falls back to its first status. The response reports every old \u2192 new ID plus everything that was dropped or remapped. Comments, images, attached documents, PR links and history all follow the item. Call list_projects first for the target projectId.",
       inputSchema: {
-        workItemId: z9.string().describe("workItemId from list_work_items \u2014 the item to move."),
-        targetProjectId: z9.string().describe(
+        workItemId: z10.string().describe("workItemId from list_work_items \u2014 the item to move."),
+        targetProjectId: z10.string().describe(
           "projectId from list_projects \u2014 the destination. Must be in the same org as the item's current project."
         )
       },
@@ -462,20 +570,20 @@ function registerMoveWorkItem(server) {
 }
 
 // src/tools/create-document.ts
-import { z as z10 } from "zod";
+import { z as z11 } from "zod";
 function registerCreateDocument(server) {
   server.registerTool(
     "create_document",
     {
       description: "Create a markdown project document. Use type 'prd' for project docs or 'fd' for feature/work-item documents.",
       inputSchema: {
-        projectId: z10.string().describe("projectId from list_projects"),
-        title: z10.string().min(1),
-        type: z10.enum(["prd", "fd"]).describe(
+        projectId: z11.string().describe("projectId from list_projects"),
+        title: z11.string().min(1),
+        type: z11.enum(["prd", "fd"]).describe(
           "Document type. 'fd' is stored as the app's feature document type."
         ),
-        workItemId: z10.string().optional().describe("Required for fd documents; omitted for prd."),
-        content: z10.string().optional().describe("Optional initial markdown content.")
+        workItemId: z11.string().optional().describe("Required for fd documents; omitted for prd."),
+        content: z11.string().optional().describe("Optional initial markdown content.")
       },
       annotations: {
         readOnlyHint: false,
@@ -497,18 +605,18 @@ function registerCreateDocument(server) {
 }
 
 // src/tools/update-document.ts
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 function registerUpdateDocument(server) {
   server.registerTool(
     "update_document",
     {
       description: "Update an existing document's markdown content and/or title. Use this to fill in or revise a document created earlier (e.g. backfill content into an empty doc). documentId comes from list_documents. Provided content fully replaces the existing content.",
       inputSchema: {
-        documentId: z11.string().describe("documentId from list_documents"),
-        content: z11.string().optional().describe(
+        documentId: z12.string().describe("documentId from list_documents"),
+        content: z12.string().optional().describe(
           "New markdown content. Replaces the document's existing content."
         ),
-        title: z11.string().min(1).optional().describe("New title (optional).")
+        title: z12.string().min(1).optional().describe("New title (optional).")
       },
       annotations: {
         readOnlyHint: false,
@@ -530,15 +638,15 @@ function registerUpdateDocument(server) {
 }
 
 // src/tools/list-documents.ts
-import { z as z12 } from "zod";
+import { z as z13 } from "zod";
 function registerListDocuments(server) {
   server.registerTool(
     "list_documents",
     {
       description: "List PRD/FD markdown documents for a project, optionally filtered to one work item.",
       inputSchema: {
-        projectId: z12.string().describe("projectId from list_projects"),
-        workItemId: z12.string().optional().describe("Optional workItemId to list linked FD documents.")
+        projectId: z13.string().describe("projectId from list_projects"),
+        workItemId: z13.string().optional().describe("Optional workItemId to list linked FD documents.")
       },
       annotations: {
         readOnlyHint: true,
@@ -558,8 +666,8 @@ function registerListDocuments(server) {
 }
 
 // src/tools/create-project-link.ts
-import { z as z13 } from "zod";
-var projectLinkCategory = z13.enum([
+import { z as z14 } from "zod";
+var projectLinkCategory = z14.enum([
   "api",
   "dashboard",
   "documentation",
@@ -573,10 +681,10 @@ function registerCreateProjectLink(server) {
     {
       description: "Save a link on a project for resources like APIs, dashboards, documentation, repositories, or services.",
       inputSchema: {
-        projectId: z13.string().describe("projectId from list_projects"),
-        title: z13.string().min(1).max(120),
-        url: z13.string().url().describe("http(s) URL to save"),
-        description: z13.string().max(500).optional(),
+        projectId: z14.string().describe("projectId from list_projects"),
+        title: z14.string().min(1).max(120),
+        url: z14.string().url().describe("http(s) URL to save"),
+        description: z14.string().max(500).optional(),
         category: projectLinkCategory.optional().describe("Defaults to other.")
       },
       annotations: {
@@ -599,14 +707,14 @@ function registerCreateProjectLink(server) {
 }
 
 // src/tools/list-project-links.ts
-import { z as z14 } from "zod";
+import { z as z15 } from "zod";
 function registerListProjectLinks(server) {
   server.registerTool(
     "list_project_links",
     {
       description: "List saved links for a project, such as APIs, dashboards, docs, repositories, and services.",
       inputSchema: {
-        projectId: z14.string().describe("projectId from list_projects")
+        projectId: z15.string().describe("projectId from list_projects")
       },
       annotations: {
         readOnlyHint: true,
@@ -625,18 +733,105 @@ function registerListProjectLinks(server) {
   );
 }
 
+// src/tools/list-scratch-notes.ts
+import { z as z16 } from "zod";
+function registerListScratchNotes(server) {
+  server.registerTool(
+    "list_scratch_notes",
+    {
+      description: "The token owner's OPEN scratch notes: thoughts and ideas they captured in the app with the `s` shortcut before deciding what to do with them. Returns the notes that belong with this project (tagged with it, or tagged with nothing), oldest first, each with noteId, body, projectId and createdAt. These are raw: a note may be one line or a paragraph, may describe one task or three, and may not be a task at all. Read each, decide what it should become (usually one or more work items via create_work_item, sometimes a comment on an existing item, sometimes nothing), do that, then call resolve_scratch_note with the noteId and the workItemId it became so the person sees where their note went. Ask in a comment rather than guess when a note is too thin to act on. Call list_projects first for the projectId.",
+      inputSchema: {
+        projectId: z16.string().describe("projectId from list_projects")
+      },
+      annotations: {
+        readOnlyHint: true,
+        openWorldHint: false
+      }
+    },
+    async ({ projectId }) => {
+      const notes = await getConvexClient().action(api.mcp.listScratchNotes, {
+        token: getToken(),
+        projectId
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify(notes, null, 2) }]
+      };
+    }
+  );
+}
+
+// src/tools/resolve-scratch-note.ts
+import { z as z17 } from "zod";
+function registerResolveScratchNote(server) {
+  server.registerTool(
+    "resolve_scratch_note",
+    {
+      description: "Mark a scratch note as used, recording the work item it became. Call this after acting on a note from list_scratch_notes: pass the noteId and the workItemId you created or updated from it (omit workItemId only when the note needed no item). The note leaves the person's open list and shows where it went. Only the token owner's own notes.",
+      inputSchema: {
+        noteId: z17.string().describe("noteId from list_scratch_notes"),
+        workItemId: z17.string().optional().describe("The workItemId the note became, from create_work_item or list_work_items.")
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    async ({ noteId, workItemId }) => {
+      const result = await getConvexClient().action(api.mcp.resolveScratchNote, {
+        token: getToken(),
+        noteId,
+        workItemId
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      };
+    }
+  );
+}
+
+// src/tools/heartbeat-work-item.ts
+import { z as z18 } from "zod";
+function registerHeartbeatWorkItem(server) {
+  server.registerTool(
+    "heartbeat_work_item",
+    {
+      description: 'Say you are still working on an item. Renews (or starts) its 15-minute "agent working" lease and does nothing else: no comment, no activity event, no change to the item. The app lights the row while the lease is live, so on a long task call this every few minutes or every handful of tool calls \u2014 otherwise the row goes quiet while you are still at it. Reads of the item (get_work_items, list_work_item_comments) also renew a live lease, and any update or comment does; this is for the stretches where you do none of those. Cheap and idempotent.',
+      inputSchema: {
+        workItemId: z18.string().describe("workItemId of the item you are working on")
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    async ({ workItemId }) => {
+      const result = await getConvexClient().action(api.mcp.heartbeatWorkItem, {
+        token: getToken(),
+        workItemId
+      });
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      };
+    }
+  );
+}
+
 // src/tools/add-work-item-image.ts
-import { z as z15 } from "zod";
+import { z as z19 } from "zod";
 function registerAddWorkItemImage(server) {
   server.registerTool(
     "add_work_item_image",
     {
       description: "Attach an externally hosted image URL to a work item. Use this when an MCP client has a screenshot, mockup, or generated image URL to preserve with the task.",
       inputSchema: {
-        workItemId: z15.string().describe("workItemId from list_work_items"),
-        imageUrl: z15.string().url().describe("Public or otherwise fetchable http(s) image URL"),
-        filename: z15.string().optional().describe("Optional display filename"),
-        altText: z15.string().optional().describe("Optional description/caption for the image")
+        workItemId: z19.string().describe("workItemId from list_work_items"),
+        imageUrl: z19.string().url().describe("Public or otherwise fetchable http(s) image URL"),
+        filename: z19.string().optional().describe("Optional display filename"),
+        altText: z19.string().optional().describe("Optional description/caption for the image")
       },
       annotations: {
         readOnlyHint: false,
@@ -658,14 +853,14 @@ function registerAddWorkItemImage(server) {
 }
 
 // src/tools/list-work-item-images.ts
-import { z as z16 } from "zod";
+import { z as z20 } from "zod";
 function registerListWorkItemImages(server) {
   server.registerTool(
     "list_work_item_images",
     {
       description: "List image attachments for a work item, including uploaded images and externally attached MCP images. Call list_work_items first to find the workItemId.",
       inputSchema: {
-        workItemId: z16.string().describe("workItemId from list_work_items")
+        workItemId: z20.string().describe("workItemId from list_work_items")
       },
       annotations: {
         readOnlyHint: true,
@@ -688,16 +883,18 @@ function registerListWorkItemImages(server) {
 }
 
 // src/tools/add-work-item-comment.ts
-import { z as z17 } from "zod";
+import { z as z21 } from "zod";
 function registerAddWorkItemComment(server) {
   server.registerTool(
     "add_work_item_comment",
     {
       description: "Add a timestamped comment to a work item. Use this to record notes, updates, or an 'AI touched' entry instead of editing the description. Comments are stamped with the current time automatically and never overwrite each other.",
       inputSchema: {
-        workItemId: z17.string().describe("workItemId from list_work_items"),
-        body: z17.string().min(1).describe("Comment text (markdown supported)"),
-        source: z17.enum(["user", "ai"]).optional().describe('Who authored it; defaults to "ai" for MCP callers')
+        workItemId: z21.string().describe("workItemId from list_work_items"),
+        body: z21.string().min(1).describe(
+          "Comment text (markdown supported). To pull a person into the thread, mention them as [@Name](user:<userId>) \u2014 they are notified and the app renders it as a chip. userIds come from an item's assigneeId/reviewerId; there is no member lookup tool yet, so only mention ids you have seen."
+        ),
+        source: z21.enum(["user", "ai"]).optional().describe('Who authored it; defaults to "ai" for MCP callers')
       },
       annotations: {
         readOnlyHint: false,
@@ -722,14 +919,14 @@ function registerAddWorkItemComment(server) {
 }
 
 // src/tools/list-work-item-comments.ts
-import { z as z18 } from "zod";
+import { z as z22 } from "zod";
 function registerListWorkItemComments(server) {
   server.registerTool(
     "list_work_item_comments",
     {
       description: "List the timestamped comments on a work item, oldest first. Use this to check whether the item was already touched/commented before adding a new comment.",
       inputSchema: {
-        workItemId: z18.string().describe("workItemId from list_work_items")
+        workItemId: z22.string().describe("workItemId from list_work_items")
       },
       annotations: {
         readOnlyHint: true,
@@ -752,14 +949,14 @@ function registerListWorkItemComments(server) {
 }
 
 // src/tools/list-validations.ts
-import { z as z19 } from "zod";
+import { z as z23 } from "zod";
 function registerListValidations(server) {
   server.registerTool(
     "list_validations",
     {
       description: "List a project's validation graph: core systems and validation/test tasks with their DERIVED state (passing, failing, stale, unvalidated). A task is 'stale' when a system it covers changed since it was last validated, or an upstream dependency is no longer passing. Call list_projects first to find the projectId.",
       inputSchema: {
-        projectId: z19.string().describe("projectId from list_projects")
+        projectId: z23.string().describe("projectId from list_projects")
       },
       annotations: {
         readOnlyHint: true,
@@ -780,15 +977,15 @@ function registerListValidations(server) {
 }
 
 // src/tools/record-validation.ts
-import { z as z20 } from "zod";
+import { z as z24 } from "zod";
 function registerRecordValidation(server) {
   server.registerTool(
     "record_validation",
     {
       description: "Check off a validation task by recording a pass or fail. Stamps the task as validated 'now', clearing any stale flag until a covered system changes or an upstream dependency moves again. Get validationTaskId from list_validations.",
       inputSchema: {
-        validationTaskId: z20.string().describe("validationTaskId from list_validations"),
-        result: z20.enum(["pass", "fail"]).describe("Outcome of running the test")
+        validationTaskId: z24.string().describe("validationTaskId from list_validations"),
+        result: z24.enum(["pass", "fail"]).describe("Outcome of running the test")
       },
       annotations: {
         readOnlyHint: false,
@@ -812,14 +1009,14 @@ function registerRecordValidation(server) {
 }
 
 // src/tools/mark-system-changed.ts
-import { z as z21 } from "zod";
+import { z as z25 } from "zod";
 function registerMarkSystemChanged(server) {
   server.registerTool(
     "mark_system_changed",
     {
       description: "Mark a core system as changed. This is the single action that invalidates testing: every validation task that covers this system (and everything transitively depending on those tasks) immediately becomes 'stale' and needs revalidation. Get systemId from list_validations.",
       inputSchema: {
-        systemId: z21.string().describe("systemId from list_validations")
+        systemId: z25.string().describe("systemId from list_validations")
       },
       annotations: {
         readOnlyHint: false,
@@ -842,16 +1039,16 @@ function registerMarkSystemChanged(server) {
 }
 
 // src/tools/create-system.ts
-import { z as z22 } from "zod";
+import { z as z26 } from "zod";
 function registerCreateSystem(server) {
   server.registerTool(
     "create_system",
     {
       description: "Create a core system in a project \u2014 a subsystem (e.g. Auth, Payments, Sync) whose change should invalidate the validation tasks that cover it. Returns the new systemId.",
       inputSchema: {
-        projectId: z22.string().describe("projectId from list_projects"),
-        name: z22.string().min(1).describe("Short system name, e.g. 'Auth'"),
-        description: z22.string().optional().describe("Optional details")
+        projectId: z26.string().describe("projectId from list_projects"),
+        name: z26.string().min(1).describe("Short system name, e.g. 'Auth'"),
+        description: z26.string().optional().describe("Optional details")
       },
       annotations: {
         readOnlyHint: false,
@@ -874,20 +1071,20 @@ function registerCreateSystem(server) {
 }
 
 // src/tools/create-validation-task.ts
-import { z as z23 } from "zod";
+import { z as z27 } from "zod";
 function registerCreateValidationTask(server) {
   server.registerTool(
     "create_validation_task",
     {
       description: "Create a validation/test task in a project. After creating it, use add_system_to_task to declare which systems it exercises (so it goes stale when they change) and add_validation_dependency to order it after other tasks. Returns the new validationTaskId.",
       inputSchema: {
-        projectId: z23.string().describe("projectId from list_projects"),
-        title: z23.string().min(1).describe("What this test validates"),
-        description: z23.string().optional().describe("Optional steps / details"),
-        kind: z23.enum(["auto", "manual"]).optional().describe(
+        projectId: z27.string().describe("projectId from list_projects"),
+        title: z27.string().min(1).describe("What this test validates"),
+        description: z27.string().optional().describe("Optional steps / details"),
+        kind: z27.enum(["auto", "manual"]).optional().describe(
           "'auto' if runnable by a test runner, 'manual' if a human checks it. Defaults to manual."
         ),
-        workItemId: z23.string().optional().describe(
+        workItemId: z27.string().optional().describe(
           "Optional workItemId to link this test to a feature for traceability"
         )
       },
@@ -912,15 +1109,15 @@ function registerCreateValidationTask(server) {
 }
 
 // src/tools/add-system-to-task.ts
-import { z as z24 } from "zod";
+import { z as z28 } from "zod";
 function registerAddSystemToTask(server) {
   server.registerTool(
     "add_system_to_task",
     {
       description: "Declare that a validation task COVERS (exercises) a system. Once linked, the task becomes 'stale' whenever that system is marked changed. Idempotent. Both IDs come from list_validations and must be in the same project.",
       inputSchema: {
-        validationTaskId: z24.string().describe("validationTaskId from list_validations"),
-        systemId: z24.string().describe("systemId from list_validations")
+        validationTaskId: z28.string().describe("validationTaskId from list_validations"),
+        systemId: z28.string().describe("systemId from list_validations")
       },
       annotations: {
         readOnlyHint: false,
@@ -944,15 +1141,15 @@ function registerAddSystemToTask(server) {
 }
 
 // src/tools/add-validation-dependency.ts
-import { z as z25 } from "zod";
+import { z as z29 } from "zod";
 function registerAddValidationDependency(server) {
   server.registerTool(
     "add_validation_dependency",
     {
       description: "Make one validation task depend on another (validationTaskId depends on dependsOnTaskId). The dependent goes 'stale' whenever the upstream task is not passing or gets revalidated. Cycles and self-dependencies are rejected. Idempotent. Both IDs come from list_validations and must be in the same project.",
       inputSchema: {
-        validationTaskId: z25.string().describe("The dependent (downstream) task"),
-        dependsOnTaskId: z25.string().describe("The dependency (upstream) task it relies on")
+        validationTaskId: z29.string().describe("The dependent (downstream) task"),
+        dependsOnTaskId: z29.string().describe("The dependency (upstream) task it relies on")
       },
       annotations: {
         readOnlyHint: false,
@@ -976,14 +1173,14 @@ function registerAddValidationDependency(server) {
 }
 
 // src/tools/list-labels.ts
-import { z as z26 } from "zod";
+import { z as z30 } from "zod";
 function registerListLabels(server) {
   server.registerTool(
     "list_labels",
     {
       description: "List all labels defined in a project. Returns each label's id, name, and color. Use the labelId with add_label_to_work_item / remove_label_from_work_item.",
       inputSchema: {
-        projectId: z26.string().describe("projectId from list_projects")
+        projectId: z30.string().describe("projectId from list_projects")
       },
       annotations: {
         readOnlyHint: true,
@@ -1003,16 +1200,16 @@ function registerListLabels(server) {
 }
 
 // src/tools/create-label.ts
-import { z as z27 } from "zod";
+import { z as z31 } from "zod";
 function registerCreateLabel(server) {
   server.registerTool(
     "create_label",
     {
       description: "Apply-or-seed a label. Returns the existing label if the name is already taken (idempotent), and otherwise creates it ONLY if the name is one of the curated ones. Any other new name is REFUSED \u2014 the reply carries `refused: true`, the reason, and `available`, the project's existing labels. Agents apply labels; they do not invent them, because a near-duplicate of an existing label splits the vocabulary silently. Prefer list_labels first. Colors are ignored for curated names so the vocabulary looks the same in every project.",
       inputSchema: {
-        projectId: z27.string().describe("projectId from list_projects"),
-        name: z27.string().min(1).describe("Label name, unique within the project"),
-        color: z27.string().regex(/^#[0-9a-fA-F]{6}$/).optional().describe("Hex color like #2563eb. Defaults to a neutral slate.")
+        projectId: z31.string().describe("projectId from list_projects"),
+        name: z31.string().min(1).describe("Label name, unique within the project"),
+        color: z31.string().regex(/^#[0-9a-fA-F]{6}$/).optional().describe("Hex color like #2563eb. Defaults to a neutral slate.")
       },
       annotations: {
         readOnlyHint: false,
@@ -1034,15 +1231,15 @@ function registerCreateLabel(server) {
 }
 
 // src/tools/add-label-to-work-item.ts
-import { z as z28 } from "zod";
+import { z as z32 } from "zod";
 function registerAddLabelToWorkItem(server) {
   server.registerTool(
     "add_label_to_work_item",
     {
       description: "Attach a label to a work item (idempotent). The label and work item must be in the same project. Get labelIds from list_labels / create_label.",
       inputSchema: {
-        workItemId: z28.string().describe("workItemId from list_work_items"),
-        labelId: z28.string().describe("labelId from list_labels or create_label")
+        workItemId: z32.string().describe("workItemId from list_work_items"),
+        labelId: z32.string().describe("labelId from list_labels or create_label")
       },
       annotations: {
         readOnlyHint: false,
@@ -1065,15 +1262,15 @@ function registerAddLabelToWorkItem(server) {
 }
 
 // src/tools/remove-label-from-work-item.ts
-import { z as z29 } from "zod";
+import { z as z33 } from "zod";
 function registerRemoveLabelFromWorkItem(server) {
   server.registerTool(
     "remove_label_from_work_item",
     {
       description: "Remove a label from a work item (idempotent \u2014 a no-op if it wasn't attached).",
       inputSchema: {
-        workItemId: z29.string().describe("workItemId from list_work_items"),
-        labelId: z29.string().describe("labelId from list_labels")
+        workItemId: z33.string().describe("workItemId from list_work_items"),
+        labelId: z33.string().describe("labelId from list_labels")
       },
       annotations: {
         readOnlyHint: false,
@@ -1096,14 +1293,14 @@ function registerRemoveLabelFromWorkItem(server) {
 }
 
 // src/tools/list-milestones.ts
-import { z as z30 } from "zod";
+import { z as z34 } from "zod";
 function registerListMilestones(server) {
   server.registerTool(
     "list_milestones",
     {
       description: "List all milestones in a project. Returns each milestone's id, name, description, dueDate (unix ms), and status. Use the milestoneId with add_item_to_milestone / remove_item_from_milestone.",
       inputSchema: {
-        projectId: z30.string().describe("projectId from list_projects")
+        projectId: z34.string().describe("projectId from list_projects")
       },
       annotations: {
         readOnlyHint: true,
@@ -1123,17 +1320,17 @@ function registerListMilestones(server) {
 }
 
 // src/tools/create-milestone.ts
-import { z as z31 } from "zod";
+import { z as z35 } from "zod";
 function registerCreateMilestone(server) {
   server.registerTool(
     "create_milestone",
     {
       description: "Create a milestone in a project. Returns the milestoneId. Good for grouping work into phases (e.g. 'Phase 1 \u2014 Web', 'Phase 2 \u2014 Native').",
       inputSchema: {
-        projectId: z31.string().describe("projectId from list_projects"),
-        name: z31.string().min(1).describe("Milestone name"),
-        description: z31.string().optional().describe("Optional markdown description"),
-        dueDate: z31.number().optional().describe("Optional due date as a unix timestamp in milliseconds")
+        projectId: z35.string().describe("projectId from list_projects"),
+        name: z35.string().min(1).describe("Milestone name"),
+        description: z35.string().optional().describe("Optional markdown description"),
+        dueDate: z35.number().optional().describe("Optional due date as a unix timestamp in milliseconds")
       },
       annotations: {
         readOnlyHint: false,
@@ -1155,15 +1352,15 @@ function registerCreateMilestone(server) {
 }
 
 // src/tools/add-item-to-milestone.ts
-import { z as z32 } from "zod";
+import { z as z36 } from "zod";
 function registerAddItemToMilestone(server) {
   server.registerTool(
     "add_item_to_milestone",
     {
       description: "Associate a work item with a milestone (idempotent). Both must be in the same project.",
       inputSchema: {
-        milestoneId: z32.string().describe("milestoneId from list_milestones or create_milestone"),
-        workItemId: z32.string().describe("workItemId from list_work_items")
+        milestoneId: z36.string().describe("milestoneId from list_milestones or create_milestone"),
+        workItemId: z36.string().describe("workItemId from list_work_items")
       },
       annotations: {
         readOnlyHint: false,
@@ -1189,15 +1386,15 @@ function registerAddItemToMilestone(server) {
 }
 
 // src/tools/remove-item-from-milestone.ts
-import { z as z33 } from "zod";
+import { z as z37 } from "zod";
 function registerRemoveItemFromMilestone(server) {
   server.registerTool(
     "remove_item_from_milestone",
     {
       description: "Remove a work item's association with a milestone (idempotent \u2014 a no-op if it wasn't associated).",
       inputSchema: {
-        milestoneId: z33.string().describe("milestoneId from list_milestones"),
-        workItemId: z33.string().describe("workItemId from list_work_items")
+        milestoneId: z37.string().describe("milestoneId from list_milestones"),
+        workItemId: z37.string().describe("workItemId from list_work_items")
       },
       annotations: {
         readOnlyHint: false,
@@ -1224,16 +1421,21 @@ function registerRemoveItemFromMilestone(server) {
 
 // src/server.ts
 function createServer() {
-  const server = new McpServer({
-    name: "nimara",
-    version: "0.1.0"
-  });
+  const server = new McpServer(
+    {
+      name: "nimara",
+      version: package_default.version
+    },
+    // Sent at connect time, before any tool is read (NIM-T189).
+    { instructions: INSTRUCTIONS }
+  );
   registerListOrgs(server);
   registerListProjects(server);
   registerListWorkItems(server);
   registerGetWorkItems(server);
   registerSearchWorkItems(server);
   registerListAiReviewQueue(server);
+  registerGetActiveBlock(server);
   registerCreateProject(server);
   registerCreateWorkItem(server);
   registerUpdateWorkItem(server);
@@ -1243,6 +1445,9 @@ function createServer() {
   registerListDocuments(server);
   registerCreateProjectLink(server);
   registerListProjectLinks(server);
+  registerListScratchNotes(server);
+  registerResolveScratchNote(server);
+  registerHeartbeatWorkItem(server);
   registerAddWorkItemImage(server);
   registerListWorkItemImages(server);
   registerAddWorkItemComment(server);