@productbrain/mcp 0.0.1-beta.156 → 0.0.1-beta.158

package/dist/{chunk-X3S5UTTZ.js → chunk-KGGSEIZ3.js}

@@ -257,6 +257,86 @@ function trackFieldQualityWarning(workspaceId, props) {
   } catch {
   }
 }
+function trackSessionCaptureRate(workspaceId, props) {
+  if (!client) return;
+  try {
+    client.capture({
+      distinctId,
+      event: "session_capture_rate",
+      properties: {
+        ...props,
+        workspace_id: workspaceId,
+        source_system: "mcp-server",
+        $groups: { workspace: workspaceId }
+      }
+    });
+  } catch {
+  }
+}
+function trackZeroCaptureAuditFired(workspaceId, props) {
+  if (!client) return;
+  try {
+    client.capture({
+      distinctId,
+      event: "zero_capture_audit_fired",
+      properties: {
+        ...props,
+        workspace_id: workspaceId,
+        source_system: "mcp-server",
+        $groups: { workspace: workspaceId }
+      }
+    });
+  } catch {
+  }
+}
+function trackCaptureContractMiss(workspaceId, props) {
+  if (!client) return;
+  try {
+    client.capture({
+      distinctId,
+      event: "capture_contract_miss",
+      properties: {
+        ...props,
+        workspace_id: workspaceId,
+        source_system: "mcp-server",
+        $groups: { workspace: workspaceId }
+      }
+    });
+  } catch {
+  }
+}
+function trackWriteBackHintServed(workspaceId, props) {
+  if (!client) return;
+  try {
+    client.capture({
+      distinctId,
+      event: "write_back_hint_served",
+      properties: {
+        ...props,
+        workspace_id: workspaceId,
+        source_system: "mcp-server",
+        $groups: { workspace: workspaceId }
+      }
+    });
+  } catch {
+  }
+}
+function trackCommitErrorByCode(workspaceId, props) {
+  if (!client) return;
+  try {
+    client.capture({
+      distinctId,
+      event: "commit_error_by_code",
+      properties: {
+        ...props,
+        workspace_id: workspaceId,
+        source_system: "mcp-server",
+        $groups: { workspace: workspaceId }
+      }
+    });
+  } catch {
+  }
+}
 function getPostHogClient() {
   return client;
 }
@@ -354,10 +434,15 @@ export {
   trackCollectionClassified,
   trackFieldGuidanceApplied,
   trackFieldQualityWarning,
+  trackSessionCaptureRate,
+  trackZeroCaptureAuditFired,
+  trackCaptureContractMiss,
+  trackWriteBackHintServed,
+  trackCommitErrorByCode,
   getPostHogClient,
   shutdownAnalytics,
   MCP_NPX_PACKAGE,
   resolveClient,
   writeClientConfig
 };
-//# sourceMappingURL=chunk-X3S5UTTZ.js.map
+//# sourceMappingURL=chunk-KGGSEIZ3.js.map

