@productbrain/mcp 0.0.1-beta.46 → 0.0.1-beta.48

package/dist/{chunk-5ZCY6NLZ.js → chunk-4ZJEIAA6.js}

@@ -8,7 +8,7 @@ import {
 } from "./chunk-MRIO53BY.js";
 
 // src/tools/smart-capture.ts
-import { z } from "zod";
+import { z as z2 } from "zod";
 
 // src/client.ts
 import { AsyncLocalStorage as AsyncLocalStorage2 } from "async_hooks";
@@ -666,6 +666,214 @@ function isClassificationAmbiguous(result) {
   return result.scoreMargin < CLASSIFIER_AMBIGUITY_MARGIN;
 }
 
+// src/envelope.ts
+import { z } from "zod";
+
+// src/errors.ts
+var GateError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "GateError";
+  }
+};
+var BackendError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BackendError";
+  }
+};
+var ValidationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ValidationError";
+  }
+};
+var GATE_PATTERNS = [
+  {
+    pattern: /session required|no active.*session|call.*session.*start/i,
+    code: "SESSION_REQUIRED",
+    recovery: "Start an agent session first.",
+    action: { tool: "session", description: "Start session", parameters: { action: "start" } }
+  },
+  {
+    pattern: /session.*closed/i,
+    code: "SESSION_CLOSED",
+    recovery: "Start a new session.",
+    action: { tool: "session", description: "Start new session", parameters: { action: "start" } }
+  },
+  {
+    pattern: /orientation required|call.*orient/i,
+    code: "ORIENTATION_REQUIRED",
+    recovery: "Orient before writing.",
+    action: { tool: "orient", description: "Orient session", parameters: {} }
+  },
+  {
+    pattern: /read.?only.*scope/i,
+    code: "READONLY_SCOPE",
+    recovery: "This API key cannot write. Use a readwrite key.",
+    action: { tool: "health", description: "Check key scope", parameters: { action: "whoami" } }
+  }
+];
+function classifyError(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  if (err instanceof GateError) {
+    return {
+      code: "PERMISSION_DENIED",
+      message,
+      recovery: "Check permissions or use a readwrite API key.",
+      availableActions: [{ tool: "health", description: "Check key scope", parameters: { action: "whoami" } }]
+    };
+  }
+  if (err instanceof BackendError) {
+    return { code: "BACKEND_ERROR", message, recovery: "Retry the operation or check backend health." };
+  }
+  if (err instanceof ValidationError) {
+    return { code: "VALIDATION_ERROR", message };
+  }
+  for (const { pattern, code, recovery, action } of GATE_PATTERNS) {
+    if (pattern.test(message)) {
+      return { code, message, recovery, availableActions: [action] };
+    }
+  }
+  if (/network error|fetch failed|ECONNREFUSED|ETIMEDOUT/i.test(message)) {
+    return { code: "BACKEND_UNAVAILABLE", message, recovery: "Retry in a few seconds." };
+  }
+  if (/not found/i.test(message)) {
+    return {
+      code: "NOT_FOUND",
+      message,
+      recovery: "Use entries action=search to find the correct ID.",
+      availableActions: [{ tool: "entries", description: "Search entries", parameters: { action: "search" } }]
+    };
+  }
+  if (/duplicate|already exists/i.test(message)) {
+    return {
+      code: "DUPLICATE",
+      message,
+      recovery: "Use entries action=get to inspect the existing entry.",
+      availableActions: [{ tool: "entries", description: "Get entry", parameters: { action: "get" } }]
+    };
+  }
+  if (/invalid|validation|required field/i.test(message)) {
+    return { code: "VALIDATION_ERROR", message };
+  }
+  return { code: "INTERNAL_ERROR", message: message || "An unexpected error occurred." };
+}
+
+// src/envelope.ts
+function success(summary, data, next) {
+  return {
+    ok: true,
+    summary: summary || "Operation completed.",
+    data,
+    ...next?.length ? { next } : {}
+  };
+}
+function failure(code, message, recovery, availableActions, diagnostics) {
+  return {
+    ok: false,
+    code,
+    message,
+    ...recovery ? { recovery } : {},
+    ...availableActions?.length ? { availableActions } : {},
+    ...diagnostics ? { diagnostics } : {}
+  };
+}
+function notFound(id, hint) {
+  return failure(
+    "NOT_FOUND",
+    `Entry '${id}' not found.`,
+    hint ?? "Use entries action=search to find the correct ID.",
+    [{ tool: "entries", description: "Search entries", parameters: { action: "search", query: id } }]
+  );
+}
+function validationError(message) {
+  return failure("VALIDATION_ERROR", message);
+}
+function textContent(text) {
+  return [{ type: "text", text }];
+}
+function parseOrFail(schema, args) {
+  const parsed = schema.safeParse(args);
+  if (parsed.success) return { ok: true, data: parsed.data };
+  const issues = parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
+  const msg = `Invalid arguments: ${issues}`;
+  return {
+    ok: false,
+    result: { content: textContent(msg), structuredContent: validationError(msg) }
+  };
+}
+function unknownAction(action, valid) {
+  const msg = `Unknown action '${action}'. Valid actions: ${valid.join(", ")}.`;
+  return { content: textContent(msg), structuredContent: validationError(msg) };
+}
+function successResult(text, summary, data, next) {
+  return { content: textContent(text), structuredContent: success(summary, data, next) };
+}
+function failureResult(text, code, message, recovery, availableActions, diagnostics) {
+  return { content: textContent(text), structuredContent: failure(code, message, recovery, availableActions, diagnostics) };
+}
+function notFoundResult(id, text, hint) {
+  return { content: textContent(text ?? `Entry '${id}' not found.`), structuredContent: notFound(id, hint) };
+}
+function validationResult(message) {
+  return { content: textContent(message), structuredContent: validationError(message) };
+}
+var nextActionSchema = z.object({
+  tool: z.string(),
+  description: z.string(),
+  parameters: z.record(z.unknown())
+});
+var metaSchema = z.object({
+  durationMs: z.number().optional()
+}).optional();
+function withEnvelope(handler) {
+  return async (args) => {
+    const start = Date.now();
+    try {
+      const result = await handler(args);
+      const durationMs = Date.now() - start;
+      const sc = result.structuredContent;
+      if (sc && typeof sc === "object" && "ok" in sc) {
+        sc._meta = { ...sc._meta, durationMs };
+        return {
+          content: result.content ?? [],
+          structuredContent: sc,
+          ...sc.ok === false ? { isError: true } : {}
+        };
+      }
+      console.warn(`[withEnvelope] Handler returned without envelope shape. Wrapping automatically. Content preview: "${result.content?.[0]?.text?.slice(0, 60) ?? "(empty)"}"`);
+      return {
+        content: result.content ?? [],
+        structuredContent: {
+          ...success(
+            result.content?.[0]?.text?.slice(0, 100) ?? "",
+            sc ?? {}
+          ),
+          _meta: { durationMs }
+        }
+      };
+    } catch (err) {
+      const durationMs = Date.now() - start;
+      const classified = classifyError(err);
+      const envelope = {
+        ...failure(
+          classified.code,
+          classified.message,
+          classified.recovery,
+          classified.availableActions
+        ),
+        _meta: { durationMs }
+      };
+      return {
+        content: [{ type: "text", text: classified.message }],
+        structuredContent: envelope,
+        isError: true
+      };
+    }
+  };
+}
+
 // src/tools/smart-capture.ts
 var AREA_KEYWORDS = {
   "Architecture": ["convex", "schema", "database", "migration", "api", "backend", "infrastructure", "scaling", "performance"],
@@ -1264,43 +1472,46 @@ var AUTO_LINK_CONFIDENCE_THRESHOLD = 35;
 var MAX_AUTO_LINKS = 5;
 var MAX_SUGGESTIONS = 5;
 var CAPTURE_WITHOUT_THINKING_FLAG = "capture-without-thinking";
-var captureSchema = z.object({
-  collection: z.string().optional().describe("Collection slug, e.g. 'tensions', 'business-rules', 'glossary', 'decisions'. Optional when `capture-without-thinking` is enabled."),
-  name: z.string().describe("Display name \u2014 be specific (e.g. 'Convex adjacency list won't scale for graph traversal')"),
-  description: z.string().describe("Full context \u2014 what's happening, why it matters, what you observed"),
-  context: z.string().optional().describe("Optional additional context (e.g. 'Observed during context gather calls taking 700ms+')"),
-  entryId: z.string().optional().describe("Optional custom entry ID (e.g. 'TEN-my-id'). Auto-generated if omitted."),
-  canonicalKey: z.string().optional().describe("Semantic type (e.g. 'decision', 'tension', 'vision'). Auto-assigned from collection if omitted."),
-  data: z.record(z.unknown()).optional().describe("Explicit field values when you know the schema (e.g. canonical_key, cardinality_rule, required_fields). Merged with inferred values; user-provided wins."),
-  links: z.array(z.object({
-    to: z.string().describe("Target entry ID (e.g. 'BR-64', 'ARCH-8')"),
-    type: z.string().describe("Relation type (e.g. 'governs', 'related_to', 'informs')")
+var captureSchema = z2.object({
+  collection: z2.string().optional().describe("Collection slug, e.g. 'tensions', 'business-rules', 'glossary', 'decisions'. Optional when `capture-without-thinking` is enabled."),
+  name: z2.string().describe("Display name \u2014 be specific (e.g. 'Convex adjacency list won't scale for graph traversal')"),
+  description: z2.string().describe("Full context \u2014 what's happening, why it matters, what you observed"),
+  context: z2.string().optional().describe("Optional additional context (e.g. 'Observed during context gather calls taking 700ms+')"),
+  entryId: z2.string().optional().describe("Optional custom entry ID (e.g. 'TEN-my-id'). Auto-generated if omitted."),
+  canonicalKey: z2.string().optional().describe("Semantic type (e.g. 'decision', 'tension', 'vision'). Auto-assigned from collection if omitted."),
+  data: z2.record(z2.unknown()).optional().describe("Explicit field values when you know the schema (e.g. canonical_key, cardinality_rule, required_fields). Merged with inferred values; user-provided wins."),
+  links: z2.array(z2.object({
+    to: z2.string().describe("Target entry ID (e.g. 'BR-64', 'ARCH-8')"),
+    type: z2.string().describe("Relation type (e.g. 'governs', 'related_to', 'informs')")
   })).optional().describe("Relations to create after capture. Skips auto-link discovery when provided."),
-  autoCommit: z.boolean().optional().describe("If true, commits the entry immediately after capture + linking. Use for ungoverned collections or when you're certain.")
+  autoCommit: z2.boolean().optional().describe("If true, commits the entry immediately after capture + linking. Use for ungoverned collections or when you're certain.")
 });
-var batchCaptureSchema = z.object({
-  entries: z.array(z.object({
-    collection: z.string().describe("Collection slug"),
-    name: z.string().describe("Display name"),
-    description: z.string().describe("Full context / definition"),
-    entryId: z.string().optional().describe("Optional custom entry ID")
+var batchCaptureSchema = z2.object({
+  entries: z2.array(z2.object({
+    collection: z2.string().describe("Collection slug"),
+    name: z2.string().describe("Display name"),
+    description: z2.string().describe("Full context / definition"),
+    entryId: z2.string().optional().describe("Optional custom entry ID")
   })).min(1).max(50).describe("Array of entries to capture")
 });
-var captureClassifierSchema = z.object({
-  enabled: z.boolean(),
-  autoRouted: z.boolean(),
-  topConfidence: z.number(),
+var captureClassifierSchema = z2.object({
+  enabled: z2.boolean(),
+  autoRouted: z2.boolean(),
+  agrees: z2.boolean(),
+  topConfidence: z2.number(),
   // Backward-compatible alias for topConfidence.
-  confidence: z.number(),
-  reasons: z.array(z.string()),
-  candidates: z.array(
-    z.object({
-      collection: z.enum(STARTER_COLLECTIONS),
-      signalScore: z.number(),
+  confidence: z2.number(),
+  reasons: z2.array(z2.string()),
+  candidates: z2.array(
+    z2.object({
+      collection: z2.enum(STARTER_COLLECTIONS),
+      signalScore: z2.number(),
       // Backward-compatible alias for signalScore.
-      confidence: z.number()
+      confidence: z2.number()
     })
-  )
+  ),
+  agentProvidedCollection: z2.string().optional(),
+  overrideCommand: z2.string().optional()
 });
 function trackClassifierTelemetry(params) {
   const telemetry = {
@@ -1322,7 +1533,13 @@ function buildCollectionRequiredResult() {
     content: [{
       type: "text",
       text: "Collection is required unless `capture-without-thinking` is enabled.\n\nProvide `collection` explicitly, or enable the feature flag for this workspace."
-    }]
+    }],
+    structuredContent: failure(
+      "VALIDATION_ERROR",
+      "Collection is required unless capture-without-thinking is enabled.",
+      "Provide collection explicitly, or enable the feature flag.",
+      [{ tool: "collections", description: "List available collections", parameters: { action: "list" } }]
+    )
   };
 }
 function buildClassifierUnknownResult() {
@@ -1331,16 +1548,13 @@ function buildClassifierUnknownResult() {
       type: "text",
       text: "I could not infer a collection confidently from this input.\n\nPlease provide `collection`, or rewrite with clearer intent (decision/problem/definition/insight/bet)."
     }],
-    structuredContent: {
-      classifier: {
-        enabled: true,
-        autoRouted: false,
-        topConfidence: 0,
-        confidence: 0,
-        reasons: [],
-        candidates: []
-      }
-    }
+    structuredContent: failure(
+      "VALIDATION_ERROR",
+      "Could not infer collection from input.",
+      "Provide collection explicitly, or rewrite with clearer intent.",
+      [{ tool: "collections", description: "List available collections", parameters: { action: "list" } }],
+      { classifier: { enabled: true, autoRouted: false, agrees: true, topConfidence: 0, confidence: 0, reasons: [], candidates: [] } }
+    )
   };
 }
 function buildProvisionedCollectionSuggestions(candidates) {
@@ -1348,10 +1562,7 @@ function buildProvisionedCollectionSuggestions(candidates) {
 }
 function buildUnsupportedProvisioningResult(classified, provisionedCandidates) {
   const suggestions = buildProvisionedCollectionSuggestions(provisionedCandidates);
-  return {
-    content: [{
-      type: "text",
-      text: `Collection inference is not safe to auto-route yet.
+  const textBody = `Collection inference is not safe to auto-route yet.
 
 Predicted collection \`${classified.collection}\` is not provisioned/supported for auto-routing in this workspace.
 Reason: ${classified.reasons.join("; ") || "low signal"}
@@ -1359,36 +1570,50 @@ Reason: ${classified.reasons.join("; ") || "low signal"}
 Choose one of these provisioned starter collections and retry with \`collection\`:
 ${suggestions}
 
-Correction path: rerun with explicit \`collection\`.`
-    }],
-    structuredContent: {
-      classifier: {
-        enabled: true,
-        autoRouted: false,
-        topConfidence: classified.topConfidence,
-        confidence: classified.confidence,
-        reasons: classified.reasons,
-        candidates: provisionedCandidates
+Correction path: rerun with explicit \`collection\`.`;
+  return {
+    content: [{ type: "text", text: textBody }],
+    structuredContent: failure(
+      "VALIDATION_ERROR",
+      `Collection '${classified.collection}' is not provisioned for auto-routing.`,
+      "Rerun with explicit collection.",
+      [{ tool: "collections", description: "List available collections", parameters: { action: "list" } }],
+      {
+        classifier: {
+          enabled: true,
+          autoRouted: false,
+          agrees: false,
+          topConfidence: classified.topConfidence,
+          confidence: classified.confidence,
+          reasons: classified.reasons,
+          candidates: provisionedCandidates.map((c) => ({ collection: c.collection, signalScore: c.signalScore, confidence: c.confidence }))
+        }
       }
-    }
+    )
   };
 }
 function buildAmbiguousRouteResult(classified, classifierMeta, ambiguousRoute) {
   const suggestions = buildProvisionedCollectionSuggestions(classifierMeta.candidates);
-  return {
-    content: [{
-      type: "text",
-      text: "Collection inference is not safe to auto-route yet.\n\n" + (ambiguousRoute ? "Routing held because intent is ambiguous across top candidates.\n\n" : "") + `Predicted: \`${classified.collection}\` (${classified.topConfidence}% top confidence)
+  const textBody = "Collection inference is not safe to auto-route yet.\n\n" + (ambiguousRoute ? "Routing held because intent is ambiguous across top candidates.\n\n" : "") + `Predicted: \`${classified.collection}\` (${classified.topConfidence}% top confidence)
 Reason: ${classified.reasons.join("; ") || "low signal"}
 
 Choose one of these and retry with \`collection\`:
 ${suggestions}
 
-Correction path: if this was close, rerun with your chosen \`collection\`.`
-    }],
-    structuredContent: {
-      classifier: classifierMeta
-    }
+Correction path: if this was close, rerun with your chosen \`collection\`.`;
+  return {
+    content: [{ type: "text", text: textBody }],
+    structuredContent: failure(
+      "VALIDATION_ERROR",
+      ambiguousRoute ? `Ambiguous routing \u2014 top candidates too close (${classified.topConfidence}% confidence).` : `Low confidence routing to '${classified.collection}' (${classified.topConfidence}%).`,
+      "Rerun with explicit collection.",
+      classifierMeta.candidates.map((c) => ({
+        tool: "capture",
+        description: `Capture to ${c.collection}`,
+        parameters: { collection: c.collection }
+      })),
+      { classifier: classifierMeta }
+    )
   };
 }
 async function getProvisionedStarterCollectionCandidates(classified, supportedStarterCollections) {
@@ -1414,7 +1639,48 @@ async function resolveCaptureCollection(params) {
     explicitCollectionProvided
   } = params;
   if (collection) {
-    return { resolvedCollection: collection };
+    const classified2 = classifyStarterCollection(name, description);
+    if (classified2) {
+      const agrees = classified2.collection === collection;
+      const classifierMeta2 = {
+        enabled: true,
+        autoRouted: false,
+        agrees,
+        topConfidence: classified2.topConfidence,
+        confidence: classified2.confidence,
+        reasons: classified2.reasons,
+        candidates: classified2.candidates.slice(0, 3),
+        agentProvidedCollection: collection,
+        ...!agrees && {
+          overrideCommand: `capture collection="${classified2.collection}"`
+        }
+      };
+      if (!agrees) {
+        trackClassifierTelemetry({
+          workspaceId,
+          predictedCollection: classified2.collection,
+          confidence: classified2.confidence,
+          autoRouted: false,
+          reasonCategory: "low-confidence",
+          explicitCollectionProvided: true,
+          outcome: "fallback"
+        });
+      }
+      return { resolvedCollection: collection, classifierMeta: classifierMeta2 };
+    }
+    return {
+      resolvedCollection: collection,
+      classifierMeta: {
+        enabled: true,
+        autoRouted: false,
+        agrees: true,
+        topConfidence: 0,
+        confidence: 0,
+        reasons: [],
+        candidates: [],
+        agentProvidedCollection: collection
+      }
+    };
   }
   if (!classifierFlagOn) {
     return { earlyResult: buildCollectionRequiredResult() };
@@ -1452,6 +1718,7 @@ async function resolveCaptureCollection(params) {
   const classifierMeta = {
     enabled: true,
     autoRouted: autoRoute,
+    agrees: true,
     topConfidence: classified.topConfidence,
     confidence: classified.confidence,
     reasons: classified.reasons,
@@ -1486,36 +1753,36 @@ async function resolveCaptureCollection(params) {
     classifierMeta
   };
 }
-var captureSuccessOutputSchema = z.object({
-  entryId: z.string(),
-  collection: z.string(),
-  name: z.string(),
-  status: z.enum(["draft", "committed"]),
-  qualityScore: z.number(),
-  qualityVerdict: z.record(z.unknown()).optional(),
+var captureSuccessOutputSchema = z2.object({
+  entryId: z2.string(),
+  collection: z2.string(),
+  name: z2.string(),
+  status: z2.enum(["draft", "committed"]),
+  qualityScore: z2.number(),
+  qualityVerdict: z2.record(z2.unknown()).optional(),
   classifier: captureClassifierSchema.optional(),
-  studioUrl: z.string().optional()
+  studioUrl: z2.string().optional()
 }).strict();
-var captureClassifierOnlyOutputSchema = z.object({
+var captureClassifierOnlyOutputSchema = z2.object({
   classifier: captureClassifierSchema
 }).strict();
-var captureOutputSchema = z.union([
+var captureOutputSchema = z2.union([
   captureSuccessOutputSchema,
   captureClassifierOnlyOutputSchema
 ]);
-var batchCaptureOutputSchema = z.object({
-  captured: z.array(z.object({
-    entryId: z.string(),
-    collection: z.string(),
-    name: z.string()
+var batchCaptureOutputSchema = z2.object({
+  captured: z2.array(z2.object({
+    entryId: z2.string(),
+    collection: z2.string(),
+    name: z2.string()
   })),
-  total: z.number(),
-  failed: z.number(),
-  failedEntries: z.array(z.object({
-    index: z.number(),
-    collection: z.string(),
-    name: z.string(),
-    error: z.string()
+  total: z2.number(),
+  failed: z2.number(),
+  failedEntries: z2.array(z2.object({
+    index: z2.number(),
+    collection: z2.string(),
+    name: z2.string(),
+    error: z2.string()
   })).optional()
 });
 function registerSmartCaptureTools(server) {
@@ -1530,7 +1797,7 @@ function registerSmartCaptureTools(server) {
       inputSchema: captureSchema.shape,
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false }
     },
-    async ({ collection, name, description, context, entryId, canonicalKey, data: userData, links, autoCommit }) => {
+    withEnvelope(async ({ collection, name, description, context, entryId, canonicalKey, data: userData, links, autoCommit }) => {
       requireWriteAccess();
       const wsCtx = await getWorkspaceContext();
       const explicitCollectionProvided = typeof collection === "string" && collection.trim().length > 0;
@@ -1571,7 +1838,16 @@ collections action=create slug="${resolvedCollection}" name="${displayName}" des
 \`\`\`
 
 Or use \`collections action=list\` to see available collections.`
-          }]
+          }],
+          structuredContent: failure(
+            "NOT_FOUND",
+            `Collection '${resolvedCollection}' not found.`,
+            "Create the collection first, or use collections action=list to see available ones.",
+            [
+              { tool: "collections", description: "Create collection", parameters: { action: "create", slug: resolvedCollection, name: displayName } },
+              { tool: "collections", description: "List collections", parameters: { action: "list" } }
+            ]
+          )
         };
       }
       const data = {};
@@ -1647,7 +1923,16 @@ Or use \`collections action=list\` to see available collections.`
 ${msg}
 
 Use \`entries action=get\` to inspect the existing entry, or \`update-entry\` to modify it.`
-            }]
+            }],
+            structuredContent: failure(
+              "DUPLICATE",
+              msg,
+              "Use entries action=get to inspect the existing entry.",
+              [
+                { tool: "entries", description: "Get existing entry", parameters: { action: "get", entryId: entryId ?? name } },
+                { tool: "update-entry", description: "Update existing entry", parameters: { entryId: entryId ?? "" } }
+              ]
+            )
           };
         }
         throw error;
@@ -1809,14 +2094,27 @@ Use \`entries action=get\` to inspect the existing entry, or \`update-entry\` to
         `**${name}** added to \`${resolvedCollection}\` as \`${finalStatus}\``,
         `**Workspace:** ${wsCtx.workspaceSlug} (${wsCtx.workspaceId})`
       ];
-      if (classifierMeta?.autoRouted) {
+      if (classifierMeta && classifierMeta.topConfidence > 0) {
         lines.push("");
-        lines.push("## Collection routing");
-        lines.push(`Auto-routed to \`${resolvedCollection}\` (${classifierMeta.topConfidence}% top confidence).`);
-        if (classifierMeta.reasons.length > 0) {
-          lines.push(`Reason: ${classifierMeta.reasons.join("; ")}.`);
+        lines.push("## Classification");
+        if (classifierMeta.autoRouted) {
+          lines.push(`Auto-routed to \`${resolvedCollection}\` (${classifierMeta.topConfidence}% confidence).`);
+          if (classifierMeta.reasons.length > 0) {
+            lines.push(`Reason: ${classifierMeta.reasons.join("; ")}.`);
+          }
+          lines.push(`Override: rerun with explicit \`collection\` if wrong.`);
+        } else if (classifierMeta.agrees) {
+          lines.push(`Classifier confirms \`${resolvedCollection}\` (${classifierMeta.topConfidence}% confidence).`);
+        } else {
+          const suggested = classifierMeta.candidates[0]?.collection ?? "unknown";
+          lines.push(`Agent chose \`${resolvedCollection}\`, classifier suggests \`${suggested}\` (${classifierMeta.topConfidence}% confidence).`);
+          if (classifierMeta.reasons.length > 0) {
+            lines.push(`Reason: ${classifierMeta.reasons.join("; ")}.`);
+          }
+          if (classifierMeta.overrideCommand) {
+            lines.push(`Override: \`${classifierMeta.overrideCommand}\``);
+          }
         }
-        lines.push("Correction path: rerun capture with explicit `collection` if this routing is wrong.");
       }
       const appUrl = process.env.PRODUCTBRAIN_APP_URL ?? "https://productbrain.io";
       const studioUrl = resolvedCollection === "bets" ? `${appUrl.replace(/\/$/, "")}/w/${wsCtx.workspaceSlug}/studio/${internalId}` : void 0;
@@ -1924,21 +2222,35 @@ Use \`entries action=get\` to inspect the existing entry, or \`update-entry\` to
         }
       } catch {
       }
+      const next = [];
+      if (finalStatus === "committed") {
+        next.push({ tool: "graph", description: "Discover connections", parameters: { action: "suggest", entryId: finalEntryId } });
+      } else {
+        if (userLinkResults.length === 0) {
+          next.push({ tool: "graph", description: "Discover links", parameters: { action: "suggest", entryId: finalEntryId } });
+        }
+        next.push({ tool: "commit-entry", description: "Commit to Chain", parameters: { entryId: finalEntryId } });
+      }
+      const summary = finalStatus === "committed" ? `Captured and committed ${finalEntryId} (${name}) to ${resolvedCollection}. Quality ${quality.score}/10.` : `Captured ${finalEntryId} (${name}) as draft in ${resolvedCollection}. Quality ${quality.score}/10.`;
       const toolResult = {
         content: [{ type: "text", text: lines.join("\n") }],
-        structuredContent: {
-          entryId: finalEntryId,
-          collection: resolvedCollection,
-          name,
-          status: finalStatus,
-          qualityScore: quality.score,
-          qualityVerdict: verdictResult?.verdict ? { ...verdictResult.verdict, source: verdictResult.source ?? "heuristic" } : void 0,
-          ...classifierMeta && { classifier: classifierMeta },
-          ...studioUrl && { studioUrl }
-        }
+        structuredContent: success(
+          summary,
+          {
+            entryId: finalEntryId,
+            collection: resolvedCollection,
+            name,
+            status: finalStatus,
+            qualityScore: quality.score,
+            qualityVerdict: verdictResult?.verdict ? { ...verdictResult.verdict, source: verdictResult.source ?? "heuristic" } : void 0,
+            ...classifierMeta && { classifier: classifierMeta },
+            ...studioUrl && { studioUrl }
+          },
+          next
+        )
       };
       return toolResult;
-    }
+    })
   );
   trackWriteTool(captureTool);
   const batchCaptureTool = server.registerTool(
@@ -1949,7 +2261,7 @@ Use \`entries action=get\` to inspect the existing entry, or \`update-entry\` to
       inputSchema: batchCaptureSchema.shape,
       annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false }
     },
-    async ({ entries }) => {
+    withEnvelope(async ({ entries }) => {
       requireWriteAccess();
       const agentId = getAgentSessionId();
       const createdBy = agentId ? `agent:${agentId}` : "capture";
@@ -2113,25 +2425,32 @@ Use \`entries action=get\` to inspect the existing entry, or \`update-entry\` to
         lines.push(`- **Commit:** Use \`commit-entry\` to promote drafts to SSOT`);
         lines.push(`- **Quality:** Run \`quality action=check\` on individual entries to assess completeness`);
       }
+      const summary = failed.length > 0 ? `Batch captured ${created.length}/${entries.length} entries (${failed.length} failed).` : `Batch captured ${created.length} entries successfully.`;
+      const next = created.length > 0 ? [
+        { tool: "graph", description: "Discover connections", parameters: { action: "suggest", entryId: created[0].entryId } },
+        { tool: "commit-entry", description: "Commit first entry", parameters: { entryId: created[0].entryId } }
+      ] : [];
       return {
         content: [{ type: "text", text: lines.join("\n") }],
-        structuredContent: {
-          captured: created.map((r) => ({ entryId: r.entryId, collection: r.collection, name: r.name })),
-          total: created.length,
-          failed: failed.length,
-          // failedEntries provides enough detail for the agent to retry individually.
-          // Only populated when failures occurred — avoids noise in the happy path.
-          ...failed.length > 0 && {
-            failedEntries: failed.map((r, i) => ({
-              index: results.indexOf(r),
-              collection: r.collection,
-              name: r.name,
-              error: r.error ?? "unknown error"
-            }))
-          }
-        }
+        structuredContent: success(
+          summary,
+          {
+            captured: created.map((r) => ({ entryId: r.entryId, collection: r.collection, name: r.name })),
+            total: created.length,
+            failed: failed.length,
+            ...failed.length > 0 && {
+              failedEntries: failed.map((r) => ({
+                index: results.indexOf(r),
+                collection: r.collection,
+                name: r.name,
+                error: r.error ?? "unknown error"
+              }))
+            }
+          },
+          next
+        )
       };
-    }
+    })
   );
   trackWriteTool(batchCaptureTool);
 }
@@ -2362,6 +2681,15 @@ export {
   STARTER_COLLECTIONS,
   classifyStarterCollection,
   isClassificationAmbiguous,
+  success,
+  failure,
+  parseOrFail,
+  unknownAction,
+  successResult,
+  failureResult,
+  notFoundResult,
+  validationResult,
+  withEnvelope,
   formatQualityReport,
   checkEntryQuality,
   captureSchema,
@@ -2374,4 +2702,4 @@ export {
   formatRubricCoaching,
   formatRubricVerdictSection
 };
-//# sourceMappingURL=chunk-5ZCY6NLZ.js.map
+//# sourceMappingURL=chunk-4ZJEIAA6.js.map