@productbrain/mcp 0.0.1-beta.6 → 0.0.1-beta.7

package/dist/index.js

@@ -3,7 +3,6 @@ import {
   bootstrap,
   closeAgentSession,
   getAgentSessionId,
-  getApiKeyScope,
   getAuditLog,
   getWorkspaceContext,
   getWorkspaceId,
@@ -21,7 +20,7 @@ import {
   shutdownAnalytics,
   startAgentSession,
   trackSessionStarted
-} from "./chunk-YLVX2CON.js";
+} from "./chunk-6ZSCQINU.js";
 
 // src/index.ts
 import { readFileSync as readFileSync3 } from "fs";
@@ -717,6 +716,111 @@ Use \`suggest-links\` to discover potential connections, or \`relate-entries\` t
       return { content: [{ type: "text", text: lines.join("\n") }] };
     }
   );
+  server2.registerTool(
+    "create-collection",
+    {
+      title: "Create Collection",
+      description: "Create a new knowledge collection in the workspace. Collections define the structure for entries (like Notion databases or Capacity boards). Provide a slug, name, and field schema.\n\nUse this when setting up a workspace or when the user wants to track a new type of knowledge. Use `list-collections` first to see what already exists.",
+      inputSchema: {
+        slug: z.string().describe("URL-safe identifier, e.g. 'glossary', 'tech-debt', 'api-endpoints'"),
+        name: z.string().describe("Display name, e.g. 'Glossary', 'Tech Debt', 'API Endpoints'"),
+        description: z.string().optional().describe("What this collection is for"),
+        icon: z.string().optional().describe("Emoji icon for the collection"),
+        fields: z.array(z.object({
+          key: z.string().describe("Field key, e.g. 'description', 'severity', 'status'"),
+          label: z.string().describe("Display label, e.g. 'Description', 'Severity'"),
+          type: z.string().describe("Field type: 'string', 'select', 'array', 'number', 'boolean'"),
+          required: z.boolean().optional().describe("Whether this field is required"),
+          options: z.array(z.string()).optional().describe("Options for 'select' type fields"),
+          searchable: z.boolean().optional().describe("Whether this field is included in full-text search")
+        })).describe("Field definitions for the collection schema")
+      },
+      annotations: { destructiveHint: false }
+    },
+    async ({ slug, name, description, icon, fields }) => {
+      requireWriteAccess();
+      try {
+        await mcpMutation("chain.createCollection", {
+          slug,
+          name,
+          description,
+          icon,
+          fields,
+          isDefault: false,
+          createdBy: getAgentSessionId() ? `agent:${getAgentSessionId()}` : "mcp"
+        });
+        const fieldList = fields.map((f) => `  - \`${f.key}\` (${f.type}${f.required ? ", required" : ""}${f.searchable ? ", searchable" : ""})`).join("\n");
+        return {
+          content: [{
+            type: "text",
+            text: `# Collection Created: ${name}
+
+**Slug:** \`${slug}\`
+` + (description ? `**Description:** ${description}
+` : "") + `
+**Fields:**
+${fieldList}
+
+You can now capture entries: \`capture collection="${slug}" name="..." description="..."\``
+          }]
+        };
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        if (msg.includes("already exists")) {
+          return {
+            content: [{
+              type: "text",
+              text: `Collection \`${slug}\` already exists. Use \`update-collection\` to modify it, or choose a different slug.`
+            }]
+          };
+        }
+        throw error;
+      }
+    }
+  );
+  server2.registerTool(
+    "update-collection",
+    {
+      title: "Update Collection",
+      description: "Update an existing collection's name, description, icon, or field schema. Only provide the fields you want to change. Use `list-collections` to see current state.",
+      inputSchema: {
+        slug: z.string().describe("Collection slug to update, e.g. 'glossary', 'tech-debt'"),
+        name: z.string().optional().describe("New display name"),
+        description: z.string().optional().describe("New description"),
+        icon: z.string().optional().describe("New emoji icon"),
+        fields: z.array(z.object({
+          key: z.string(),
+          label: z.string(),
+          type: z.string(),
+          required: z.boolean().optional(),
+          options: z.array(z.string()).optional(),
+          searchable: z.boolean().optional()
+        })).optional().describe("Replacement field schema (replaces all fields \u2014 include existing fields you want to keep)")
+      },
+      annotations: { destructiveHint: false }
+    },
+    async ({ slug, name, description, icon, fields }) => {
+      requireWriteAccess();
+      await mcpMutation("chain.updateCollection", {
+        slug,
+        ...name !== void 0 && { name },
+        ...description !== void 0 && { description },
+        ...icon !== void 0 && { icon },
+        ...fields !== void 0 && { fields }
+      });
+      const changes = [name && "name", description && "description", icon && "icon", fields && "fields"].filter(Boolean).join(", ");
+      return {
+        content: [{
+          type: "text",
+          text: `# Collection Updated: \`${slug}\`
+
+Changed: ${changes || "no changes"}.
+
+Use \`list-collections\` to verify the result.`
+        }]
+      };
+    }
+  );
   server2.registerTool(
     "commit-entry",
     {
@@ -729,7 +833,7 @@ Use \`suggest-links\` to discover potential connections, or \`relate-entries\` t
     },
     async ({ entryId }) => {
       requireWriteAccess();
-      const { runContradictionCheck } = await import("./smart-capture-QGIC5N47.js");
+      const { runContradictionCheck } = await import("./smart-capture-SEINMTTR.js");
       const entry = await mcpQuery("chain.getEntry", { entryId });
       if (!entry) {
         return {
@@ -876,6 +980,8 @@ var CALL_CATEGORIES = {
   "chain.createLabel": "label",
   "chain.updateLabel": "label",
   "chain.deleteLabel": "label",
+  "chain.createCollection": "write",
+  "chain.updateCollection": "write",
   "chain.listCollections": "meta",
   "chain.getCollection": "meta",
   "chain.listLabels": "meta",
@@ -1054,7 +1160,7 @@ function registerHealthTools(server2) {
     "orient",
     {
       title: "Orient \u2014 Start Here",
-      description: "The single entry point for starting a session. Returns everything needed in one call: workspace identity, readiness score, prior session summaries, architecture/governance constraints, open tensions, and suggested next actions.\n\nUse this FIRST. One call to orient replaces 3\u20135 individual tool calls.\n\nCompleting orientation unlocks write tools for the active session.",
+      description: "The single entry point for starting a session. Returns workspace context with a single recommended next action for low-readiness workspaces, or a standup-style briefing for established workspaces.\n\nUse this FIRST. One call to orient replaces 3\u20135 individual tool calls.\n\nCompleting orientation unlocks write tools for the active session.",
       annotations: { readOnlyHint: true }
     },
     async () => {
@@ -1067,15 +1173,13 @@ function registerHealthTools(server2) {
         errors.push(`Workspace: ${e.message}`);
       }
       let priorSessions = [];
-      let maxSessions = 3;
       if (wsCtx) {
         try {
-          priorSessions = await mcpQuery("agent.recentSessions", { limit: maxSessions });
+          priorSessions = await mcpQuery("agent.recentSessions", { limit: 3 });
         } catch {
         }
       }
       let constraintEntries = [];
-      let maxConstraints = 8;
       try {
         const [archEntries, ruleEntries, decisionEntries] = await Promise.all([
           mcpQuery("chain.listEntries", { collectionSlug: "architecture" }),
@@ -1087,7 +1191,7 @@ function registerHealthTools(server2) {
           ...(ruleEntries ?? []).filter((e) => e.status === "Active" || e.status === "active"),
           ...(decisionEntries ?? []).filter((e) => e.status === "Decided" || e.status === "active")
         ];
-        constraintEntries = committed.sort((a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0)).slice(0, maxConstraints);
+        constraintEntries = committed.sort((a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0)).slice(0, 8);
       } catch {
       }
       let openTensions = [];
@@ -1102,109 +1206,100 @@ function registerHealthTools(server2) {
       } catch (e) {
         errors.push(`Readiness: ${e.message}`);
       }
-      const TOKEN_LIMIT = 6e3;
-      const CHAR_PER_TOKEN = 4;
-      const CHAR_LIMIT = TOKEN_LIMIT * CHAR_PER_TOKEN;
       const lines = [];
-      let charCount = 0;
-      function addLine(line) {
-        lines.push(line);
-        charCount += line.length + 1;
-      }
-      function addLines(ls) {
-        for (const l of ls) addLine(l);
-      }
+      const isLowReadiness = readiness && readiness.score < 50;
       if (wsCtx) {
-        addLine(`# ${wsCtx.workspaceName}`);
-        addLine(`_Workspace \`${wsCtx.workspaceSlug}\` \u2014 Product Brain is healthy._`);
+        lines.push(`# ${wsCtx.workspaceName}`);
+        lines.push(`_Workspace \`${wsCtx.workspaceSlug}\` \u2014 Product Brain is healthy._`);
       } else {
-        addLine("# Workspace");
-        addLine("_Could not resolve workspace._");
-      }
-      addLine("");
-      if (readiness) {
-        const scoreBar = "\u2588".repeat(Math.round(readiness.score / 10)) + "\u2591".repeat(10 - Math.round(readiness.score / 10));
-        addLine(`## Readiness: ${readiness.score}%`);
-        addLine(`${scoreBar} ${readiness.passedChecks}/${readiness.totalChecks} requirements`);
-        addLine("");
-        if (readiness.gaps && readiness.gaps.length > 0) {
-          addLine("### Gaps");
-          for (const gap of readiness.gaps) {
-            addLine(`- [ ] **${gap.label}** (${gap.current}/${gap.required}) \u2014 _${gap.guidance}_`);
-          }
-          addLine("");
+        lines.push("# Workspace");
+        lines.push("_Could not resolve workspace._");
+      }
+      lines.push("");
+      if (isLowReadiness && wsCtx?.createdAt) {
+        const ageDays = Math.floor((Date.now() - wsCtx.createdAt) / (1e3 * 60 * 60 * 24));
+        if (ageDays >= 30) {
+          lines.push(`Your workspace has been around for ${ageDays} days but is only ${readiness.score}% ready.`);
+          lines.push("Let's close the gaps \u2014 or if the current structure doesn't fit, we can reshape it.");
+          lines.push("");
         }
       }
-      if (openTensions.length > 0) {
-        addLine(`## Open Tensions (${openTensions.length})`);
-        for (const t of openTensions) {
-          const id = t.entryId ?? "(no ID)";
-          const prio = t.data?.priority ?? "";
-          addLine(`- \`${id}\` ${t.name}${prio ? ` _(${prio})_` : ""}`);
+      if (isLowReadiness) {
+        lines.push(`Readiness: ${readiness.score}% (${readiness.passedChecks}/${readiness.totalChecks}).`);
+        lines.push("");
+        const gaps = readiness.gaps ?? [];
+        if (gaps.length > 0) {
+          const gap = gaps[0];
+          const ctaMap = {
+            "strategy-vision": "Tell me what you're building \u2014 your vision, mission, and north star \u2014 and I'll capture it.",
+            "architecture-layers": "Describe your architecture in a few sentences and I'll capture it.",
+            "glossary-foundation": "What are the key terms your team uses? Tell me a few and I'll add them to the glossary.",
+            "decisions-documented": "What's a recent significant decision your team made? I'll document it with the rationale.",
+            "tensions-tracked": "What's a friction point or pain point you're dealing with? I'll capture it as a tension."
+          };
+          const cta = ctaMap[gap.id] ?? `Tell me about your ${gap.label.toLowerCase()} and I'll capture it.`;
+          lines.push("## Recommended next step");
+          lines.push(`**${gap.label}** (${gap.current}/${gap.required})`);
+          lines.push("");
+          lines.push(cta);
+          lines.push("");
+          lines.push('_Everything stays as a draft until you confirm. Say "commit" or "looks good" to promote to the Chain._');
+          lines.push("");
+          const remainingGaps = gaps.length - 1;
+          if (remainingGaps > 0 || openTensions.length > 0) {
+            lines.push(`_${remainingGaps > 0 ? `${remainingGaps} more gap${remainingGaps === 1 ? "" : "s"}` : ""}${remainingGaps > 0 && openTensions.length > 0 ? " and " : ""}${openTensions.length > 0 ? `${openTensions.length} open tension${openTensions.length === 1 ? "" : "s"}` : ""} \u2014 ask "show full status" for details._`);
+            lines.push("");
+          }
+        }
+      } else if (readiness) {
+        lines.push(`Readiness: ${readiness.score}% (${readiness.passedChecks}/${readiness.totalChecks}).`);
+        lines.push("");
+        const briefingItems = [];
+        if (openTensions.length > 0) {
+          const topTension = openTensions[0];
+          briefingItems.push(`**${openTensions.length} open tension${openTensions.length === 1 ? "" : "s"}** \u2014 top: ${topTension.name}`);
+        }
+        if (priorSessions.length > 0) {
+          const last = priorSessions[0];
+          const date = new Date(last.startedAt).toISOString().split("T")[0];
+          const created = Array.isArray(last.entriesCreated) ? last.entriesCreated.length : last.entriesCreated ?? 0;
+          const modified = Array.isArray(last.entriesModified) ? last.entriesModified.length : last.entriesModified ?? 0;
+          briefingItems.push(`**Last session** (${date}): ${created} created, ${modified} modified`);
         }
-        addLine("");
-      }
-      if (charCount > CHAR_LIMIT * 0.6) {
-        maxSessions = 2;
-        maxConstraints = 5;
-        priorSessions = priorSessions.slice(0, maxSessions);
-        constraintEntries = constraintEntries.slice(0, maxConstraints);
-      }
-      if (priorSessions.length > 0) {
-        addLine(`## Prior Agent Sessions (last ${priorSessions.length})`);
-        for (const s of priorSessions) {
-          const date = new Date(s.startedAt).toISOString().split("T")[0];
-          const created = Array.isArray(s.entriesCreated) ? s.entriesCreated.length : s.entriesCreated ?? 0;
-          const modified = Array.isArray(s.entriesModified) ? s.entriesModified.length : s.entriesModified ?? 0;
-          const stats = `${created} created, ${modified} modified, ${s.relationsCreated ?? 0} relations`;
-          const gates = (s.gateFailures ?? 0) > 0 ? `, ${s.gateFailures} gate failures` : "";
-          const warns = (s.contradictionWarnings ?? 0) > 0 ? `, ${s.contradictionWarnings} contradiction warnings` : "";
-          addLine(`- **${date}** (${s.status}, by ${s.initiatedBy ?? "unknown"}) \u2014 ${stats}${gates}${warns}`);
+        if (readiness.gaps?.length > 0) {
+          briefingItems.push(`**${readiness.gaps.length} gap${readiness.gaps.length === 1 ? "" : "s"}** remaining`);
         }
-        addLine("");
-      }
-      if (constraintEntries.length > 0) {
-        addLine(`## Active Constraints (${constraintEntries.length})`);
-        addLine("_Architecture, business rules, and decisions that govern this workspace._");
-        addLine("");
-        for (const c of constraintEntries) {
-          const id = c.entryId ?? "(no ID)";
-          const col = c.collectionSlug ?? "";
-          const desc = c.data?.description ?? c.data?.rationale ?? "";
-          const truncated = desc.length > 100 ? desc.slice(0, 100) + "..." : desc;
-          addLine(`- \`${id}\` **${c.name}** [${col}] \u2014 ${truncated}`);
+        if (constraintEntries.length > 0) {
+          briefingItems.push(`**${constraintEntries.length} active constraint${constraintEntries.length === 1 ? "" : "s"}** (architecture, rules, decisions)`);
         }
-        addLine("");
+        if (briefingItems.length > 0) {
+          lines.push("## Briefing");
+          for (const item of briefingItems) {
+            lines.push(`- ${item}`);
+          }
+          lines.push("");
+        }
+        lines.push("What would you like to work on?");
+        lines.push("");
       }
       if (errors.length > 0) {
-        addLine("## Errors");
-        for (const err of errors) addLine(`- ${err}`);
-        addLine("");
+        lines.push("## Errors");
+        for (const err of errors) lines.push(`- ${err}`);
+        lines.push("");
       }
       if (agentSessionId) {
         try {
           await mcpCall("agent.markOriented", { sessionId: agentSessionId });
           setSessionOriented(true);
-          const scope = getApiKeyScope();
-          const sessionInfo = `Session ${agentSessionId}.`;
-          const readinessInfo = readiness ? `${readiness.score}% readiness.` : "";
-          const tensionInfo = openTensions.length > 0 ? `${openTensions.length} open tensions.` : "No open tensions.";
-          let sessionSummary = "";
-          if (priorSessions.length > 0) {
-            const lastSession = priorSessions[0];
-            const created = Array.isArray(lastSession.entriesCreated) ? lastSession.entriesCreated.length : lastSession.entriesCreated ?? 0;
-            const modified = Array.isArray(lastSession.entriesModified) ? lastSession.entriesModified.length : lastSession.entriesModified ?? 0;
-            sessionSummary = `Last session: ${created} created, ${modified} modified.`;
-          }
-          addLine("---");
-          addLine(`Orientation complete. ${sessionInfo} Write tools now available. ${readinessInfo} ${tensionInfo} ${sessionSummary}`);
+          lines.push("---");
+          lines.push(`Orientation complete. Session ${agentSessionId}. Write tools available.`);
         } catch {
-          addLine("---");
-          addLine("_Warning: Could not mark session as oriented. Write tools may be restricted._");
+          lines.push("---");
+          lines.push("_Warning: Could not mark session as oriented. Write tools may be restricted._");
         }
       } else {
-        addLine("---");
-        addLine("_No active agent session. Call `agent-start` to begin a tracked session._");
+        lines.push("---");
+        lines.push("_No active agent session. Call `agent-start` to begin a tracked session._");
       }
       return { content: [{ type: "text", text: lines.join("\n") }] };
     }
@@ -3500,9 +3595,9 @@ function buildPresetMenu(wsCtx) {
   const lines = [
     `# Welcome to ${wsCtx.workspaceName}`,
     "",
-    "Your workspace is fresh \u2014 let's set it up. **What are you building?**",
+    "Your workspace is fresh \u2014 let's get it set up together.",
     "",
-    "Choose a preset to tailor your collections:",
+    "**Tell me: what are you building?** Describe it in a sentence or two and I'll help you pick the right structure. Or choose a preset to start from:",
     ""
   ];
   for (const p of presets) {
@@ -3512,7 +3607,7 @@ function buildPresetMenu(wsCtx) {
     "",
     'Call `start` again with your choice, e.g.: `start preset="software-product"`',
     "",
-    "_You can always add, remove, or customize collections later._"
+    "_These are starting points. You can add, remove, or customize collections at any time using `create-collection` and `update-collection`._"
   );
   return lines.join("\n");
 }
@@ -3565,46 +3660,57 @@ Available presets: ${listPresets().map((p) => `\`${p.id}\``).join(", ")}`;
   }
   lines.push(
     "",
-    "## What's next?",
+    "## Let's activate your workspace",
     "",
-    "Start capturing knowledge. Here are example commands for your collections:",
-    ""
-  );
-  for (const col of preset.collections.slice(0, 3)) {
-    lines.push(
-      `- \`capture collection="${col.slug}" name="..." description="..."\` \u2014 add to ${col.name}`
-    );
-  }
-  lines.push(
+    "I'll help you load knowledge step by step. Everything stays as a draft until you confirm it.",
+    "",
+    "**First:** Tell me what you're building in one or two sentences. I'll capture it as your product vision.",
+    "",
+    `_After that, we'll add a few key terms to your glossary and any important decisions. Each entry is a draft \u2014 say "commit" or "looks good" when you're happy with it, and I'll promote it to the Chain (SSOT)._`,
     "",
-    "After capturing a few entries, use `suggest-links` to connect them into a knowledge graph.",
+    "You can also customize your structure anytime: `create-collection`, `update-collection`, or `list-collections`.",
     "",
     "---",
-    `Orientation complete. Write tools are available.`
+    "Orientation complete. Write tools are available."
   );
   return lines.join("\n");
 }
+function computeWorkspaceAge(createdAt) {
+  if (!createdAt) return { ageDays: 0, isNeglected: false };
+  const ageDays = Math.floor((Date.now() - createdAt) / (1e3 * 60 * 60 * 24));
+  return { ageDays, isNeglected: ageDays >= 30 };
+}
+function pickNextAction(gaps, openTensions, priorSessions) {
+  if (gaps.length === 0 && openTensions.length === 0) return null;
+  if (gaps.length > 0) {
+    const gap = gaps[0];
+    const ctaMap = {
+      "strategy-vision": "Tell me what you're building \u2014 your vision, mission, and north star \u2014 and I'll capture it.",
+      "architecture-layers": "Describe your architecture in a few sentences and I'll capture it.",
+      "glossary-foundation": "What are the key terms your team uses? Tell me a few and I'll add them to the glossary.",
+      "decisions-documented": "What's a recent significant decision your team made? I'll document it with the rationale.",
+      "tensions-tracked": "What's a friction point or pain point you're dealing with? I'll capture it as a tension."
+    };
+    const cta = ctaMap[gap.id] ?? `Tell me about your ${gap.label.toLowerCase()} and I'll capture it.`;
+    return { action: gap.label, cta };
+  }
+  if (openTensions.length > 0) {
+    const t = openTensions[0];
+    return {
+      action: `Open tension: ${t.name}`,
+      cta: "Want to discuss this tension or capture a decision about it?"
+    };
+  }
+  return null;
+}
 async function buildOrientResponse(wsCtx, agentSessionId, errors) {
+  const wsFullCtx = await getWorkspaceContext();
+  const { ageDays, isNeglected } = computeWorkspaceAge(wsFullCtx.createdAt);
   let priorSessions = [];
   try {
     priorSessions = await mcpQuery("agent.recentSessions", { limit: 3 });
   } catch {
   }
-  let constraintEntries = [];
-  try {
-    const [archEntries, ruleEntries, decisionEntries] = await Promise.all([
-      mcpQuery("chain.listEntries", { collectionSlug: "architecture" }),
-      mcpQuery("chain.listEntries", { collectionSlug: "business-rules" }),
-      mcpQuery("chain.listEntries", { collectionSlug: "decisions" })
-    ]);
-    const committed = [
-      ...(archEntries ?? []).filter((e) => e.status === "active" || e.status === "healthy"),
-      ...(ruleEntries ?? []).filter((e) => e.status === "Active" || e.status === "active"),
-      ...(decisionEntries ?? []).filter((e) => e.status === "Decided" || e.status === "active")
-    ];
-    constraintEntries = committed.sort((a, b) => (b.updatedAt ?? 0) - (a.updatedAt ?? 0)).slice(0, 8);
-  } catch {
-  }
   let openTensions = [];
   try {
     const tensions = await mcpQuery("chain.listEntries", { collectionSlug: "tensions" });
@@ -3618,53 +3724,63 @@ async function buildOrientResponse(wsCtx, agentSessionId, errors) {
     errors.push(`Readiness: ${e.message}`);
   }
   const lines = [];
+  const isLowReadiness = readiness && readiness.score < 50;
+  const isHighReadiness = readiness && readiness.score >= 50;
   lines.push(`# ${wsCtx.workspaceName}`);
   lines.push(`_Workspace \`${wsCtx.workspaceSlug}\` \u2014 Product Brain is healthy._`);
   lines.push("");
-  if (readiness) {
-    const scoreBar = "\u2588".repeat(Math.round(readiness.score / 10)) + "\u2591".repeat(10 - Math.round(readiness.score / 10));
-    lines.push(`## Readiness: ${readiness.score}%`);
-    lines.push(`${scoreBar} ${readiness.passedChecks}/${readiness.totalChecks} requirements`);
+  if (isLowReadiness && isNeglected) {
+    lines.push(`Your workspace has been around for ${ageDays} days but is only ${readiness.score}% ready.`);
+    lines.push("Let's close the gaps \u2014 or if the current structure doesn't fit, we can reshape it.");
     lines.push("");
-    if (readiness.gaps?.length > 0) {
-      lines.push("### Gaps");
-      for (const gap of readiness.gaps) {
-        lines.push(`- [ ] **${gap.label}** (${gap.current}/${gap.required}) \u2014 _${gap.guidance}_`);
-      }
+  } else if (isLowReadiness) {
+    lines.push(`Readiness: ${readiness.score}%. Let's get your workspace active.`);
+    lines.push("");
+  }
+  if (isLowReadiness) {
+    const nextAction = pickNextAction(readiness.gaps ?? [], openTensions, priorSessions);
+    if (nextAction) {
+      lines.push("## Recommended next step");
+      lines.push(`**${nextAction.action}**`);
+      lines.push("");
+      lines.push(nextAction.cta);
       lines.push("");
+      lines.push('_Everything stays as a draft until you confirm. Say "commit" or "looks good" to promote to the Chain._');
+      lines.push("");
+      const remainingGaps = (readiness.gaps ?? []).length - 1;
+      if (remainingGaps > 0 || openTensions.length > 0) {
+        lines.push(`_${remainingGaps > 0 ? `${remainingGaps} more gap${remainingGaps === 1 ? "" : "s"}` : ""}${remainingGaps > 0 && openTensions.length > 0 ? " and " : ""}${openTensions.length > 0 ? `${openTensions.length} open tension${openTensions.length === 1 ? "" : "s"}` : ""} \u2014 ask "show full status" for details._`);
+        lines.push("");
+      }
     }
-  }
-  if (openTensions.length > 0) {
-    lines.push(`## Open Tensions (${openTensions.length})`);
-    for (const t of openTensions) {
-      const id = t.entryId ?? "(no ID)";
-      const prio = t.data?.priority ?? "";
-      lines.push(`- \`${id}\` ${t.name}${prio ? ` _(${prio})_` : ""}`);
+  } else if (isHighReadiness) {
+    if (readiness) {
+      lines.push(`Readiness: ${readiness.score}% (${readiness.passedChecks}/${readiness.totalChecks}).`);
     }
-    lines.push("");
-  }
-  if (priorSessions.length > 0) {
-    lines.push(`## Prior Agent Sessions (last ${priorSessions.length})`);
-    for (const s of priorSessions) {
-      const date = new Date(s.startedAt).toISOString().split("T")[0];
-      const created = Array.isArray(s.entriesCreated) ? s.entriesCreated.length : s.entriesCreated ?? 0;
-      const modified = Array.isArray(s.entriesModified) ? s.entriesModified.length : s.entriesModified ?? 0;
-      const stats = `${created} created, ${modified} modified, ${s.relationsCreated ?? 0} relations`;
-      lines.push(`- **${date}** (${s.status}, by ${s.initiatedBy ?? "unknown"}) \u2014 ${stats}`);
+    const briefingItems = [];
+    if (openTensions.length > 0) {
+      const topTension = openTensions[0];
+      briefingItems.push(`**${openTensions.length} open tension${openTensions.length === 1 ? "" : "s"}** \u2014 top: ${topTension.name}`);
     }
-    lines.push("");
-  }
-  if (constraintEntries.length > 0) {
-    lines.push(`## Active Constraints (${constraintEntries.length})`);
-    lines.push("_Architecture, business rules, and decisions that govern this workspace._");
-    lines.push("");
-    for (const c of constraintEntries) {
-      const id = c.entryId ?? "(no ID)";
-      const col = c.collectionSlug ?? "";
-      const desc = c.data?.description ?? c.data?.rationale ?? "";
-      const truncated = desc.length > 100 ? desc.slice(0, 100) + "..." : desc;
-      lines.push(`- \`${id}\` **${c.name}** [${col}] \u2014 ${truncated}`);
+    if (priorSessions.length > 0) {
+      const last = priorSessions[0];
+      const date = new Date(last.startedAt).toISOString().split("T")[0];
+      const created = Array.isArray(last.entriesCreated) ? last.entriesCreated.length : last.entriesCreated ?? 0;
+      const modified = Array.isArray(last.entriesModified) ? last.entriesModified.length : last.entriesModified ?? 0;
+      briefingItems.push(`**Last session** (${date}): ${created} created, ${modified} modified`);
+    }
+    if (readiness?.gaps?.length > 0) {
+      briefingItems.push(`**${readiness.gaps.length} gap${readiness.gaps.length === 1 ? "" : "s"}** remaining`);
+    }
+    if (briefingItems.length > 0) {
+      lines.push("");
+      lines.push("## Briefing");
+      for (const item of briefingItems) {
+        lines.push(`- ${item}`);
+      }
+      lines.push("");
     }
+    lines.push("What would you like to work on?");
     lines.push("");
   }
   if (errors.length > 0) {
@@ -3676,11 +3792,9 @@ async function buildOrientResponse(wsCtx, agentSessionId, errors) {
     try {
       await mcpCall("agent.markOriented", { sessionId: agentSessionId });
       setSessionOriented(true);
-      const readinessInfo = readiness ? `${readiness.score}% readiness.` : "";
-      const tensionInfo = openTensions.length > 0 ? `${openTensions.length} open tensions.` : "No open tensions.";
       lines.push("---");
       lines.push(
-        `Orientation complete. Session ${agentSessionId}. Write tools now available. ${readinessInfo} ${tensionInfo}`
+        `Orientation complete. Session ${agentSessionId}. Write tools available.`
       );
     } catch {
       lines.push("---");
@@ -4223,14 +4337,26 @@ var server = new McpServer2(
       "  4. Drill in: use `get-entry` for full details \u2014 data, labels, relations, history.",
       "  5. Context: use `gather-context` with an entryId or a task description.",
       "  6. Capture: use `capture` to create entries \u2014 auto-links and scores in one call.",
-      "  7. Commit: use `commit-entry` to promote drafts to SSOT.",
+      "  7. Commit: use `commit-entry` to promote drafts to SSOT \u2014 only when the user confirms.",
       "  8. Connect: use `suggest-links` then `relate-entries` to build the graph.",
       "  9. Close: call `agent-close` when done \u2014 records session activity.",
       "",
       "Write tools (capture, update-entry, relate-entries, commit-entry) require:",
       "  - An active agent session (call agent-start)",
       "  - Completed orientation (call orient)",
-      "  - A readwrite API key scope"
+      "  - A readwrite API key scope",
+      "",
+      "Commit-on-confirm: always capture as draft first and show the user what was captured.",
+      "Only call `commit-entry` when the user explicitly confirms (e.g. 'commit', 'looks good', 'yes').",
+      "This builds trust \u2014 the Chain (main) is SSOT; nothing goes there without user consent.",
+      "",
+      "Workspace setup: use `create-collection` and `update-collection` to shape the workspace",
+      "structure with the user. Ask what they need to track; presets are starting points, not fixed.",
+      "",
+      "Personalization: if you have context about the user from memory (prior work, recent",
+      "conversations, team context), use it to personalize recommendations. For example,",
+      "'Based on your recent pitch reviews, the gap most likely to matter is X.'",
+      "The orient/start output gives you the workspace state; your memory fills in the human context."
     ].join("\n")
   }
 );