@productbrain/mcp 0.0.1-beta.41 → 0.0.1-beta.43

package/dist/{chunk-5IH3KEAZ.js → chunk-AWDD44CN.js}

@@ -25,43 +25,51 @@ import {
   startAgentSession,
   trackWriteTool,
   translateStaleToolNames
-} from "./chunk-M264FY2V.js";
+} from "./chunk-PQP27A3R.js";
 import {
   trackQualityCheck,
   trackQualityVerdict
-} from "./chunk-P7ABQEFK.js";
+} from "./chunk-BIDMZOLE.js";
 
 // src/server.ts
 import { McpServer as McpServer2 } from "@modelcontextprotocol/sdk/server/mcp.js";
 
 // src/tools/knowledge.ts
 import { z } from "zod";
-var LEGACY_WORKFLOW_STATUSES = /* @__PURE__ */ new Set([
+var WORKFLOW_STATUS_VALUES = [
+  // Generic / governed collections
   "open",
   "pending",
-  "decided",
   "proposed",
   "accepted",
   "needs-amendment",
   "withdrawn",
   "review",
   "in-progress",
+  "decided",
   "conflict",
   "processing",
   "closed",
+  // Bets lifecycle
   "shaped",
   "bet",
   "building",
-  "shipped"
-]);
+  "shipped",
+  // Assumptions lifecycle
+  "untested",
+  "testing",
+  "validated",
+  "invalidated"
+];
+var LEGACY_WORKFLOW_STATUSES = new Set(WORKFLOW_STATUS_VALUES);
 var updateEntrySchema = z.object({
   entryId: z.string().describe("Entry ID to update, e.g. 'T-SUPPLIER', 'BR-001'"),
   name: z.string().optional().describe("New display name"),
   status: z.union([
     z.enum(["draft", "active", "deprecated", "archived"]),
-    z.enum(["open", "pending", "decided", "proposed", "accepted", "needs-amendment", "withdrawn", "review", "in-progress", "conflict", "processing", "closed", "shaped", "bet", "building", "shipped"])
+    z.enum(WORKFLOW_STATUS_VALUES)
   ]).optional().describe("Lifecycle status: draft | active | deprecated | archived. **Workflow values (open, pending, decided\u2026) are deprecated here \u2014 use `workflowStatus` instead. Passing a workflow value as `status` will be auto-routed with a warning until 2026-09-03, then hard-errored.**"),
-  workflowStatus: z.enum(["open", "pending", "proposed", "accepted", "needs-amendment", "withdrawn", "review", "in-progress", "decided", "conflict", "processing", "closed"]).optional().describe("Collection workflow state (e.g. 'open', 'pending', 'decided', 'conflict'). Validated against collection's allowed values."),
+  workflowStatus: z.enum(WORKFLOW_STATUS_VALUES).optional().describe("Collection workflow state. Each collection restricts which values are valid (e.g. bets: 'shaped' | 'bet' | 'building' | 'shipped'; assumptions: 'untested' | 'testing' | 'validated' | 'invalidated'; decisions: 'pending' | 'decided'; tensions: 'open' | 'processing' | 'decided' | 'closed'). The backend will reject values invalid for the target collection."),
   data: z.record(z.unknown()).optional().describe("Fields to update (merged with existing data)"),
   order: z.number().optional().describe("New sort order"),
   canonicalKey: z.string().optional().describe("Semantic type (e.g. 'decision', 'tension'). Only changeable on draft/uncommitted entries."),
@@ -195,7 +203,7 @@ ${formatted}` }]
     },
     async ({ entryId }) => {
       requireWriteAccess();
-      const { runContradictionCheck } = await import("./smart-capture-GH4CXVVX.js");
+      const { runContradictionCheck } = await import("./smart-capture-W2IALMJ5.js");
       const entry = await mcpQuery("chain.getEntry", { entryId });
       if (!entry) {
         return {
@@ -3669,11 +3677,15 @@ function generateBuildContract(ctx) {
 
 // src/tools/facilitate-validation.ts
 function computeCommitBlockers(opts) {
-  const { betEntryId, relations, betData, sessionDrafts } = opts;
+  const { betEntryId, betDocId, relations, hasStrategyLink, betData, sessionDrafts } = opts;
   const blockers = [];
   const str = (key) => (betData[key] ?? "").trim();
-  const hasStrategyLink = relations.some((r) => r.type === "commits_to");
-  if (!hasStrategyLink) {
+  const hasDirectionalCommitsTo = relations.some((r) => {
+    if (r.type !== "commits_to") return false;
+    return r.fromId === betDocId && r.toId !== betDocId;
+  });
+  const strategyLinked = hasStrategyLink ?? hasDirectionalCommitsTo;
+  if (!strategyLinked) {
     blockers.push({
       entryId: betEntryId,
       blocker: "Missing strategy link",
@@ -4121,6 +4133,7 @@ async function handleStart2(args) {
     const sc = orient?.strategicContext;
     const parts = [];
     if (sc?.vision) parts.push(`Vision: ${sc.vision}`);
+    if (sc?.purpose) parts.push(`Purpose: ${sc.purpose}`);
     if (sc?.activeBetCount) parts.push(`${sc.activeBetCount} active bet(s)`);
     if (sc?.activeTensionCount) parts.push(`${sc.activeTensionCount} open tension(s)`);
     if (orient?.activeBets?.length) {
@@ -4469,6 +4482,7 @@ async function handleRespond(args) {
   if (captureReady) {
     commitBlockers = computeCommitBlockers({
       betEntryId: betId,
+      betDocId: refreshedBet?._id ?? betEntry._id,
       relations: refreshedConstellation.relations,
       betData: refreshedData,
       sessionDrafts
@@ -4608,6 +4622,7 @@ async function handleScore(args) {
   }
   const commitBlockers = computeCommitBlockers({
     betEntryId: betId,
+    betDocId: betEntry._id,
     relations: constellation.relations,
     betData,
     sessionDrafts
@@ -4767,10 +4782,27 @@ async function handleCommitConstellation(args) {
   const relations = await mcpQuery("chain.listEntryRelations", {
     entryId: betId
   });
+  const hasStrategyLink = await (async () => {
+    const relatedDocIds = /* @__PURE__ */ new Set();
+    for (const rel of relations) {
+      if (rel.fromId === betEntry._id && rel.toId) relatedDocIds.add(rel.toId);
+      if (rel.toId === betEntry._id && rel.fromId) relatedDocIds.add(rel.fromId);
+    }
+    for (const docId of relatedDocIds) {
+      try {
+        const related = await mcpQuery("chain.getEntry", { id: docId });
+        if (related?.collectionSlug === "strategy") return true;
+      } catch {
+      }
+    }
+    return false;
+  })();
   const sessionDrafts = await loadSessionDrafts(betId, betEntry._id);
   const commitBlockerItems = computeCommitBlockers({
     betEntryId: betId,
+    betDocId: betEntry._id,
     relations,
+    hasStrategyLink,
     betData,
     sessionDrafts
   });
@@ -4792,6 +4824,7 @@ async function handleCommitConstellation(args) {
         blockers: commitBlockerItems,
         committedIds: [],
         alreadyCommittedIds: [],
+        proposedIds: [],
         failedIds: [],
         conflictIds: [],
         totalRelations: relations.length
@@ -4800,7 +4833,7 @@ async function handleCommitConstellation(args) {
   }
   let contradictionWarnings = [];
   try {
-    const { runContradictionCheck } = await import("./smart-capture-GH4CXVVX.js");
+    const { runContradictionCheck } = await import("./smart-capture-W2IALMJ5.js");
     const descField = betData.problem ?? betData.description ?? "";
     contradictionWarnings = await runContradictionCheck(
       betEntry.name ?? betId,
@@ -4835,24 +4868,40 @@ No constellation entries were committed.`
       isError: true
     };
   }