package/dist/chunk-KGGSEIZ3.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/analytics.ts","../src/cli/config-writer.ts"],"sourcesContent":["/**\n * PostHog analytics for SynergyOS maintainers — tracks MCP usage (sessions, tool calls).\n * Not user-facing. Key is injected at build time via SYNERGYOS_POSTHOG_KEY.\n * Override with POSTHOG_MCP_KEY for self-hosted deployments.\n */\n\nimport { userInfo } from \"node:os\";\nimport { PostHog } from \"posthog-node\";\n\nlet client: PostHog | null = null;\nlet distinctId = \"anonymous\";\n\nconst POSTHOG_HOST = \"https://eu.i.posthog.com\";\n\n/** Injected at build time: SYNERGYOS_POSTHOG_KEY env when running `npm run build`/publish. */\ndeclare const __SYNERGYOS_POSTHOG_KEY__: string;\n\n/** Only write to stderr when MCP_DEBUG=1 for quieter default DX. */\nfunction log(msg: string): void {\n  if (process.env.MCP_DEBUG === \"1\") {\n    process.stderr.write(msg);\n  }\n}\n\nfunction getBuildTimeKey(): string {\n  try {\n    return __SYNERGYOS_POSTHOG_KEY__;\n  } catch {\n    // Not replaced by bundler (e.g. running via tsx in tests) — treat as absent.\n    return \"\";\n  }\n}\n\nexport function initAnalytics(): void {\n  const apiKey = process.env.POSTHOG_MCP_KEY || getBuildTimeKey();\n  if (!apiKey) {\n    log(\"[MCP-ANALYTICS] No PostHog key — tracking disabled (set SYNERGYOS_POSTHOG_KEY at build time for publish)\\n\");\n    return;\n  }\n\n  client = new PostHog(apiKey, {\n    host: POSTHOG_HOST,\n    flushAt: 1,\n    flushInterval: 5000,\n    featureFlagsPollingInterval: 30_000,\n  });\n  distinctId = process.env.MCP_USER_ID || fallbackDistinctId();\n\n  log(`[MCP-ANALYTICS] Initialized — host=${POSTHOG_HOST} distinctId=${distinctId}\\n`);\n}\n\nfunction fallbackDistinctId(): string {\n  try {\n    return userInfo().username;\n  } catch {\n    return `os-${process.pid}`;\n  }\n}\n\nexport function trackSessionStarted(\n  workspaceId: string,\n  serverVersion: string,\n): void {\n  if (!client) return;\n  client.capture({\n    distinctId,\n    event: \"mcp_session_started\",\n    properties: {\n      workspace_id: workspaceId,\n      server_version: serverVersion,\n      source: \"mcp-server\",\n      $groups: { workspace: workspaceId },\n    },\n  });\n}\n\nexport function trackToolCall(\n  fn: string,\n  status: \"ok\" | \"error\",\n  durationMs: number,\n  workspaceId: string,\n  errorMsg?: string,\n): void {\n  const properties: Record<string, unknown> = {\n    tool: fn,\n    status,\n    duration_ms: durationMs,\n    workspace_id: workspaceId,\n    source: \"mcp-server\",\n    $groups: { workspace: workspaceId },\n  };\n  if (errorMsg) properties.error = errorMsg;\n\n  if (!client) return;\n  client.capture({\n    distinctId,\n    event: \"mcp_tool_called\",\n    properties,\n  });\n}\n\nexport function trackSetupStarted(): void {\n  if (!client) return;\n  client.capture({\n    distinctId,\n    event: \"mcp_setup_started\",\n    properties: {\n      source: \"mcp-server\",\n      platform: process.platform,\n    },\n  });\n}\n\nexport function trackSetupCompleted(\n  chosenClient: string,\n  outcome: \"config_written\" | \"config_existed\" | \"snippet_shown\" | \"write_error\",\n): void {\n  if (!client) return;\n  client.capture({\n    distinctId,\n    event: \"mcp_setup_completed\",\n    properties: {\n      client: chosenClient,\n      outcome,\n      source: \"mcp-server\",\n      platform: process.platform,\n    },\n  });\n}\n\nexport function trackQualityVerdict(\n  workspaceId: string,\n  props: {\n    entry_id: string;\n    entry_type: string;\n    tier: string;\n    context: string;\n    passed: boolean;\n    source: string;\n    criteria_total: number;\n    criteria_failed: number;\n    llm_scheduled: boolean;\n  },\n): void {\n  if (!client) return;\n  client.capture({\n    distinctId,\n    event: \"quality_verdict_generated\",\n    properties: {\n      ...props,\n      workspace_id: workspaceId,\n      source_system: \"mcp-server\",\n      $groups: { workspace: workspaceId },\n    },\n  });\n}\n\nexport function trackQualityCheck(\n  workspaceId: string,\n  props: {\n    entry_id: string;\n    entry_type: string;\n    tier: string;\n    passed: boolean;\n    source: string;\n    llm_status?: string;\n    llm_duration_ms?: number;\n    llm_error?: string;\n    has_roger_martin: boolean;\n  },\n): void {\n  if (!client) return;\n  client.capture({\n    distinctId,\n    event: \"quality_verdict_checked\",\n    properties: {\n      ...props,\n      workspace_id: workspaceId,\n      source_system: \"mcp-server\",\n      $groups: { workspace: workspaceId },\n    },\n  });\n}\n\nexport type ClassifierReasonCategory =\n  | \"auto-routed\"\n  | \"low-confidence\"\n  | \"ambiguous\"\n  | \"non-provisioned\";\n\ntype CaptureClassifierTelemetryProps = {\n  predicted_collection: string;\n  confidence: number;\n  auto_routed: boolean;\n  reason_category: ClassifierReasonCategory;\n  explicit_collection_provided: boolean;\n};\n\nfunction trackCaptureClassifierEvent(\n  event: \"mcp_capture_classifier_evaluated\" | \"mcp_capture_classifier_auto_routed\" | \"mcp_capture_classifier_fallback\",\n  workspaceId: string,\n  props: CaptureClassifierTelemetryProps,\n): void {\n  if (!client) return;\n  try {\n    client.capture({\n      distinctId,\n      event,\n      properties: {\n        ...props,\n        workspace_id: workspaceId,\n        source_system: \"mcp-server\",\n        $groups: { workspace: workspaceId },\n      },\n    });\n  } catch {\n    // Analytics are advisory and must never break capture flow.\n  }\n}\n\nexport function trackCaptureClassifierEvaluated(\n  workspaceId: string,\n  props: CaptureClassifierTelemetryProps,\n): void {\n  trackCaptureClassifierEvent(\"mcp_capture_classifier_evaluated\", workspaceId, props);\n}\n\nexport function trackCaptureClassifierAutoRouted(\n  workspaceId: string,\n  props: CaptureClassifierTelemetryProps,\n): void {\n  trackCaptureClassifierEvent(\"mcp_capture_classifier_auto_routed\", workspaceId, props);\n}\n\nexport function trackCaptureClassifierFallback(\n  workspaceId: string,\n  props: CaptureClassifierTelemetryProps,\n): void {\n  trackCaptureClassifierEvent(\"mcp_capture_classifier_fallback\", workspaceId, props);\n}\n\n/** GLO-26 / TEN-156: every SSOT commit for PostHog funnels (split auto vs manual). */\nexport function trackChainEntryCommitted(\n  workspaceId: string,\n  props: {\n    entry_id: string;\n    collection?: string;\n    commit_method: \"auto\" | \"manual\";\n    surface:\n      | \"mcp_commit_tool\"\n      | \"mcp_capture\"\n      | \"mcp_wrapup\";\n  },\n): void {\n  if (!client) return;\n  try {\n    client.capture({\n      distinctId,\n      event: \"chain_entry_committed\",\n      properties: {\n        workspace_id: workspaceId,\n        source_system: \"mcp-server\",\n        $groups: { workspace: workspaceId },\n        ...props,\n      },\n    });\n  } catch {\n    // Analytics must never break the tool path.\n  }\n}\n\nexport function trackKnowledgeGap(\n  workspaceId: string,\n  props: {\n    query: string;\n    tool: string;\n    action: string;\n    gap_type: \"search_zero\" | \"context_task_empty\" | \"context_entry_isolated\" | \"context_graph_empty\";\n    collection_scope?: string;\n  },\n): void {\n  if (!client) return;\n  try {\n    client.capture({\n      distinctId,\n      event: \"knowledge_gap_detected\",\n      properties: {\n        ...props,\n        query: props.query.slice(0, 200),\n        workspace_id: workspaceId,\n        source_system: \"mcp-server\",\n        $groups: { workspace: workspaceId },\n      },\n    });\n  } catch {\n    // Analytics must never break the tool response path.\n  }\n}\n\n// ── BET-272 S6 / STD-155: Capture intelligence observability ────────────────\n\n/** Fires when formative quality hints are returned at capture time. */\nexport function trackCaptureQualityHints(\n  workspaceId: string,\n  props: {\n    collection: string;\n    hint_count: number;\n    hint_fields: string[];\n  },\n): void {\n  if (!client) return;\n  try {\n    client.capture({\n      distinctId,\n      event: \"mcp_capture_quality_hints\",\n      properties: {\n        ...props,\n        workspace_id: workspaceId,\n        source_system: \"mcp-server\",\n        $groups: { workspace: workspaceId },\n      },\n    });\n  } catch {\n    // Analytics must never break capture flow.\n  }\n}\n\n/** Fires when relation suggestions are returned at capture time. */\nexport function trackCaptureRelationSuggestions(\n  workspaceId: string,\n  props: {\n    collection: string;\n    suggestion_count: number;\n    relation_types: string[];\n    avg_confidence: number;\n  },\n): void {\n  if (!client) return;\n  try {\n    client.capture({\n      distinctId,\n      event: \"mcp_capture_relation_suggestions\",\n      properties: {\n        ...props,\n        workspace_id: workspaceId,\n        source_system: \"mcp-server\",\n        $groups: { workspace: workspaceId },\n      },\n    });\n  } catch {\n    // Analytics must never break capture flow.\n  }\n}\n\n// ── BET-288 S0: Collection classification confusion matrix telemetry ────────\n\n/**\n * Fires on every collection classification (auto-routed, fallback, explicit-provided).\n * Captures the full confusion signal: predicted collection, runner-up, thinkingLayer,\n * and confidence scores. This is the baseline measurement for BET-288 algorithm changes.\n */\nexport function trackCollectionClassified(\n  workspaceId: string,\n  props: {\n    collection_slug: string;\n    thinking_layer: string | null;\n    confidence: number;\n    classified_by: \"llm\" | \"heuristic\";\n    confidence_tier: \"high\" | \"medium\" | \"low\";\n    alternative_slug: string | null;\n    alternative_confidence: number | null;\n    explicit_collection_provided: boolean;\n    auto_routed: boolean;\n  },\n): void {\n  if (!client) return;\n  try {\n    client.capture({\n      distinctId,\n      event: \"collection_classified\",\n      properties: {\n        ...props,\n        workspace_id: workspaceId,\n        source_system: \"mcp-server\",\n        $groups: { workspace: workspaceId },\n      },\n    });\n  } catch {\n    // Analytics must never break the capture flow.\n  }\n}\n\n// ── BET-289 S5: Field-level writing guidance telemetry ────────────────────────\n\n/** Fires when field guidance is injected into a capture prompt or response. */\nexport function trackFieldGuidanceApplied(\n  workspaceId: string,\n  props: {\n    collection: string;\n    guided_field_count: number;\n  },\n): void {\n  if (!client) return;\n  try {\n    client.capture({\n      distinctId,\n      event: \"field_guidance_applied\",\n      properties: {\n        ...props,\n        workspace_id: workspaceId,\n        source_system: \"mcp-server\",\n        $groups: { workspace: workspaceId },\n      },\n    });\n  } catch {\n    // Analytics must never break the capture flow.\n  }\n}\n\n/** Fires when commit-time heuristic detects field guidance violations. */\nexport function trackFieldQualityWarning(\n  workspaceId: string,\n  props: {\n    warning_count: number;\n    warning_types: string[];\n  },\n): void {\n  if (!client) return;\n  try {\n    client.capture({\n      distinctId,\n      event: \"field_quality_warning\",\n      properties: {\n        ...props,\n        workspace_id: workspaceId,\n        source_system: \"mcp-server\",\n        $groups: { workspace: workspaceId },\n      },\n    });\n  } catch {\n    // Analytics must never break the commit flow.\n  }\n}\n\n/** Fires when skipGuidanceCheck is used to bypass guidance validation. */\nexport function trackFieldQualityOverride(\n  workspaceId: string,\n): void {\n  if (!client) return;\n  try {\n    client.capture({\n      distinctId,\n      event: \"field_quality_override\",\n      properties: {\n        workspace_id: workspaceId,\n        source_system: \"mcp-server\",\n        $groups: { workspace: workspaceId },\n      },\n    });\n  } catch {\n    // Analytics must never break the commit flow.\n  }\n}\n\n// ── WP-306 S3: Write-Back Measurement (capture rate insights) ──────────────\n\n/** Fires on session close to track session capture rate. */\nexport function trackSessionCaptureRate(\n  workspaceId: string,\n  props: {\n    entries_created: number;\n    entries_modified: number;\n    relations_created: number;\n    had_captures: boolean;\n  },\n): void {\n  if (!client) return;\n  try {\n    client.capture({\n      distinctId,\n      event: \"session_capture_rate\",\n      properties: {\n        ...props,\n        workspace_id: workspaceId,\n        source_system: \"mcp-server\",\n        $groups: { workspace: workspaceId },\n      },\n    });\n  } catch {\n    // Analytics must never break session closure.\n  }\n}\n\n/** Fires when captureAudit is triggered (activity but no captures). */\nexport function trackZeroCaptureAuditFired(\n  workspaceId: string,\n  props: {\n    suggestion_count: number;\n  },\n): void {\n  if (!client) return;\n  try {\n    client.capture({\n      distinctId,\n      event: \"zero_capture_audit_fired\",\n      properties: {\n        ...props,\n        workspace_id: workspaceId,\n        source_system: \"mcp-server\",\n        $groups: { workspace: workspaceId },\n      },\n    });\n  } catch {\n    // Analytics must never break wrapup flow.\n  }\n}\n\n// ── WP-316 S1b: Capture contract observability ──────────────────────────────\n\n/** Fires when a capture-contract resource request references an unknown collection slug. */\nexport function trackCaptureContractMiss(\n  workspaceId: string,\n  props: {\n    slug: string;\n  },\n): void {\n  if (!client) return;\n  try {\n    client.capture({\n      distinctId,\n      event: \"capture_contract_miss\",\n      properties: {\n        ...props,\n        workspace_id: workspaceId,\n        source_system: \"mcp-server\",\n        $groups: { workspace: workspaceId },\n      },\n    });\n  } catch {\n    // Analytics must never break the resource response path.\n  }\n}\n\n/** Fires when writeBackHints are included in an orient response. */\nexport function trackWriteBackHintServed(\n  workspaceId: string,\n  props: {\n    hint_count: number;\n    has_task: boolean;\n  },\n): void {\n  if (!client) return;\n  try {\n    client.capture({\n      distinctId,\n      event: \"write_back_hint_served\",\n      properties: {\n        ...props,\n        workspace_id: workspaceId,\n        source_system: \"mcp-server\",\n        $groups: { workspace: workspaceId },\n      },\n    });\n  } catch {\n    // Analytics must never break orient flow.\n  }\n}\n\n/**\n * WP-316 S1a: Fires when commit-entry fails with a structured error code.\n * Enables observability on which validation errors block commits most often.\n */\nexport function trackCommitErrorByCode(\n  workspaceId: string,\n  props: {\n    error_code: string;\n    missing_field_count: number;\n    field_error_count: number;\n    entry_id: string;\n  },\n): void {\n  if (!client) return;\n  try {\n    client.capture({\n      distinctId,\n      event: \"commit_error_by_code\",\n      properties: {\n        ...props,\n        workspace_id: workspaceId,\n        source_system: \"mcp-server\",\n        $groups: { workspace: workspaceId },\n      },\n    });\n  } catch {\n    // Analytics must never break the commit error path.\n  }\n}\n\nexport function getPostHogClient(): PostHog | null {\n  return client;\n}\n\nexport async function shutdownAnalytics(): Promise<void> {\n  await client?.shutdown();\n}\n","/**\n * Multi-client MCP config detection and writer.\n *\n * Supports:\n *  - Cursor: .cursor/mcp.json in cwd (project-level)\n *  - Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)\n *                    %APPDATA%/Claude/claude_desktop_config.json (Windows)\n *\n * The writer reads existing config, merges the new server entry (never\n * overwrites existing entries), and writes back. Falls back to printing\n * a snippet for unsupported OS or unknown formats.\n */\n\nimport { existsSync, readFileSync, writeFileSync, mkdirSync } from \"node:fs\";\nimport { join, dirname } from \"node:path\";\nimport { homedir, platform } from \"node:os\";\n\nexport interface McpClientInfo {\n  name: string;\n  configPath: string;\n}\n\nconst SERVER_ENTRY_KEY = \"Product Brain\";\nconst LEGACY_ENTRY_KEY = \"productbrain\";\n\n/**\n * Canonical npx package specifier. Update here when exiting beta.\n * Frontend mirror: src/lib/constants/mcp.ts\n * Business rule: BR-84 (Chain)\n */\nexport const MCP_NPX_PACKAGE = \"@productbrain/mcp@beta\";\n\nfunction buildServerEntry(apiKey: string) {\n  return {\n    command: \"npx\",\n    args: [\"-y\", MCP_NPX_PACKAGE],\n    env: { PRODUCTBRAIN_API_KEY: apiKey },\n  };\n}\n\n// ── Detection ───────────────────────────────────────────────────────────\n\nfunction getCursorConfigPath(): string {\n  return join(process.cwd(), \".cursor\", \"mcp.json\");\n}\n\nfunction getClaudeDesktopConfigPath(): string | null {\n  const os = platform();\n  if (os === \"darwin\") {\n    return join(\n      homedir(),\n      \"Library\",\n      \"Application Support\",\n      \"Claude\",\n      \"claude_desktop_config.json\",\n    );\n  }\n  if (os === \"win32\") {\n    const appData = process.env.APPDATA ?? join(homedir(), \"AppData\", \"Roaming\");\n    return join(appData, \"Claude\", \"claude_desktop_config.json\");\n  }\n  // Linux: no official Claude Desktop location yet\n  return null;\n}\n\nexport function resolveClient(name: \"Cursor\" | \"Claude Desktop\"): McpClientInfo | null {\n  if (name === \"Cursor\") {\n    return { name, configPath: getCursorConfigPath() };\n  }\n  const configPath = getClaudeDesktopConfigPath();\n  return configPath ? { name, configPath } : null;\n}\n\n// ── Writing ─────────────────────────────────────────────────────────────\n\nfunction readJsonSafe(path: string): Record<string, any> {\n  if (!existsSync(path)) return {};\n  try {\n    return JSON.parse(readFileSync(path, \"utf-8\"));\n  } catch {\n    return {};\n  }\n}\n\n/**\n * Write or merge the Product Brain server entry into a client config file.\n * Migrates legacy \"productbrain\" key to \"Product Brain\" when present.\n * Returns true if the config was written, false if already present.\n */\nexport async function writeClientConfig(\n  client: McpClientInfo,\n  apiKey: string,\n): Promise<boolean> {\n  const config = readJsonSafe(client.configPath);\n\n  const serversKey = \"mcpServers\";\n  if (!config[serversKey]) config[serversKey] = {};\n\n  // Migrate legacy \"productbrain\" key or update existing Product Brain with new API key\n  if (config[serversKey][LEGACY_ENTRY_KEY]) {\n    const legacy = config[serversKey][LEGACY_ENTRY_KEY];\n    config[serversKey][SERVER_ENTRY_KEY] = {\n      ...buildServerEntry(apiKey),\n      env: { ...legacy.env, PRODUCTBRAIN_API_KEY: legacy.env?.PRODUCTBRAIN_API_KEY ?? apiKey },\n    };\n    delete config[serversKey][LEGACY_ENTRY_KEY];\n  } else {\n    const existing = config[serversKey][SERVER_ENTRY_KEY];\n    config[serversKey][SERVER_ENTRY_KEY] = existing\n      ? { ...existing, env: { ...existing.env, PRODUCTBRAIN_API_KEY: apiKey } }\n      : buildServerEntry(apiKey);\n  }\n\n  const dir = dirname(client.configPath);\n  if (!existsSync(dir)) {\n    mkdirSync(dir, { recursive: true });\n  }\n\n  writeFileSync(client.configPath, JSON.stringify(config, null, 2) + \"\\n\", \"utf-8\");\n  return true;\n}\n"],"mappings":"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","names":["client"]}

