vantage-peers-mcp 2.4.6 → 2.4.10

package/README.md

@@ -9,8 +9,6 @@ MCP server for [VantagePeers](https://vantagepeers.com) — shared memory, messa
 
 84 tools across 18 categories: memory, profiles, tasks, missions, mission templates, messages, diary, briefing notes, search (RAG), issues, fix patterns, error monitoring, deployments, business units, components, mandates, recurring tasks, and session. All tools ship with ChatGPT Apps SDK annotations (`readOnlyHint`, `openWorldHint`, `destructiveHint`) for native UX in ChatGPT custom connectors.
 
-**Companion plugin — 32 skills (target v2.7.0):** the `vantage-peers` Claude Code plugin wraps these 84 tools with 32 high-level skills split across three phases — Phase A (11 skills, v2.5.0): `dispatch-message`, `dispatch-task-create`, `dispatch-task-complete`, `dispatch-task-start`, `dispatch-subagent`, `identity-set`, `mission-bootstrap`, `check-messages` v5.1, `check-tasks` v2, `daily-start` v3, `close-day` v2 — Phase B (10 skills, v2.6.0): `memory-write`, `briefing-write`, `mission-template-apply`, `task-structure`, `component-register`, `component-discover`, `issue-triage`, `fix-pattern-cycle`, `episode-log`, `recall-deep` — Phase C (11 skills, v2.7.0): `briefing-recall`, `repo-link`, `recurring-schedule`, `deploy-track`, `profile-lookup`, `peers-discovery`, `mandate-lifecycle`, `bu-manage`, `messages-history`, `memory-edit`, `diary-discover`.
-
 ## Quick start
 
 ```bash

package/dist/src/tools.d.ts

@@ -99,6 +99,11 @@ export declare const fieldsSchema: z.ZodEnum<{
     full: "full";
 }>;
 export declare const updatedSinceSchema: z.ZodNumber;
+/**
+ * Derive the current VantagePeers day number from the server clock.
+ * Returns 1 on or before 2026-03-06 UTC; increments by 1 per UTC day.
+ */
+export declare function deriveSessionDay(nowMs?: number): number;
 export interface ParsedConvexError {
     code: string;
     message: string;

package/dist/src/tools.js

@@ -274,6 +274,30 @@ const coreTeamSchema = z
 })
     .describe("Core team composition — agents, skills, hooks, plugins");
 // ─────────────────────────────────────────────────────────────────────────────
+// A.7 — project day number derivation
+//
+// VantagePeers uses a sequential "Day N" numbering convention where Day 1 =
+// 2026-03-06 UTC. This is the confirmed epoch: Day 88 = 2026-06-01 (87 days
+// after Day 1), verified from Pi VP task k178tqgzhbhzg1h4vbgn4kwdm987vntn
+// Day 88 brief (2026-06-01).
+//
+// No Convex-side day-counter table exists. The value is purely clock-based:
+//   dayNumber = floor((nowUTC_midnight - epoch_midnight) / MS_PER_DAY) + 1
+//
+// Callers who pass explicit sessionDay always override this derivation.
+// ─────────────────────────────────────────────────────────────────────────────
+/** UTC midnight of Day 1 (2026-03-06). All arithmetic is in whole UTC days. */
+const VP_DAY1_EPOCH_UTC_MS = Date.UTC(2026, 2, 6); // month is 0-indexed: 2 = March
+/**
+ * Derive the current VantagePeers day number from the server clock.
+ * Returns 1 on or before 2026-03-06 UTC; increments by 1 per UTC day.
+ */
+export function deriveSessionDay(nowMs = Date.now()) {
+    const MS_PER_DAY = 86_400_000;
+    const deltaDays = Math.floor((nowMs - VP_DAY1_EPOCH_UTC_MS) / MS_PER_DAY);
+    return Math.max(1, deltaDays + 1);
+}
+// ─────────────────────────────────────────────────────────────────────────────
 // Helper: normalize string|array inputs to array
 // ─────────────────────────────────────────────────────────────────────────────
 function toArray(val) {
@@ -589,16 +613,19 @@ export function registerTools(server, convex, oauthCtx) {
             .number()
             .int()
             .min(1)
-            .max(50)
+            .max(200)
+            .optional()
+            .describe("Max items to return. Default 20 (envelope-safe). Cap 200."),
+        fields: z
+            .enum(["lite", "full"])
             .optional()
-            .default(5)
-            .describe("Maximum number of results to return (default 5)"),
+            .describe("'lite' returns compact payload (less tokens), 'full' is default. v2.4.9+."),
     }, {
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         title: "Recall memories",
-    }, async ({ query, namespace, type, limit }) => {
+    }, async ({ query, namespace, type, limit, fields }) => {
         try {
             const nsDenied = guardRead(namespace);
             if (nsDenied)
@@ -607,7 +634,8 @@ export function registerTools(server, convex, oauthCtx) {
                 query,
                 namespace,
                 type,
-                limit: limit ?? 5,
+                limit: limit ?? 20,
+                fields: fields ?? "lite",
             });
             return {
                 content: [
@@ -634,16 +662,19 @@ export function registerTools(server, convex, oauthCtx) {
             .number()
             .int()
             .min(1)
-            .max(50)
+            .max(200)
             .optional()
-            .default(10)
-            .describe("Max results"),
+            .describe("Max items to return. Default 20 (envelope-safe). Cap 200."),
+        fields: z
+            .enum(["lite", "full"])
+            .optional()
+            .describe("'lite' returns compact payload (less tokens), 'full' is default. v2.4.9+."),
     }, {
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         title: "Search memories (text)",
-    }, async ({ query, namespace, type, limit }) => {
+    }, async ({ query, namespace, type, limit, fields }) => {
         try {
             const nsDenied = guardRead(namespace);
             if (nsDenied)
@@ -652,7 +683,8 @@ export function registerTools(server, convex, oauthCtx) {
                 query,
                 namespace,
                 type,
-                limit: limit ?? 10,
+                limit: limit ?? 20,
+                fields: fields ?? "lite",
             });
             return {
                 content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
@@ -671,10 +703,13 @@ export function registerTools(server, convex, oauthCtx) {
             .number()
             .int()
             .min(1)
-            .max(50)
+            .max(200)
             .optional()
-            .default(10)
-            .describe("Max results"),
+            .describe("Max items to return. Default 20 (envelope-safe). Cap 200."),
+        fields: z
+            .enum(["lite", "full"])
+            .optional()
+            .describe("'lite' returns compact payload (less tokens), 'full' is default. v2.4.9+."),
         vectorWeight: z
             .number()
             .min(0)
@@ -692,7 +727,7 @@ export function registerTools(server, convex, oauthCtx) {
         openWorldHint: false,
         destructiveHint: false,
         title: "Search memories (hybrid)",
-    }, async ({ query, namespace, type, limit, vectorWeight, textWeight }) => {
+    }, async ({ query, namespace, type, limit, fields, vectorWeight, textWeight }) => {
         try {
             const nsDenied = guardRead(namespace);
             if (nsDenied)
@@ -701,7 +736,8 @@ export function registerTools(server, convex, oauthCtx) {
                 query,
                 namespace,
                 type,
-                limit: limit ?? 10,
+                limit: limit ?? 20,
+                fields: fields ?? "lite",
                 vectorWeight,
                 textWeight,
             });
@@ -874,14 +910,17 @@ export function registerTools(server, convex, oauthCtx) {
             .min(1)
             .max(200)
             .optional()
-            .default(20)
-            .describe("Maximum number of memories to return (default 20)"),
+            .describe("Max items to return. Default 20 (envelope-safe). Cap 200."),
+        fields: z
+            .enum(["lite", "full"])
+            .optional()
+            .describe("'lite' returns compact payload (less tokens), 'full' is default. v2.4.9+."),
     }, {
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         title: "List memories",
-    }, async ({ namespace, type, createdBy, limit }) => {
+    }, async ({ namespace, type, createdBy, limit, fields }) => {
         try {
             const nsDenied = guardRead(namespace);
             if (nsDenied)
@@ -891,6 +930,7 @@ export function registerTools(server, convex, oauthCtx) {
                 type,
                 createdBy,
                 limit: limit ?? 20,
+                fields: fields ?? "lite",
             });
             const rawList = Array.isArray(memories)
                 ? memories
@@ -933,7 +973,8 @@ export function registerTools(server, convex, oauthCtx) {
             .number()
             .int()
             .optional()
-            .describe("Day number (e.g. 19 for Day 19)"),
+            .describe("Day number (e.g. 88 for Day 88). If omitted, auto-derived from project epoch " +
+            "(Day 1 = 2026-03-06 UTC). Pass explicitly to override."),
         tenantId: z
             .string()
             .optional()
@@ -950,12 +991,18 @@ export function registerTools(server, convex, oauthCtx) {
             const fromDenied = guardFrom(from);
             if (fromDenied)
                 return fromDenied;
+            // A.7: auto-derive sessionDay from project epoch when caller omits it.
+            // Day 1 = 2026-03-06 UTC (Day 88 confirmed as 2026-06-01).
+            // Explicit args.sessionDay always wins (backward-compat).
+            const derivedSessionDay = sessionDay !== undefined
+                ? sessionDay
+                : deriveSessionDay();
             const messageId = await convex.mutation("messages:sendMessage", {
                 from,
                 fromInstanceId,
                 channel,
                 content,
-                sessionDay,
+                sessionDay: derivedSessionDay,
                 tenantId,
             });
             return {
@@ -1165,17 +1212,32 @@ export function registerTools(server, convex, oauthCtx) {
     });
     // ── list_peers ──────────────────────────────────────────────────────────────
     server.tool("list_peers", "List all orchestrator profiles with their current status and summary. " +
-        "Replaces claude-peers list_peers.", {}, {
+        "Replaces claude-peers list_peers.", {
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .optional()
+            .describe("Max items to return. Default 20 (envelope-safe). Cap 200."),
+        fields: z
+            .enum(["lite", "full"])
+            .optional()
+            .describe("'lite' returns compact payload (less tokens), 'full' is default. v2.4.9+."),
+    }, {
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         title: "List peers",
-    }, async () => {
+    }, async ({ limit, fields }) => {
         try {
             const _scopeDenied = guardMasterOnly("list_peers");
             if (_scopeDenied)
                 return _scopeDenied;
-            const profiles = await convex.query("profiles:listProfiles", {});
+            const profiles = await convex.query("profiles:listProfiles", {
+                limit: limit ?? 20,
+                fields: fields ?? "lite",
+            });
             const peers = profiles.map((p) => ({
                 id: p.orchestratorId,
                 instanceId: p.instanceId ?? p.orchestratorId,
@@ -1211,16 +1273,19 @@ export function registerTools(server, convex, oauthCtx) {
             .number()
             .int()
             .min(1)
-            .max(500)
+            .max(200)
+            .optional()
+            .describe("Max items to return. Default 20 (envelope-safe). Cap 200."),
+        fields: z
+            .enum(["lite", "full"])
             .optional()
-            .default(100)
-            .describe("Max messages to return (default 100)"),
+            .describe("'lite' returns compact payload (less tokens), 'full' is default. v2.4.9+."),
     }, {
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         title: "List messages",
-    }, async ({ sessionDay, from, limit }) => {
+    }, async ({ sessionDay, from, limit, fields }) => {
         try {
             const _scopeDenied = guardMasterOnly("list_messages");
             if (_scopeDenied)
@@ -1228,7 +1293,8 @@ export function registerTools(server, convex, oauthCtx) {
             const messages = await convex.query("messages:listMessages", {
                 sessionDay,
                 from,
-                limit: limit ?? 100,
+                limit: limit ?? 20,
+                fields: fields ?? "lite",
             });
             const baseText = capListResponseBytes(messages, JSON.stringify(messages, null, 2), "list_messages");
             const text = appendMarkerIfEnabled(baseText, () => ({
@@ -1256,18 +1322,31 @@ export function registerTools(server, convex, oauthCtx) {
         messageId: z
             .string()
             .describe("Convex document ID of the broadcast message"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .optional()
+            .describe("Max items to return. Default 20 (envelope-safe). Cap 200."),
+        fields: z
+            .enum(["lite", "full"])
+            .optional()
+            .describe("'lite' returns compact payload (less tokens), 'full' is default. v2.4.9+."),
     }, {
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         title: "List broadcast status",
-    }, async ({ messageId }) => {
+    }, async ({ messageId, limit, fields }) => {
         try {
             const _scopeDenied = guardMasterOnly("list_broadcast_status");
             if (_scopeDenied)
                 return _scopeDenied;
             const status = await convex.query("messages:listBroadcastStatus", {
                 messageId,
+                limit: limit ?? 20,
+                fields: fields ?? "lite",
             });
             return {
                 content: [
@@ -1375,10 +1454,10 @@ export function registerTools(server, convex, oauthCtx) {
             .min(1)
             .max(200)
             .optional()
-            .describe("Maximum number of tasks to return. Default 50 with fields=lite, auto-clamped to 30 when fields=full and no explicit limit (overflow protection)."),
+            .describe("Max items to return. Default 20 (envelope-safe). Cap 200."),
         fields: fieldsSchema
             .optional()
-            .describe('Field projection ("lite"|"full")'),
+            .describe('Field projection ("lite"|"full"). Default "lite" (v2.4.9+).'),
         createdBy: assigneeSchema
             .optional()
             .describe("Filter by task creator (e.g. 'pi' to find Pi-dispatched tasks)"),
@@ -1405,8 +1484,8 @@ export function registerTools(server, convex, oauthCtx) {
                 assignedToInstance,
                 status,
                 project,
-                limit,
-                fields,
+                limit: limit ?? 20,
+                fields: fields ?? "lite",
                 createdBy,
                 updatedSince,
             });
@@ -1768,7 +1847,7 @@ export function registerTools(server, convex, oauthCtx) {
             .min(1)
             .max(200)
             .optional()
-            .describe("Maximum number of tasks to return. Default 50 with fields=lite, auto-clamped to 30 when fields=full and no explicit limit."),
+            .describe("Max items to return. Default 20 (envelope-safe). Cap 200."),
         fields: fieldsSchema
             .optional()
             .describe('Field projection ("lite"|"full")'),
@@ -1787,8 +1866,8 @@ export function registerTools(server, convex, oauthCtx) {
             const tasks = await convex.query("tasks:listByMission", {
                 missionId: missionId,
                 status,
-                limit,
-                fields,
+                limit: limit ?? 20,
+                fields: fields ?? "lite",
                 createdBy,
                 updatedSince,
             });
@@ -1879,10 +1958,10 @@ export function registerTools(server, convex, oauthCtx) {
             .min(1)
             .max(200)
             .optional()
-            .describe("Maximum number of missions to return. Default 50 with fields=lite, auto-clamped to 30 when fields=full and no explicit limit."),
+            .describe("Max items to return. Default 20 (envelope-safe). Cap 200."),
         fields: fieldsSchema
             .optional()
-            .describe('Field projection ("lite"|"full")'),
+            .describe('Field projection ("lite"|"full"). Default "lite" (v2.4.9+).'),
         updatedSince: updatedSinceSchema.optional(),
     }, {
         readOnlyHint: true,
@@ -1902,8 +1981,8 @@ export function registerTools(server, convex, oauthCtx) {
                 project,
                 pilot,
                 status,
-                limit,
-                fields,
+                limit: limit ?? 20,
+                fields: fields ?? "lite",
                 updatedSince,
             });
             const baseText = capListResponseBytes(missions, JSON.stringify(missions, null, 2), "list_missions");
@@ -2062,12 +2141,19 @@ export function registerTools(server, convex, oauthCtx) {
             const fromDenied = guardFrom(orchestrator);
             if (fromDenied)
                 return fromDenied;
+            // v2.4.8: derive createdBy from auth context (oauthCtx.userId).
+            // This is the anti-spoof authored-by — distinct from orchestrator
+            // (writer-intent label, client-supplied). On the no-auth path
+            // (master-scope bearer / local dev), oauthCtx is undefined and
+            // createdBy gracefully degrades to undefined (transition period).
+            const createdBy = oauthCtx?.userId;
             const diaryId = await convex.mutation("diary:write", {
                 date,
                 orchestrator,
                 content,
                 highlights: toArray(highlights),
                 blockers: toArray(blockers),
+                createdBy,
             });
             return {
                 content: [
@@ -2139,33 +2225,43 @@ export function registerTools(server, convex, oauthCtx) {
             .describe("Filter to a specific orchestrator — omit for all"),
         createdBy: assigneeSchema
             .optional()
-            .describe("Filter by creator/orchestrator role — alias of `orchestrator` for cross-tool consistency (mirrors list_tasks pattern). If both are passed, `createdBy` wins."),
+            .describe("Filter by auth-derived author (v2.4.8+, anti-spoof). Distinct from `orchestrator` which is the writer-intent label. Pre-v2.4.8 entries are backfilled with orchestrator as best-guess."),
         limit: z
             .number()
             .int()
             .min(1)
-            .max(100)
+            .max(200)
             .optional()
-            .default(20)
-            .describe("Maximum entries to return (default 20)"),
+            .describe("Max items to return. Default 20 (envelope-safe). Cap 200."),
+        fields: z
+            .enum(["lite", "full"])
+            .optional()
+            .describe("'lite' returns compact payload (less tokens), 'full' is default. v2.4.9+."),
     }, {
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         title: "List diary entries",
-    }, async ({ orchestrator, createdBy, limit }) => {
+    }, async ({ orchestrator, createdBy, limit, fields }) => {
         try {
-            // createdBy is an alias of orchestrator (diary's author field). If both set, createdBy wins.
-            const effectiveOrchestrator = createdBy ?? orchestrator;
-            // Non-master: must scope to own orchestrator id.
+            // v2.4.8: orchestrator (writer-intent) and createdBy (auth-derived
+            // author) are separate filters — NOT aliases. Forward both independently.
+            // Non-master: REQUIRE at least one explicit self-scope — undefined passes
+            // through are forbidden. Mirrors v2.4.7 effectiveOrchestrator shortcircuit:
+            // undefined !== myId → Forbidden. No silent fleet-read for non-master callers.
             if (oauthCtx && !isMasterScope(oauthCtx)) {
-                if (effectiveOrchestrator !== oauthCtx.userId) {
-                    return mcpError(`Forbidden: list_diaries requires orchestrator='${oauthCtx.userId}' for non-master scope (current: ${oauthCtx.scopeProfile}).`);
+                const myId = oauthCtx.userId;
+                const orchestratorScoped = orchestrator === myId;
+                const createdByScoped = createdBy === myId;
+                if (!orchestratorScoped && !createdByScoped) {
+                    return mcpError(`Forbidden: list_diaries requires orchestrator='${myId}' OR createdBy='${myId}' for non-master scope (current scope: ${oauthCtx.scopeProfile}).`);
                 }
             }
             const entries = await convex.query("diary:list", {
-                orchestrator: effectiveOrchestrator,
+                orchestrator,
+                createdBy,
                 limit: limit ?? 20,
+                fields: fields ?? "lite",
             });
             return {
                 content: [
@@ -2302,12 +2398,12 @@ export function registerTools(server, convex, oauthCtx) {
             .number()
             .int()
             .min(1)
-            .max(100)
+            .max(200)
             .optional()
-            .describe("Maximum notes to return. Default 20 with fields=lite, auto-clamped to 15 when fields=full and no explicit limit."),
+            .describe("Max items to return. Default 20 (envelope-safe). Cap 200."),
         fields: fieldsSchema
             .optional()
-            .describe('Field projection ("lite"|"full")'),
+            .describe('Field projection ("lite"|"full"). Default "lite" (v2.4.9+).'),
         updatedSince: updatedSinceSchema.optional(),
     }, {
         readOnlyHint: true,
@@ -2321,8 +2417,8 @@ export function registerTools(server, convex, oauthCtx) {
                 return _scopeDenied;
             const notes = await convex.query("briefingNotes:list", {
                 topic,
-                limit,
-                fields,
+                limit: limit ?? 20,
+                fields: fields ?? "lite",
                 updatedSince,
             });
             const baseText = capListResponseBytes(notes, JSON.stringify(notes, null, 2), "list_briefing_notes");
@@ -2421,16 +2517,19 @@ export function registerTools(server, convex, oauthCtx) {
             .number()
             .int()
             .min(1)
-            .max(500)
+            .max(200)
+            .optional()
+            .describe("Max items to return. Default 20 (envelope-safe). Cap 200."),
+        fields: z
+            .enum(["lite", "full"])
             .optional()
-            .default(100)
-            .describe("Maximum components to return (default 100)"),
+            .describe("'lite' returns compact payload (less tokens), 'full' is default. v2.4.9+."),
     }, {
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         title: "List components",
-    }, async ({ type, team, limit }) => {
+    }, async ({ type, team, limit, fields }) => {
         try {
             const _scopeDenied = guardMasterOnly("list_components");
             if (_scopeDenied)
@@ -2438,7 +2537,8 @@ export function registerTools(server, convex, oauthCtx) {
             const components = await convex.query("components:list", {
                 type,
                 team,
-                limit: limit ?? 100,
+                limit: limit ?? 20,
+                fields: fields ?? "lite",
             });
             return {
                 content: [
@@ -2556,13 +2656,23 @@ export function registerTools(server, convex, oauthCtx) {
             .string()
             .describe("Search term to match against component name or team"),
         type: componentTypeSchema.optional().describe("Filter by component type"),
-        limit: z.number().int().optional().describe("Max results (default 50)"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .optional()
+            .describe("Max items to return. Default 20 (envelope-safe). Cap 200."),
+        fields: z
+            .enum(["lite", "full"])
+            .optional()
+            .describe("'lite' returns compact payload (less tokens), 'full' is default. v2.4.9+."),
     }, {
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         title: "Search components",
-    }, async ({ query, type, limit }) => {
+    }, async ({ query, type, limit, fields }) => {
         try {
             const _scopeDenied = guardMasterOnly("search_components");
             if (_scopeDenied)
@@ -2570,7 +2680,8 @@ export function registerTools(server, convex, oauthCtx) {
             const results = await convex.query("components:search", {
                 query,
                 type,
-                limit,
+                limit: limit ?? 20,
+                fields: fields ?? "lite",
             });
             return {
                 content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
@@ -2648,14 +2759,17 @@ export function registerTools(server, convex, oauthCtx) {
             .min(1)
             .max(200)
             .optional()
-            .default(50)
-            .describe("Max results"),
+            .describe("Max items to return. Default 20 (envelope-safe). Cap 200."),
+        fields: z
+            .enum(["lite", "full"])
+            .optional()
+            .describe("'lite' returns compact payload (less tokens), 'full' is default. v2.4.9+."),
     }, {
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         title: "List recurring tasks",
-    }, async ({ assignedTo, active, limit }) => {
+    }, async ({ assignedTo, active, limit, fields }) => {
         try {
             const _scopeDenied = guardMasterOnly("list_recurring_tasks");
             if (_scopeDenied)
@@ -2663,7 +2777,8 @@ export function registerTools(server, convex, oauthCtx) {
             const tasks = await convex.query("recurringTasks:list", {
                 assignedTo,
                 active,
-                limit: limit ?? 50,
+                limit: limit ?? 20,
+                fields: fields ?? "lite",
             });
             return {
                 content: [{ type: "text", text: capListResponseBytes(tasks, JSON.stringify(tasks, null, 2), "list_recurring_tasks") }],
@@ -2994,14 +3109,17 @@ export function registerTools(server, convex, oauthCtx) {
             .min(1)
             .max(200)
             .optional()
-            .default(50)
-            .describe("Maximum mandates to return (default 50)"),
+            .describe("Max items to return. Default 20 (envelope-safe). Cap 200."),
+        fields: z
+            .enum(["lite", "full"])
+            .optional()
+            .describe("'lite' returns compact payload (less tokens), 'full' is default. v2.4.9+."),
     }, {
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         title: "List mandates",
-    }, async ({ requestedBy, fulfilledBy, status, limit }) => {
+    }, async ({ requestedBy, fulfilledBy, status, limit, fields }) => {
         try {
             const _scopeDenied = guardMasterOnly("list_mandates");
             if (_scopeDenied)
@@ -3010,7 +3128,8 @@ export function registerTools(server, convex, oauthCtx) {
                 requestedBy,
                 fulfilledBy,
                 status,
-                limit: limit ?? 50,
+                limit: limit ?? 20,
+                fields: fields ?? "lite",
             });
             return {
                 content: [
@@ -3205,14 +3324,17 @@ export function registerTools(server, convex, oauthCtx) {
             .min(1)
             .max(200)
             .optional()
-            .default(50)
-            .describe("Maximum BUs to return (default 50)"),
+            .describe("Max items to return. Default 20 (envelope-safe). Cap 200."),
+        fields: z
+            .enum(["lite", "full"])
+            .optional()
+            .describe("'lite' returns compact payload (less tokens), 'full' is default. v2.4.9+."),
     }, {
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         title: "List BUs",
-    }, async ({ orchestratorId, status, limit }) => {
+    }, async ({ orchestratorId, status, limit, fields }) => {
         try {
             const _scopeDenied = guardMasterOnly("list_bus");
             if (_scopeDenied)
@@ -3220,7 +3342,8 @@ export function registerTools(server, convex, oauthCtx) {
             const bus = await convex.query("businessUnits:list", {
                 orchestratorId,
                 status,
-                limit: limit ?? 50,
+                limit: limit ?? 20,
+                fields: fields ?? "lite",
             });
             return {
                 content: [
@@ -3306,17 +3429,32 @@ export function registerTools(server, convex, oauthCtx) {
         }
     });
     // ── list_repo_mappings ──────────────────────────────────────────────────────
-    server.tool("list_repo_mappings", "List all GitHub repo → orchestrator mappings. Shows which repos are monitored and which orchestrator handles each.", {}, {
+    server.tool("list_repo_mappings", "List all GitHub repo → orchestrator mappings. Shows which repos are monitored and which orchestrator handles each.", {
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .optional()
+            .describe("Max items to return. Default 20 (envelope-safe). Cap 200."),
+        fields: z
+            .enum(["lite", "full"])
+            .optional()
+            .describe("'lite' returns compact payload (less tokens), 'full' is default. v2.4.9+."),
+    }, {
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         title: "List repo mappings",
-    }, async () => {
+    }, async ({ limit, fields }) => {
         try {
             const _scopeDenied = guardMasterOnly("list_repo_mappings");
             if (_scopeDenied)
                 return _scopeDenied;
-            const mappings = await convex.query("githubRepoMapping:list", {});
+            const mappings = await convex.query("githubRepoMapping:list", {
+                limit: limit ?? 20,
+                fields: fields ?? "lite",
+            });
             return {
                 content: [
                     {
@@ -3378,14 +3516,17 @@ export function registerTools(server, convex, oauthCtx) {
             .min(1)
             .max(200)
             .optional()
-            .default(50)
-            .describe("Maximum number of issues to return (default 50)"),
+            .describe("Max items to return. Default 20 (envelope-safe). Cap 200."),
+        fields: z
+            .enum(["lite", "full"])
+            .optional()
+            .describe("'lite' returns compact payload (less tokens), 'full' is default. v2.4.9+."),
     }, {
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         title: "List issues",
-    }, async ({ project, status, assignedTo, limit }) => {
+    }, async ({ project, status, assignedTo, limit, fields }) => {
         try {
             const _scopeDenied = guardMasterOnly("list_issues");
             if (_scopeDenied)
@@ -3395,26 +3536,30 @@ export function registerTools(server, convex, oauthCtx) {
                 results = await convex.query("issues:listByOrchestrator", {
                     assignedOrchestrator: assignedTo,
                     status: status,
-                    limit: limit ?? 50,
+                    limit: limit ?? 20,
+                    fields: fields ?? "lite",
                 });
             }
             else if (project) {
                 results = await convex.query("issues:listByProject", {
                     project,
                     status: status,
-                    limit: limit ?? 50,
+                    limit: limit ?? 20,
+                    fields: fields ?? "lite",
                 });
             }
             else if (status) {
                 results = await convex.query("issues:listByStatus", {
                     status: status,
-                    limit: limit ?? 50,
+                    limit: limit ?? 20,
+                    fields: fields ?? "lite",
                 });
             }
             else {
                 results = await convex.query("issues:listByProject", {
                     project: "",
-                    limit: limit ?? 50,
+                    limit: limit ?? 20,
+                    fields: fields ?? "lite",
                 });
             }
             return {
@@ -3730,21 +3875,28 @@ export function registerTools(server, convex, oauthCtx) {
         limit: z
             .number()
             .int()
+            .min(1)
+            .max(200)
             .optional()
-            .describe("Max results to return (default 10)"),
+            .describe("Max items to return. Default 20 (envelope-safe). Cap 200."),
+        fields: z
+            .enum(["lite", "full"])
+            .optional()
+            .describe("'lite' returns compact payload (less tokens), 'full' is default. v2.4.9+."),
     }, {
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         title: "Search fix patterns",
-    }, async ({ query, limit }) => {
+    }, async ({ query, limit, fields }) => {
         try {
             const _scopeDenied = guardMasterOnly("search_fix_patterns");
             if (_scopeDenied)
                 return _scopeDenied;
             const results = await convex.action("search:searchFixPatterns", {
                 query,
-                limit,
+                limit: limit ?? 20,
+                fields: fields ?? "lite",
             });
             return {
                 content: [
@@ -3765,13 +3917,23 @@ export function registerTools(server, convex, oauthCtx) {
             .string()
             .optional()
             .describe("Filter by source project — omit for all"),
-        limit: z.number().int().optional().describe("Max results (default 50)"),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(200)
+            .optional()
+            .describe("Max items to return. Default 20 (envelope-safe). Cap 200."),
+        fields: z
+            .enum(["lite", "full"])
+            .optional()
+            .describe("'lite' returns compact payload (less tokens), 'full' is default. v2.4.9+."),
     }, {
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         title: "List fix patterns",
-    }, async ({ project, limit }) => {
+    }, async ({ project, limit, fields }) => {
         try {
             const _scopeDenied = guardMasterOnly("list_fix_patterns");
             if (_scopeDenied)
@@ -3779,14 +3941,16 @@ export function registerTools(server, convex, oauthCtx) {
             if (project) {
                 const results = await convex.query("fixPatterns:listByProject", {
                     sourceProject: project,
-                    limit,
+                    limit: limit ?? 20,
+                    fields: fields ?? "lite",
                 });
                 return {
                     content: [{ type: "text", text: capListResponseBytes(results, JSON.stringify(results, null, 2), "list_fix_patterns") }],
                 };
             }
             const allResults = await convex.query("fixPatterns:listAll", {
-                limit,
+                limit: limit ?? 20,
+                fields: fields ?? "lite",
             });
             return {
                 content: [
@@ -4057,21 +4221,25 @@ export function registerTools(server, convex, oauthCtx) {
             .min(1)
             .max(200)
             .optional()
-            .default(50)
-            .describe("Maximum number of errors to return (default 50)"),
+            .describe("Max items to return. Default 20 (envelope-safe). Cap 200."),
+        fields: z
+            .enum(["lite", "full"])
+            .optional()
+            .describe("'lite' returns compact payload (less tokens), 'full' is default. v2.4.9+."),
     }, {
         readOnlyHint: true,
         openWorldHint: false,
         destructiveHint: false,
         title: "List errors",
-    }, async ({ deployment, limit }) => {
+    }, async ({ deployment, limit, fields }) => {
         try {
             const _scopeDenied = guardMasterOnly("list_errors");
             if (_scopeDenied)
                 return _scopeDenied;
             const errors = await convex.query("errorMonitor:listErrors", {
                 deployment,
-                limit: limit ?? 50,
+                limit: limit ?? 20,
+                fields: fields ?? "lite",
             });
             return {
                 content: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vantage-peers-mcp",
-  "version": "2.4.6",
+  "version": "2.4.10",
   "description": "MCP server for VantagePeers — shared memory, messaging, and task coordination for AI agent teams",
   "type": "module",
   "main": "./dist/server.js",