+  result = {
+    ...result,
+    committedIds: result.committedIds ?? [],
+    alreadyCommittedIds: result.alreadyCommittedIds ?? [],
+    proposedIds: result.proposedIds ?? [],
+    failedIds: result.failedIds ?? [],
+    conflictIds: result.conflictIds ?? []
+  };
   for (const entryId of result.committedIds) {
-    await recordSessionActivity({ entryModified: entryId });
+    try {
+      const committedEntry = await mcpQuery("chain.getEntry", { entryId });
+      const docId = committedEntry?._id;
+      if (typeof docId === "string" && docId.length > 0) {
+        await recordSessionActivity({ entryModified: docId });
+      }
+    } catch {
+    }
   }
   const lines = [];
+  const hasIssues = result.failedIds.length > 0 || result.conflictIds.length > 0;
   if (result.proposalCreated) {
     const linkedCount = result.committedIds.filter((id) => id !== betId).length;
     lines.push(
-      `# Proposal created`,
+      hasIssues ? `# Proposal created with issues` : `# Proposal created`,
       "",
       `Workspace uses consent-based governance. \`${betId}\` was submitted as a proposal \u2014 it will be committed when approved.`,
       `**${linkedCount} linked entries** were committed directly (proposals apply to the bet only).`
     );
   } else {
     lines.push(
-      `# Published`,
+      hasIssues ? `# Published with issues` : `# Published`,
       "",
       `**${result.committedIds.length} entries** committed to the Chain, **${result.totalRelations} connections** preserved.`,
-      `\`${betId}\` and its full constellation are now source of truth.`
+      hasIssues ? `\`${betId}\` was partially committed. Review conflicts/failed entries below before considering the constellation complete.` : `\`${betId}\` and its full constellation are now source of truth.`
     );
   }
   if (contradictionWarnings.length > 0) {
@@ -4864,6 +4913,9 @@ No constellation entries were committed.`
   if (result.alreadyCommittedIds.length > 0) {
     lines.push("", `**Already committed:** ${result.alreadyCommittedIds.join(", ")}`);
   }
+  if (result.proposedIds.length > 0) {
+    lines.push("", `**Proposed (not yet committed):** ${result.proposedIds.join(", ")}`);
+  }
   if (result.conflictIds.length > 0) {
     lines.push("", `**${result.conflictIds.length} conflicts:**`);
     for (const c of result.conflictIds) {
@@ -5335,10 +5387,10 @@ function formatRecoveryBlock(block) {
   const lines = [
     "## Previous Session Recovery",
     "",
-    `Session ${block.sessionId} \u2014 ${block.date}, ${block.duration}, status: ${block.status}`,
+    `Previous session \u2014 ${block.date}, ${block.duration}, status: ${block.status}`,
     `Created (${block.created.length + (block.createdOverflow ?? 0)}): ${fmt(block.created, block.createdOverflow)}`,
     `Modified (${block.modified.length + (block.modifiedOverflow ?? 0)}): ${fmt(block.modified, block.modifiedOverflow)}`,
-    `Drafts needing attention (${block.draftsNeedingAttention.length + (block.draftsOverflow ?? 0)}): ${fmt(block.draftsNeedingAttention, block.draftsOverflow)}`,
+    `Items pending review (${block.draftsNeedingAttention.length + (block.draftsOverflow ?? 0)}): ${fmt(block.draftsNeedingAttention, block.draftsOverflow)}`,
     `Relations created: ${block.relationsCreated}`,
     ""
   ];
@@ -5361,7 +5413,7 @@ function buildPlannedWorkSection(work, priorSessions, recoveryBlock) {
   }
   if (work.uncommittedDrafts.length > 0) {
     const count = work.uncommittedDrafts.length;
-    const label = count === 1 ? "1 uncommitted draft" : `${count} uncommitted drafts`;
+    const label = count === 1 ? "1 item pending" : `${count} items pending`;
     const topNames = work.uncommittedDrafts.slice(0, 3).map((d) => d.name).join(", ");
     lines.push(`- **${label}** \u2014 ${topNames}${count > 3 ? ", ..." : ""}`);
   }
@@ -5581,7 +5633,7 @@ function extractionToBatchEntries(extracted) {
 }
 function getInterviewInstructions(workspaceName) {
   return {
-    systemPrompt: `You are activating the **${workspaceName}** Product Brain. Ask 1\u20132 focused questions, then extract structured knowledge and feed it to batch-capture. Everything lands as a draft \u2014 the user confirms before anything is committed.`,
+    systemPrompt: `You are activating the **${workspaceName}** Product Brain. Ask 1\u20132 focused questions, then extract structured knowledge and feed it to batch-capture. Everything stays pending \u2014 the user confirms before anything is committed.`,
     question1: `**Q1 \u2014 What are you building and for whom?** Describe your product in 1\u20132 sentences and who it's for. (This becomes your Product Vision and primary Audience.)`,
     question2: `**Q2 (optional) \u2014 What's your tech stack or key domain terms?** Name a few core technologies or terms your team uses. (These become Architecture + Glossary entries.)`,
     extractionGuidance: `After the user answers, extract:
@@ -5611,7 +5663,7 @@ function buildInterviewResponse(workspaceName) {
     "",
     instructions.systemPrompt,
     "",
-    "I'll ask you 1\u20132 questions. Your answers become the first entries in your knowledge graph \u2014 all as drafts until you confirm.",
+    "I'll ask you 1\u20132 questions. Your answers become the first entries in your knowledge graph \u2014 all pending until you confirm.",
     "",
     `**${instructions.question1}**`,
     "",
@@ -5619,7 +5671,7 @@ function buildInterviewResponse(workspaceName) {
     "",
     `> ${instructions.scanOffer}`,
     "",
-    '_Everything stays as a draft until you say "commit" or "looks good"._'
+    "_Everything stays pending until you confirm._"
   ].join("\n");
 }
 
@@ -5666,27 +5718,42 @@ function registerStartTools(server) {
         errors.push("Readiness check unavailable \u2014 showing workspace summary.");
       }
       if (stage === "blank" && preset) {
-        return { content: [{ type: "text", text: await seedPreset(wsCtx, preset, agentSessionId) }] };
+        const result = await seedPreset(wsCtx, preset, agentSessionId);
+        return {
+          content: [{ type: "text", text: result.text }],
+          structuredContent: result.structuredContent
+        };
       }
       if (stage === "blank") {
-        return { content: [{ type: "text", text: buildProjectScanResponse(wsCtx) }] };
+        const scanResult = buildProjectScanResponse(wsCtx);
+        return {
+          content: [{ type: "text", text: scanResult.text }],
+          structuredContent: scanResult.structuredContent
+        };
       }
       if (stage === "seeded") {
-        const text = await buildSeededResponse(wsCtx, readiness, agentSessionId);
+        const result = await buildSeededResponse(wsCtx, readiness, agentSessionId);
         void mcpMutation("chain.setOnboardingCompleted", {}).catch(() => {
         });
-        return { content: [{ type: "text", text }] };
+        return {
+          content: [{ type: "text", text: result.text }],
+          structuredContent: result.structuredContent
+        };
       }
       if (stage === "grounded" || stage === "connected") {
         void mcpMutation("chain.setOnboardingCompleted", {}).catch(() => {
         });
       }
-      return { content: [{ type: "text", text: await buildOrientResponse(wsCtx, agentSessionId, errors) }] };
+      const orientResult = await buildOrientResponse(wsCtx, agentSessionId, errors);
+      return {
+        content: [{ type: "text", text: orientResult.text }],
+        structuredContent: orientResult.structuredContent
+      };
     }
   );
 }
 function buildProjectScanResponse(wsCtx) {
-  return [
+  const text = [
     `# Welcome to ${wsCtx.workspaceName}`,
     "",
     "Your workspace is fresh. Let me get oriented in your codebase.",
@@ -5716,56 +5783,72 @@ function buildProjectScanResponse(wsCtx) {
     "",
     "_Prefer 5 specific entries over 8 generic ones. Skip anything that would apply to any codebase._"
   ].join("\n");
+  return {
+    text,
+    structuredContent: {
+      stage: "blank",
+      oriented: false,
+      orientationStatus: "no_session"
+    }
+  };
 }
 async function buildSeededResponse(wsCtx, readiness, agentSessionId) {
+  const stage = readiness?.stage ?? "seeded";
+  const score = readiness?.score;
+  const gaps = readiness?.gaps ?? [];
   const lines = [
     `# ${wsCtx.workspaceName}`,
     "_Picking up where you left off._",
     ""
   ];
-  const stage = readiness?.stage ?? "seeded";
-  const score = readiness?.score;
-  if (score !== void 0) {
-    lines.push(`**Brain stage: ${stage}.** Readiness score: ${score}/100.`);
-    lines.push("");
-  }
-  const gaps = readiness?.gaps ?? [];
   if (gaps.length > 0) {
-    lines.push("## Top gaps to fill");
-    for (const gap of gaps.slice(0, 3)) {
-      const cta = gap.capabilityGuidance ?? gap.guidance ?? `Capture ${gap.label.toLowerCase()} to unlock this.`;
-      lines.push(`**${gap.label}** \u2014 ${cta}`);
-    }
+    lines.push("Here are the most impactful gaps to fill next:");
     lines.push("");
-    if (gaps.length > 3) {
-      lines.push(`_${gaps.length - 3} more gap${gaps.length - 3 === 1 ? "" : "s"} \u2014 use \`health action=status\` for the full list._`);
-      lines.push("");
+    const topGaps = gaps.slice(0, 3);
+    for (let i = 0; i < topGaps.length; i++) {
+      const gap = topGaps[i];
+      const cta = gap.capabilityGuidance ?? gap.guidance ?? `Describe your ${gap.label.toLowerCase()}.`;
+      lines.push(`${i + 1}. **${gap.label}** \u2014 ${cta}`);
     }
-  } else {
-    lines.push("No gaps detected \u2014 workspace is filling up nicely.");
     lines.push("");
+    lines.push("Pick any to start \u2014 or begin with **#1** and I'll guide you through it.");
+  } else {
+    lines.push("No gaps detected \u2014 your workspace is filling up nicely. What would you like to work on?");
   }
-  lines.push("What would you like to work on?");
-  lines.push("");
+  let oriented = false;
+  let orientationStatus = "no_session";
   if (agentSessionId) {
     try {
       await mcpCall("agent.markOriented", { sessionId: agentSessionId });
       setSessionOriented(true);
-      lines.push("---");
-      lines.push("Orientation complete. Write tools available.");
+      oriented = true;
+      orientationStatus = "complete";
     } catch {
-      lines.push("---");
-      lines.push("_Warning: Could not mark session as oriented._");
+      orientationStatus = "failed";
     }
   }
-  return lines.join("\n");
+  return {
+    text: lines.join("\n"),
+    structuredContent: {
+      stage,
+      readinessScore: score ?? null,
+      totalGaps: gaps.length,
+      topGapLabels: gaps.slice(0, 3).map((g) => g.label),
+      oriented,
+      orientationStatus,
+      ...agentSessionId ? { sessionId: agentSessionId } : {}
+    }
+  };
 }
 async function seedPreset(wsCtx, presetId, agentSessionId) {
   const preset = getPreset(presetId);
   if (!preset) {
-    return `Preset "${presetId}" not found.
+    return {
+      text: `Preset "${presetId}" not found.
 
-Available presets: ${listPresets().map((p) => `\`${p.id}\``).join(", ")}`;
+Available presets: ${listPresets().map((p) => `\`${p.id}\``).join(", ")}`,
+      structuredContent: { stage: "blank", error: "preset_not_found", preset: presetId }
+    };
   }
   const seeded = [];
   const skipped = [];
@@ -5785,11 +5868,16 @@ Available presets: ${listPresets().map((p) => `\`${p.id}\``).join(", ")}`;
       skipped.push(`${col.name} (already exists)`);
     }
   }
+  let oriented = false;
+  let orientationStatus = "no_session";
   if (agentSessionId) {
     try {
       await mcpCall("agent.markOriented", { sessionId: agentSessionId });
       setSessionOriented(true);
+      oriented = true;
+      orientationStatus = "complete";
     } catch {
+      orientationStatus = "failed";
     }
   }
   const lines = [
@@ -5811,12 +5899,20 @@ Available presets: ${listPresets().map((p) => `\`${p.id}\``).join(", ")}`;
     "",
     buildInterviewResponse(wsCtx.workspaceName),
     "",
-    "_You can also customize your structure anytime: `collections action=create`, `collections action=update`, or `collections action=list`._",
-    "",
-    "---",
-    "Orientation complete. Write tools are available."
+    "_You can also customize your collections anytime \u2014 just ask._"
   );
-  return lines.join("\n");
+  return {
+    text: lines.join("\n"),
+    structuredContent: {
+      stage: "blank",
+      preset: presetId,
+      seededCollections: seeded,
+      skippedCollections: skipped,
+      oriented,
+      orientationStatus,
+      ...agentSessionId ? { sessionId: agentSessionId } : {}
+    }
+  };
 }
 function computeWorkspaceAge(createdAt) {
   if (!createdAt) return { ageDays: 0, isNeglected: false };
@@ -5867,7 +5963,7 @@ async function buildOrientResponse(wsCtx, agentSessionId, errors) {
   const isHighReadiness = readiness !== null && readiness.score >= 50;
   const stage = readiness?.stage ?? null;
   lines.push(`# ${wsCtx.workspaceName}`);