package/dist/{chunk-GMSHWOXT.js → chunk-ZZHGJKLF.js}

@@ -3,17 +3,22 @@ import {
   trackCaptureClassifierAutoRouted,
   trackCaptureClassifierEvaluated,
   trackCaptureClassifierFallback,
+  trackCaptureContractMiss,
   trackCaptureQualityHints,
   trackCaptureRelationSuggestions,
   trackChainEntryCommitted,
   trackCollectionClassified,
+  trackCommitErrorByCode,
   trackFieldGuidanceApplied,
   trackFieldQualityWarning,
   trackKnowledgeGap,
   trackQualityCheck,
   trackQualityVerdict,
-  trackToolCall
-} from "./chunk-X3S5UTTZ.js";
+  trackSessionCaptureRate,
+  trackToolCall,
+  trackWriteBackHintServed,
+  trackZeroCaptureAuditFired
+} from "./chunk-KGGSEIZ3.js";
 
 // src/auth.ts
 import { AsyncLocalStorage } from "async_hooks";
@@ -83,11 +88,17 @@ var DEFAULT_CLOUD_URL = "https://gateway.productbrain.io";
 var McpCallError = class extends Error {
   status;
   code;
-  constructor(message, status, code) {
+  /** WP-316 S1a: Structured commit validation — required field keys missing from entry.data. */
+  missingRequiredFields;
+  /** WP-316 S1a: Structured commit validation — field-level data errors. */
+  fieldErrors;
+  constructor(message, status, code, missingRequiredFields, fieldErrors) {
     super(message);
     this.name = "McpCallError";
     this.status = status;
     this.code = code;
+    this.missingRequiredFields = missingRequiredFields;
+    this.fieldErrors = fieldErrors;
   }
 };
 var CACHE_TTL_MS = 6e4;
@@ -324,7 +335,13 @@ async function mcpCall(fn, args = {}) {
   if (!res.ok || json.error) {
     const msg = json.error ?? "unknown error";
     audit(fn, "error", Date.now() - start, json.code ? `${msg} [${json.code}]` : msg);
-    throw new McpCallError(`MCP call "${fn}" failed (${res.status}): ${msg}`, res.status, json.code);
+    throw new McpCallError(
+      `MCP call "${fn}" failed (${res.status}): ${msg}`,
+      res.status,
+      json.code,
+      Array.isArray(json.missingRequiredFields) ? json.missingRequiredFields : void 0,
+      Array.isArray(json.fieldErrors) ? json.fieldErrors : void 0
+    );
   }
   audit(fn, "ok", Date.now() - start);
   const data = json.data;
@@ -748,7 +765,13 @@ function asMcpCallError(err) {
     const code = err.code;
     const match = MCP_CALL_ERROR_RE.exec(err.message);
     if (match) {
-      return { code, cleanMessage: match[1] };
+      const e = err;
+      return {
+        code,
+        cleanMessage: match[1],
+        missingRequiredFields: Array.isArray(e.missingRequiredFields) ? e.missingRequiredFields : void 0,
+        fieldErrors: Array.isArray(e.fieldErrors) ? e.fieldErrors : void 0
+      };
     }
   }
   return void 0;
@@ -815,9 +838,19 @@ function classifyError(err) {
   }
   const mcpErr = asMcpCallError(err);
   if (mcpErr) {
-    const { code: convexCode, cleanMessage } = mcpErr;
+    const { code: convexCode, cleanMessage, missingRequiredFields, fieldErrors } = mcpErr;
     if (convexCode === "VALIDATION_FAILED") {
-      return { code: "VALIDATION_ERROR", message: cleanMessage };
+      const hasDiagnostics = missingRequiredFields?.length || fieldErrors?.length;
+      return {
+        code: "VALIDATION_ERROR",
+        message: cleanMessage,
+        ...hasDiagnostics ? {
+          diagnostics: {
+            ...missingRequiredFields?.length ? { missingRequiredFields } : {},
+            ...fieldErrors?.length ? { fieldErrors } : {}
+          }
+        } : {}
+      };
     }
     if (convexCode === "NOT_FOUND") {
       return {
@@ -976,7 +1009,9 @@ function withEnvelope(handler) {
           classified.code,
           classified.message,
           classified.recovery,
-          classified.availableActions
+          classified.availableActions,
+          // WP-316 S1a: pass structured diagnostics (e.g. missingRequiredFields, fieldErrors)
+          classified.diagnostics
         ),
         _meta: { durationMs }
       };
@@ -2803,6 +2838,16 @@ Use \`entries action=get\` to inspect the existing entry, or \`update-entry\` to
         type: f.type,
         ...f.required && { required: true }
       }));
+      const captureContractForEnvelope = {
+        requiredFields: (col.fields ?? []).filter((f) => f.required === true).map((f) => f.key),
+        allFields: (col.fields ?? []).map((f) => ({
+          key: f.key,
+          required: f.required === true,
+          type: f.type,
+          ...f.helpText ? { helpText: f.helpText } : {}
+        })),
+        ...col.captureExpectation ? { captureExpectation: col.captureExpectation } : {}
+      };
       const totalMs = Date.now() - timingStart;
       const timing = {
         classifyMs: tAfterClassify - timingStart,
@@ -2840,6 +2885,8 @@ Use \`entries action=get\` to inspect the existing entry, or \`update-entry\` to
             },
             next
           ),
+          // WP-316 S1a: Populate contract field so agents know required fields upfront.
+          contract: captureContractForEnvelope,
           _meta: { timing }
         }
       };
@@ -3849,11 +3896,30 @@ ${formatted}` }],
         });
       } catch {
       }
-      const result = await mcpMutation("chain.commitEntry", {
-        entryId,
-        author: getAgentSessionId() ? `agent:${getAgentSessionId()}` : void 0,
-        sessionId: getAgentSessionId() ?? void 0
-      });
+      let result;
+      try {
+        result = await mcpMutation("chain.commitEntry", {
+          entryId,
+          author: getAgentSessionId() ? `agent:${getAgentSessionId()}` : void 0,
+          sessionId: getAgentSessionId() ?? void 0
+        });
+      } catch (commitErr) {
+        const errCode = commitErr?.code;
+        if (errCode === "VALIDATION_FAILED") {
+          try {
+            const wsCtx2 = await getWorkspaceContext();
+            const e = commitErr;
+            trackCommitErrorByCode(wsCtx2.workspaceId, {
+              error_code: errCode,
+              missing_field_count: e.missingRequiredFields?.length ?? 0,
+              field_error_count: e.fieldErrors?.length ?? 0,
+              entry_id: entryId
+            });
+          } catch {
+          }
+        }
+        throw commitErr;
+      }
       const docId = result?._id ?? entry._id;
       const wsCtx = await getWorkspaceContext();
       const isProposal = result?.status === "proposal_created";
@@ -3942,6 +4008,17 @@ ${formatted}` }],
           lines.push(`  \u2192 ${epistemic.action}`);
         }
       }
+      let captureContract;
+      try {
+        const collSlug = entry.collectionSlug ?? entry.collection?.slug;
+        if (collSlug) {
+          captureContract = await mcpQuery(
+            "chain.getCaptureContract",
+            { collectionSlug: collSlug }
+          ) ?? void 0;
+        }
+      } catch {
+      }
       const next = isProposal ? [
         { tool: "entries", description: "View entry", parameters: { action: "get", entryId } }
       ] : [
@@ -3949,21 +4026,25 @@ ${formatted}` }],
         { tool: "entries", description: "View committed entry", parameters: { action: "get", entryId } }
       ];
       const summary = isProposal ? `Proposal created for ${entryId} (${entry.name}). Awaiting consent.` : `Committed ${entryId} (${entry.name}) to the Chain.`;