-  lines.push(`_Workspace \`${wsCtx.workspaceSlug}\` \u2014 Product Brain is healthy._`);
+  lines.push("_Product Brain is ready._");
   lines.push("");
   if (isLowReadiness && isNeglected) {
     const stageNote = stage ? ` and is still at the **${stage}** stage` : "";
@@ -5875,7 +5971,7 @@ async function buildOrientResponse(wsCtx, agentSessionId, errors) {
     lines.push("Let's close the gaps \u2014 or if the current structure doesn't fit, we can reshape it.");
     lines.push("");
   } else if (isLowReadiness) {
-    if (stage) lines.push(`**Brain stage: ${stage}.** Let's get your workspace active.`);
+    lines.push("Let's get your workspace active.");
     lines.push("");
   }
   if (isLowReadiness) {
@@ -5886,21 +5982,17 @@ async function buildOrientResponse(wsCtx, agentSessionId, errors) {
       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("_Everything I capture stays pending until you confirm._");
       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(`_${remainingGaps > 0 ? `${remainingGaps} more area${remainingGaps === 1 ? "" : "s"} to cover` : ""}${remainingGaps > 0 && openTensions.length > 0 ? " and " : ""}${openTensions.length > 0 ? `${openTensions.length} open tension${openTensions.length === 1 ? "" : "s"}` : ""} \u2014 ask for full status to see everything._`);
         lines.push("");
       }
     }
-    lines.push("_Need a collection that doesn't exist yet (e.g. audiences, personas, metrics)?_");
-    lines.push("_Use `collections action=create` to add it, or ask me to propose collections for your domain._");
+    lines.push("_Need a collection that doesn't exist yet (e.g. audiences, personas, metrics)? Just ask \u2014 I'll set it up._");
     lines.push("");
   } else if (isHighReadiness) {
-    if (readiness) {
-      lines.push(`**Brain stage: ${stage}.**`);
-    }
     let wsPrinciples = [];
     let wsStandards = [];
     let wsBusinessRules = [];
@@ -6002,7 +6094,7 @@ async function buildOrientResponse(wsCtx, agentSessionId, errors) {
         lines.push("");
         lines.push("## Your workspace is activated");
         lines.push(
-          `**${committed.length} committed entries** across **${committedCollections.size} collections** \u2014 your knowledge graph is alive.`
+          `**${committed.length} entries** across **${committedCollections.size} collections** \u2014 your knowledge graph is alive.`
         );
         lines.push("");
         lines.push(
@@ -6013,7 +6105,7 @@ async function buildOrientResponse(wsCtx, agentSessionId, errors) {
           lines.push(`**View in Studio:** \`/w/${wsCtx.workspaceSlug}/studio\``);
           lines.push("");
         }
-        lines.push(`_Tip: Connect entries with \`graph action=suggest\` to unlock deeper context._`);
+        lines.push("_Tip: Ask me to suggest connections between entries to unlock deeper context._");
         lines.push("");
       }
     } catch {
@@ -6026,23 +6118,30 @@ async function buildOrientResponse(wsCtx, agentSessionId, errors) {
     for (const err of errors) lines.push(`- ${err}`);
     lines.push("");
   }
+  let oriented = false;
+  let orientationStatus = "no_session";
   if (agentSessionId) {
     try {
       await mcpCall("agent.markOriented", { sessionId: agentSessionId });
       setSessionOriented(true);
-      lines.push("---");
-      lines.push(
-        `Orientation complete. Session ${agentSessionId}. Write tools available.`
-      );
+      oriented = true;
+      orientationStatus = "complete";
     } catch {
-      lines.push("---");
-      lines.push("_Warning: Could not mark session as oriented. Write tools may be restricted._");
+      orientationStatus = "failed";
     }
-  } else {
-    lines.push("---");
-    lines.push("_No active agent session. Call `session action=start` to begin a tracked session._");
   }
-  return lines.join("\n");
+  return {
+    text: lines.join("\n"),
+    structuredContent: {
+      stage,
+      readinessScore: readiness?.score ?? null,
+      totalGaps: readiness?.gaps?.length ?? 0,
+      openTensions: openTensions.length,
+      oriented,
+      orientationStatus,
+      ...agentSessionId ? { sessionId: agentSessionId } : {}
+    }
+  };
 }
 
 // src/tools/usage.ts
@@ -8061,6 +8160,34 @@ function registerHealthTools(server) {
       } catch (e) {
         errors.push(`Readiness: ${e instanceof Error ? e.message : String(e)}`);
       }
+      if (readiness?.stage === "blank") {
+        const scanLines = [
+          `# Welcome to ${wsCtx?.workspaceName ?? "your workspace"}`,
+          "",
+          "Your workspace is fresh \u2014 let's set it up.",
+          "",
+          "**Recommended:** call the `start` tool instead of `orient` for the best first-run experience.",
+          "It will guide you through scanning your codebase and capturing initial knowledge.",
+          "",
+          "Or tell me about your product and I'll start capturing knowledge directly."
+        ];
+        if (agentSessionId) {
+          try {
+            await mcpCall("agent.markOriented", { sessionId: agentSessionId });
+            setSessionOriented(true);
+          } catch {
+          }
+        }
+        return {
+          content: [{ type: "text", text: scanLines.join("\n") }],
+          structuredContent: {
+            stage: "blank",
+            readinessScore: readiness?.score ?? 0,
+            oriented: true,
+            redirectHint: "Use the `start` tool for the full guided setup experience."
+          }
+        };
+      }
       const lines = [];
       const isLowReadiness = readiness && readiness.score < 50;
       if (wsCtx) {
@@ -8077,6 +8204,7 @@ function registerHealthTools(server) {
         if (orientEntries?.strategicContext) {
           const sc = orientEntries.strategicContext;
           if (sc.vision) lines.push(`Vision: ${sc.vision}`);
+          if (sc.purpose) lines.push(`Purpose: ${sc.purpose}`);
           if (sc.productAreaCount != null && sc.productAreaCount > 0) {
             lines.push(`Product areas (${sc.productAreaCount}): ${(sc.productAreas ?? []).join(", ")}`);
           }
@@ -8172,6 +8300,7 @@ function registerHealthTools(server) {
           const sc = orientEntries.strategicContext;
           lines.push("## Strategic Context");
           if (sc.vision) lines.push(`**Vision:** ${sc.vision}`);
+          if (sc.purpose) lines.push(`**Purpose:** ${sc.purpose}`);
           if (sc.productAreaCount != null && sc.productAreaCount > 0) {
             lines.push(`**Product areas (${sc.productAreaCount}):** ${(sc.productAreas ?? []).join(", ")}`);
           }
@@ -9122,6 +9251,8 @@ Description field: ${wf.kbOutputTemplate.descriptionField}
         const orient = await mcpQuery("chain.getOrientEntries", {});
         const sc = orient?.strategicContext;
         if (sc?.vision) strategicContext += `**Vision:** ${sc.vision}
+`;
+        if (sc?.purpose) strategicContext += `**Purpose:** ${sc.purpose}
 `;
         if (sc?.currentBet) strategicContext += `**Current bet:** ${sc.currentBet}
 `;
@@ -9166,18 +9297,20 @@ You are a **coached shaping facilitator** powered by the \`facilitate\` tool. Yo
 
 ## Your Role (DEC-56 Boundary)
 
-The **server judges** \u2014 it scores input against 5 rubric dimensions, detects overlap with existing Chain entries, and checks alignment with governance. The server returns structured coaching responses.
+The **server judges** \u2014 it scores input against 7 rubric dimensions, detects overlap with existing Chain entries, and checks alignment with governance. The server returns structured coaching responses.
 **You coach** \u2014 you interpret the structured response, synthesize it naturally, decide tone, follow up on weak areas, and push back when the shaping isn't sharp enough.
 The \`coaching.suggestedQuestion\` is a suggestion, not a script \u2014 rephrase or skip based on conversation flow.
 
-## Rubric Dimensions (5 scoring criteria)
+## Rubric Dimensions (7 scoring criteria)
 
 Each scored 0-10 by the server:
 1. **Problem Clarity** \u2014 workaround described, who affected, frequency/severity, differentiated from existing tensions
 2. **Appetite Definition** \u2014 time constraint explicit, scope bounded, trade-offs acknowledged
 3. **Element Decomposition** \u2014 breadboard-level pieces identified, independently describable, no implementation leaks
-4. **Risk Coverage** \u2014 rabbit holes named, mitigations or acceptances, codebase-level risks
-5. **Boundary Specification** \u2014 explicit no-gos, each prevents scope creep in a specific direction
+4. **Architecture Fit** \u2014 layer boundaries and dependency implications are explicit, aligned with existing system constraints
+5. **Risk Coverage** \u2014 rabbit holes named, mitigations or acceptances, codebase-level risks
+6. **Boundary Specification** \u2014 explicit no-gos, each prevents scope creep in a specific direction
+7. **Done-When Quality** \u2014 testable completion outcomes, measurable verification criteria, and clear acceptance conditions
 
 ## How to Use the Facilitate Tool
 
@@ -9614,8 +9747,8 @@ var INSTRUCTIONS = [
   "",
   "## Workflow",
   "",
-  "  1. Start: call `session action=start` to begin a tracked session.",
-  "  2. Orient: call `orient` to load workspace context and unlock write tools.",
+  "  1. Start: call `start` to begin \u2014 it starts a session automatically, detects your workspace stage, and returns the right guidance. Fresh workspaces get a guided setup; active workspaces get a standup briefing.",
+  "  2. Re-orient: call `orient` mid-session for task-scoped context or a compact status refresh.",
   "  3. Discover: use `entries action=search` to find entries, or `entries action=list` to browse.",
   '  4. Drill in: use `entries action=get entryId="..."` for full details \u2014 data, labels, relations, history.',
   "  5. Context: use `context action=gather` with an entryId or a task description.",
@@ -9626,8 +9759,7 @@ var INSTRUCTIONS = [
   "  10. Close: call `session action=close` when done \u2014 records session activity. Auto-nudges if wrapup was skipped.",
   "",
   "Write tools (capture, update-entry, relations, commit-entry) require:",
-  "  - An active agent session (call session action=start)",
-  "  - Completed orientation (call orient)",
+  "  - Call `start` to begin (starts session + loads context). Call `orient` mid-session for a refresh.",
   "  - A readwrite API key scope",
   "",
   "Commit-on-confirm: always capture as draft first and show the user what was captured.",
@@ -9687,4 +9819,4 @@ export {
   SERVER_VERSION,
   createProductBrainServer
 };
-//# sourceMappingURL=chunk-5IH3KEAZ.js.map
+//# sourceMappingURL=chunk-AWDD44CN.js.map