+      const commitSuccessEnvelope = success(
+        summary,
+        {
+          entryId,
+          name: entry.name,
+          outcome: isProposal ? "proposal_created" : "committed",
+          qualityVerdict: coachingResult?.verdict ?? void 0,
+          source: coachingResult?.source ?? void 0,
+          contradictions: advisoryWarnings.length,
+          ...epistemic ? { epistemicStatus: epistemic } : {}
+        },
+        next
+      );
+      if (captureContract) {
+        commitSuccessEnvelope.contract = captureContract;
+      }
       return {
         content: [{ type: "text", text: lines.join("\n") }],
-        structuredContent: success(
-          summary,
-          {
-            entryId,
-            name: entry.name,
-            outcome: isProposal ? "proposal_created" : "committed",
-            qualityVerdict: coachingResult?.verdict ?? void 0,
-            source: coachingResult?.source ?? void 0,
-            contradictions: advisoryWarnings.length,
-            ...epistemic ? { epistemicStatus: epistemic } : {}
-          },
-          next
-        )
+        structuredContent: commitSuccessEnvelope
       };
     })
   );
@@ -7260,6 +7341,30 @@ async function runWrapupReview() {
     lines.push("- **Commit all:** call `session-wrapup` with action `commit-all`");
     lines.push("- **Skip:** call `session action=close` \u2014 drafts remain for next session's orient recovery.");
   }
+  if (data.captureAudit) {
+    lines.push("");
+    lines.push("### Capture Audit");
+    lines.push("");
+    lines.push(`_${data.captureAudit.message}_`);
+    if (data.captureAudit.suggestions.length > 0) {
+      lines.push("");
+      lines.push("**What to consider capturing:**");
+      for (const s of data.captureAudit.suggestions) {
+        lines.push(`- **${s.collectionSlug}**: ${s.hint}`);
+      }
+    }
+    lines.push("");
+  }
+  lines.push("");
+  lines.push(`> **${data.closeNudge}**`);
+  if (data.captureAudit) {
+    const wsCtx = await getWorkspaceContext();
+    if (wsCtx) {
+      trackZeroCaptureAuditFired(wsCtx.workspaceId, {
+        suggestion_count: data.captureAudit.suggestions.length
+      });
+    }
+  }
   const gapCount = getSessionGaps().length;
   return { text: lines.join("\n"), data, suggestions, gapCount, coherenceVerdict, persistentGaps };
 }
@@ -7583,13 +7688,22 @@ async function handleClose() {
   }
   await closeAgentSession();
   clearSessionGaps();
+  const created = session?.entriesCreated?.length ?? 0;
+  const modified = session?.entriesModified?.length ?? 0;
+  const relations = session?.relationsCreated ?? 0;
+  const wsCtx = await getWorkspaceContext();
+  if (wsCtx) {
+    trackSessionCaptureRate(wsCtx.workspaceId, {
+      entries_created: created,
+      entries_modified: modified,
+      relations_created: relations,
+      had_captures: created > 0
+    });
+  }
   const lines = [
     `Session ${sessionId} closed.`,
     ""
   ];
-  const created = session?.entriesCreated?.length ?? 0;
-  const modified = session?.entriesModified?.length ?? 0;
-  const relations = session?.relationsCreated ?? 0;
   const gates = session?.gateFailures ?? 0;
   const warnings = session?.contradictionWarnings ?? 0;
   if (session) {
@@ -8370,7 +8484,7 @@ var IMPLEMENTATION_REVIEW_WORKFLOW_DESCRIPTOR = {
 
 ## Your Behavior
 
-1. **Tool-heavy, not chat-heavy.** Each round calls specific tools: orient, quality, verify, chain-review, context action=gather, review-against-rules. Use Context7 (query-docs) for relevant testing and framework docs \u2014 not for Chain truth.
+1. **Tool-heavy, not chat-heavy.** Each round calls specific tools: orient, quality, verify, chain-review, context action=gather, review-against-rules. Use Context7 **CLI** (\`npx ctx7@latest library\` then \`docs\`) for relevant testing and framework docs \u2014 not for Chain truth. Do not use Context7 MCP.
 2. **Spawn sub-agents** for parallel review: (a) code/architecture review, (b) test honesty (did we edit tests to pass or do they validate real behavior?). Max 2 agents in parallel, 30s budget each. **Constrain each sub-agent to the stated review scope only.**
 3. **Fix-as-you-go (FEAT-172).** When you find a HIGH or MEDIUM issue: fix it immediately, verify (lints, types), then proceed. The user sees clean work, not a list of issues. Only defer if estimated >5 min \u2014 capture deferred items as tensions. If user says "skip", capture as tension and continue.
 4. **Chain is SSOT.** Call orient or start first. Use entries action=search and context action=gather to load relevant BETs, DECs, BRs. If findings conflict with Chain entries, report the conflict and cite the entry ID.
@@ -8387,7 +8501,7 @@ var IMPLEMENTATION_REVIEW_WORKFLOW_DESCRIPTOR = {
 - \`verify\` \u2014 glossary code mappings, cross-references vs codebase
 - \`review-against-rules\` (domain) \u2014 business rule compliance
 - \`context action=gather task="implementation review for [BET-ID]"\` \u2014 related knowledge
-- Context7 \`query-docs\` \u2014 relevant testing and framework best practices (resolve-library-id first)
+- Context7 CLI \u2014 \`npx ctx7@latest library\` then \`npx ctx7@latest docs\` for framework/testing docs (not Chain truth)
 - \`session-wrapup\` \u2014 before close
 
 ## Sub-Agent Classification (for test failures)
@@ -8439,7 +8553,7 @@ This block is the final deliverable of the review. Everything else is supporting
       label: "Code & Test Honesty",
       type: "open",
       instruction: "Spawn sub-agents to review implementation and tests for the stated scope only. Fix every HIGH/MEDIUM finding before proceeding. Did we meet high standards? Are tests validating real behavior or did we edit them just to pass?",
-      facilitatorGuidance: "Restrict all review to the scope stated in Round 01 (by default, work in this conversation only). Spawn 1\u20132 sub-agents in parallel: (1) explore agent \u2014 code review, architecture boundaries, type-safety for scoped files only. (2) explore agent \u2014 test review for scoped code: are tests asserting real behavior or were they edited to pass? Pass the scope (files/BET) explicitly to sub-agents so they do not touch other work. Use Context7 (query-docs) for relevant testing and framework best practices if needed. Classify any test failures: staleness, regression, or flaky. **Fix-as-you-go (FEAT-172):** For every HIGH/MEDIUM finding: fix immediately, run lints, verify types. Only defer fixes estimated >5 min \u2014 capture deferred items as tensions on the Chain. After fixing, do a boy-scout pass on each scoped file: clean imports, improve naming, remove dead code. **Counter-Metric Mandate (STD-19):** When reporting test coverage, accuracy, or any quantitative result, include the denominator, what was excluded, and at least one counter-metric. Never report accuracy without recall. Never report pass rate without coverage. Synthesize: findings, fixes applied, implementation grade, test honesty verdict.",
+      facilitatorGuidance: "Restrict all review to the scope stated in Round 01 (by default, work in this conversation only). Spawn 1\u20132 sub-agents in parallel: (1) explore agent \u2014 code review, architecture boundaries, type-safety for scoped files only. (2) explore agent \u2014 test review for scoped code: are tests asserting real behavior or were they edited to pass? Pass the scope (files/BET) explicitly to sub-agents so they do not touch other work. Use Context7 CLI (npx ctx7 library/docs) for relevant testing and framework best practices if needed. Classify any test failures: staleness, regression, or flaky. **Fix-as-you-go (FEAT-172):** For every HIGH/MEDIUM finding: fix immediately, run lints, verify types. Only defer fixes estimated >5 min \u2014 capture deferred items as tensions on the Chain. After fixing, do a boy-scout pass on each scoped file: clean imports, improve naming, remove dead code. **Counter-Metric Mandate (STD-19):** When reporting test coverage, accuracy, or any quantitative result, include the denominator, what was excluded, and at least one counter-metric. Never report accuracy without recall. Never report pass rate without coverage. Synthesize: findings, fixes applied, implementation grade, test honesty verdict.",
       outputSchema: {
         field: "codeAndTests",
         description: "Implementation grade, test honesty, refactor suggestions",
@@ -8515,7 +8629,7 @@ This block is the final deliverable of the review. Everything else is supporting
 
 1. **Tool failure**: Explain what failed. Continue with what you have. The conversation is the record.
 2. **Sub-agent timeout**: Proceed without that agent's output. Note what wasn't checked.
-3. **Context7 unavailable**: Skip library doc validation. Rely on Chain and codebase review.
+3. **Context7 CLI unavailable** (e.g. auth/network): Skip library doc validation. Rely on Chain and codebase review.
 4. **MCP unreachable**: Run from conversation knowledge. Summarize findings. Offer to capture manually later.
 
 The review must never fail silently. Always end with BET/chain IDs.`
@@ -13249,6 +13363,15 @@ function registerOrientTool(server) {
       } catch {
       }
       const hasTaskGrounding = Boolean(task && orientEntries?.taskContext?.context?.length > 0);
+      if (wsCtx && hasTaskGrounding && orientEntries?.writeBackHints) {
+        const hints = Array.isArray(orientEntries.writeBackHints) ? orientEntries.writeBackHints : [];
+        if (hints.length > 0) {
+          trackWriteBackHintServed(wsCtx.workspaceId, {
+            hint_count: hints.length,
+            has_task: !!task
+          });
+        }
+      }
       let openTensions = [];
       try {
         const tensions = await mcpQuery("chain.listEntries", { collectionSlug: "tensions" });
@@ -13327,6 +13450,13 @@ function registerOrientTool(server) {
         if (orientEntries?.taskContext && orientEntries.taskContext.context.length > 0) {
           lines.push(`Task context: ${orientEntries.taskContext.totalFound} relevant entries (${orientEntries.taskContext.confidence} confidence).`);
         }
+        if (orientEntries?.writeBackHints && orientEntries.writeBackHints.length > 0) {
+          lines.push("");
+          lines.push("Write-back hints (what to capture this session):");
+          for (const h of orientEntries.writeBackHints) {
+            lines.push(`  ${h.collectionSlug}: ${h.hint}`);
+          }
+        }
         if (orientEntries?.activeBets?.length > 0) {
           for (const e of orientEntries.activeBets) {
             const tensions = e.linkedTensions;
@@ -13574,6 +13704,16 @@ function registerOrientTool(server) {
               orientEntries.taskContext.constellationBetName
             ));
           }
+          if (orientEntries?.writeBackHints && orientEntries.writeBackHints.length > 0) {
+            lines.push("");
+            lines.push("## Write-Back Hints");
+            lines.push("_What to capture this session (derived from task context):_");
+            lines.push("");
+            for (const h of orientEntries.writeBackHints) {
+              lines.push(`- **${h.collectionSlug}**: ${h.hint}`);
+            }
+            lines.push("");
+          }
           if (orientEntries) {
             const result = await runAlignmentCheck(
               task,
@@ -14990,6 +15130,67 @@ ${entry.labels.map((l) => `- ${l.name ?? l.slug}`).join("\n")}`);
       };
     }
   );
+  server.resource(
+    "chain-collection-capture-contract",
+    new ResourceTemplate("productbrain://collections/{slug}/capture-contract", {
+      list: async () => {
+        const collections = await mcpQuery("chain.listCollections") ?? [];
+        return {
+          resources: collections.map((c) => ({
+            uri: `productbrain://collections/${c.slug}/capture-contract`,
+            name: `${c.icon ?? ""} ${c.name} \u2014 capture contract`.trim()
+          }))
+        };
+      }
+    }),
+    async (uri, { slug }) => {
+      const collectionSlug = slug;
+      let workspaceId = null;
+      try {
+        const ctx = await getWorkspaceContext();
+        workspaceId = ctx.workspaceId;
+      } catch {
+      }
+      let contract = null;
+      try {
+        contract = await mcpQuery(
+          "chain.getCaptureContract",
+          { collectionSlug }
+        );
+      } catch {
+        contract = null;
+      }
+      if (!contract) {
+        if (workspaceId) {
+          trackCaptureContractMiss(workspaceId, { slug: collectionSlug });
+        }
+        return {
+          contents: [{
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify({
+              ok: false,
+              error: `Collection '${collectionSlug}' not found in this workspace.`,
+              hint: "Use `collections action=list` to see available collections and their slugs."
+            })
+          }]
+        };
+      }
+      const result = {
+        collectionSlug,
+        requiredFields: contract.requiredFields,
+        allFields: contract.allFields,
+        captureExpectation: contract.captureExpectation
+      };
+      return {
+        contents: [{
+          uri: uri.href,
+          mimeType: "application/json",
+          text: JSON.stringify(result)
+        }]
+      };
+    }
+  );
   server.resource(
     "chain-search",
     new ResourceTemplate("productbrain://search/{query}", {
@@ -15319,4 +15520,4 @@ export {
   SERVER_VERSION,
   createProductBrainServer
 };
-//# sourceMappingURL=chunk-GMSHWOXT.js.map
+//# sourceMappingURL=chunk-ZZHGJKLF.js.map