@unified-product-graph/mcp-server 0.7.4 → 0.7.6

package/dist/index.js

@@ -63,6 +63,7 @@ async function hashFile(filePath) {
 }
 
 // ../upg-spec/dist/index.js
+import { createHash as createHash2 } from "crypto";
 var UPG_DOMAINS = [
   {
     id: "strategy",
@@ -12115,26 +12116,6 @@ var UPG_FRAMEWORKS = [
         "label": "Items to score",
         "entityTypeId": "feature",
         "description": "Features, opportunities, or solutions being evaluated"
-      },
-      {
-        "label": "Reach",
-        "entityTypeId": "feature",
-        "description": "How many users does this affect per quarter?"
-      },
-      {
-        "label": "Impact",
-        "entityTypeId": "feature",
-        "description": "How much does this move the target outcome?"
-      },
-      {
-        "label": "Confidence",
-        "entityTypeId": "feature",
-        "description": "How sure are we about these estimates?"
-      },
-      {
-        "label": "Effort",
-        "entityTypeId": "feature",
-        "description": "How many person-months to build?"
       }
     ],
     "data": {
@@ -12148,31 +12129,35 @@ var UPG_FRAMEWORKS = [
         "feature": [
           {
             "property": "reach",
-            "type": "number",
+            "type": "assessment",
+            "scale_id": "reach_5",
             "required": true,
             "label": "Reach",
             "description": "How many users will this impact per quarter?"
           },
           {
             "property": "impact",
-            "type": "number",
+            "type": "assessment",
+            "scale_id": "impact_5",
             "required": true,
             "label": "Impact",
-            "description": "How much will this impact each user? (1=minimal, 2=low, 3=medium, 4=high, 5=massive)"
+            "description": "How much will this impact each user, on the impact scale?"
           },
           {
             "property": "confidence",
-            "type": "number",
+            "type": "assessment",
+            "scale_id": "confidence_5",
             "required": true,
             "label": "Confidence",
-            "description": "How confident are you in the estimates? (0.5=low, 0.8=medium, 1.0=high)"
+            "description": "How confident are you in the reach, impact, and effort estimates?"
           },
           {
             "property": "effort",
-            "type": "number",
+            "type": "assessment",
+            "scale_id": "effort_5",
             "required": true,
             "label": "Effort",
-            "description": "Person-months of effort required"
+            "description": "How much work is required to build and ship this, on the effort scale?"
           }
         ]
       },
@@ -12366,7 +12351,7 @@ var UPG_FRAMEWORKS = [
       {
         "label": "Performance",
         "entityTypeId": "feature",
-        "description": "More is better, with linear satisfaction increase"
+        "description": "More is better: linear satisfaction increase"
       },
       {
         "label": "Delighters",
@@ -12615,24 +12600,9 @@ var UPG_FRAMEWORKS = [
     ],
     "slots": [
       {
-        "label": "Must Have",
-        "entityTypeId": "feature",
-        "description": "Non-negotiable requirements for this release"
-      },
-      {
-        "label": "Should Have",
+        "label": "Requirements to categorise",
         "entityTypeId": "feature",
-        "description": "Important but not critical; a workaround exists"
-      },
-      {
-        "label": "Could Have",
-        "entityTypeId": "feature",
-        "description": "Nice to have; include if time permits"
-      },
-      {
-        "label": "Won't Have",
-        "entityTypeId": "feature",
-        "description": "Explicitly out of scope for now"
+        "description": "Features or requirements sorted into the four MoSCoW buckets"
       }
     ],
     "data": {
@@ -12642,7 +12612,23 @@ var UPG_FRAMEWORKS = [
           "role": "scored_item"
         }
       ],
-      "required_properties": {},
+      "required_properties": {
+        "feature": [
+          {
+            "property": "moscow",
+            "type": "enum",
+            "required": true,
+            "label": "MoSCoW priority",
+            "description": "Which scope bucket this requirement falls into for the current release",
+            "enum_values": [
+              "must",
+              "should",
+              "could",
+              "wont"
+            ]
+          }
+        ]
+      },
       "computed_properties": [
         {
           "property": "must_have_ratio",
@@ -12662,28 +12648,19 @@ var UPG_FRAMEWORKS = [
         "columns": [
           {
             "property": "title",
-            "label": "Must Have",
+            "label": "Requirement",
             "sortable": true
           },
           {
-            "property": "title",
-            "label": "Should Have",
-            "sortable": true
-          },
-          {
-            "property": "title",
-            "label": "Could Have",
-            "sortable": true
-          },
-          {
-            "property": "title",
-            "label": "Won't Have",
-            "sortable": true
+            "property": "moscow",
+            "label": "Priority",
+            "sortable": true,
+            "format": "badge"
           }
         ]
       },
       "sort_by": {
-        "property": "title",
+        "property": "moscow",
         "direction": "asc"
       },
       "colour_by": "type",
@@ -13234,24 +13211,9 @@ var UPG_FRAMEWORKS = [
     ],
     "slots": [
       {
-        "label": "Deployment Frequency",
-        "entityTypeId": "metric",
-        "description": "How often you deploy to production"
-      },
-      {
-        "label": "Lead Time for Changes",
-        "entityTypeId": "metric",
-        "description": "Time from commit to production"
-      },
-      {
-        "label": "Change Failure Rate",
+        "label": "Delivery metric",
         "entityTypeId": "metric",
-        "description": "Percentage of deployments causing failures"
-      },
-      {
-        "label": "Time to Restore",
-        "entityTypeId": "metric",
-        "description": "How long to recover from a failure"
+        "description": "One of the four DORA software-delivery performance metrics"
       }
     ],
     "data": {
@@ -13261,7 +13223,36 @@ var UPG_FRAMEWORKS = [
           "role": "item"
         }
       ],
-      "required_properties": {},
+      "required_properties": {
+        "metric": [
+          {
+            "property": "dora_metric",
+            "type": "enum",
+            "required": true,
+            "label": "DORA metric",
+            "description": "Which of the four DORA metrics this measures",
+            "enum_values": [
+              "deployment_frequency",
+              "lead_time_for_changes",
+              "change_failure_rate",
+              "time_to_restore"
+            ]
+          },
+          {
+            "property": "performance_tier",
+            "type": "enum",
+            "required": false,
+            "label": "Performance tier",
+            "description": "Where this metric sits on the DORA elite-to-low benchmark",
+            "enum_values": [
+              "elite",
+              "high",
+              "medium",
+              "low"
+            ]
+          }
+        ]
+      },
       "computed_properties": [
         {
           "property": "stability_index",
@@ -13417,29 +13408,9 @@ var UPG_FRAMEWORKS = [
     ],
     "slots": [
       {
-        "label": "Acquisition",
-        "entityTypeId": "metric",
-        "description": "How do users find you?"
-      },
-      {
-        "label": "Activation",
-        "entityTypeId": "metric",
-        "description": "Do users have a great first experience?"
-      },
-      {
-        "label": "Retention",
-        "entityTypeId": "metric",
-        "description": "Do users come back?"
-      },
-      {
-        "label": "Revenue",
+        "label": "Lifecycle metric",
         "entityTypeId": "metric",
-        "description": "Can you monetise the behaviour?"
-      },
-      {
-        "label": "Referral",
-        "entityTypeId": "metric",
-        "description": "Do users tell others?"
+        "description": "A metric tracking one stage of the customer lifecycle funnel"
       }
     ],
     "data": {
@@ -13449,7 +13420,24 @@ var UPG_FRAMEWORKS = [
           "role": "item"
         }
       ],
-      "required_properties": {},
+      "required_properties": {
+        "metric": [
+          {
+            "property": "lifecycle_stage",
+            "type": "enum",
+            "required": true,
+            "label": "Lifecycle stage",
+            "description": "Which AARRR funnel stage this metric measures",
+            "enum_values": [
+              "acquisition",
+              "activation",
+              "retention",
+              "revenue",
+              "referral"
+            ]
+          }
+        ]
+      },
       "computed_properties": [
         {
           "property": "conversion_rate",
@@ -13461,7 +13449,39 @@ var UPG_FRAMEWORKS = [
       ]
     },
     "structure": {
-      "pattern": "funnel"
+      "pattern": "funnel",
+      "stages": [
+        {
+          "id": "acquisition",
+          "label": "Acquisition",
+          "order": 0,
+          "entity_type": "metric"
+        },
+        {
+          "id": "activation",
+          "label": "Activation",
+          "order": 1,
+          "entity_type": "metric"
+        },
+        {
+          "id": "retention",
+          "label": "Retention",
+          "order": 2,
+          "entity_type": "metric"
+        },
+        {
+          "id": "revenue",
+          "label": "Revenue",
+          "order": 3,
+          "entity_type": "metric"
+        },
+        {
+          "id": "referral",
+          "label": "Referral",
+          "order": 4,
+          "entity_type": "metric"
+        }
+      ]
     },
     "presentation": {
       "layout": {
@@ -13508,24 +13528,9 @@ var UPG_FRAMEWORKS = [
     ],
     "slots": [
       {
-        "label": "North Star",
-        "entityTypeId": "metric",
-        "description": "The single metric reflecting core value delivered"
-      },
-      {
-        "label": "Input Metric 1",
-        "entityTypeId": "metric",
-        "description": "A driver metric you can directly influence"
-      },
-      {
-        "label": "Input Metric 2",
-        "entityTypeId": "metric",
-        "description": "A driver metric you can directly influence"
-      },
-      {
-        "label": "Input Metric 3",
+        "label": "Metric",
         "entityTypeId": "metric",
-        "description": "A driver metric you can directly influence"
+        "description": "The North Star metric or one of its 3-5 input (driver) metrics"
       }
     ],
     "data": {
@@ -13535,7 +13540,28 @@ var UPG_FRAMEWORKS = [
           "role": "item"
         }
       ],
-      "required_properties": {},
+      "required_properties": {
+        "metric": [
+          {
+            "property": "metric_role",
+            "type": "enum",
+            "required": true,
+            "label": "Metric role",
+            "description": "Whether this is the single North Star or a driver that feeds it",
+            "enum_values": [
+              "north_star",
+              "input"
+            ]
+          },
+          {
+            "property": "leverage",
+            "type": "number",
+            "required": false,
+            "label": "Leverage",
+            "description": "How strongly this input metric moves the North Star (input metrics only)"
+          }
+        ]
+      },
       "computed_properties": [
         {
           "property": "nsm_impact",
@@ -13835,7 +13861,7 @@ var UPG_FRAMEWORKS = [
       ]
     },
     "education": {
-      "purpose": "Design the product itself as the primary growth driver (free tier, self-serve onboarding, in-product virality), reducing dependence on sales-led acquisition.",
+      "purpose": "Design the product itself as the primary growth driver (free tier, self-serve onboarding, in-product virality) to reduce dependence on sales-led acquisition.",
       "core_question": "Can our product acquire, activate, and expand users without human intervention, and where in the loop do we still need sales?",
       "when_to_use": [
         "You are launching a new product, feature, or entering a new market",
@@ -14245,7 +14271,7 @@ var UPG_FRAMEWORKS = [
       {
         "label": "Team",
         "entityTypeId": "team",
-        "description": "Team conducting the health check: all members vote anonymously on each dimension"
+        "description": "Team conducting the health check; all members vote anonymously on each dimension"
       },
       {
         "label": "Retrospective",
@@ -14334,7 +14360,7 @@ var UPG_FRAMEWORKS = [
     },
     "education": {
       "purpose": "Regularly assess team health across dimensions (psychological safety, autonomy, mission clarity, fun, speed, learning) to catch problems early and celebrate strengths.",
-      "core_question": "How is the team really doing? Where do they feel strong, where do they feel stuck, and what has changed since last check?",
+      "core_question": "How is the team really doing: where do they feel strong, where do they feel stuck, and what has changed since last check?",
       "when_to_use": [
         "You need to improve team collaboration, clarity, or effectiveness",
         "Roles and responsibilities are unclear or causing friction",
@@ -14350,7 +14376,7 @@ var UPG_FRAMEWORKS = [
     "id": "raid-log",
     "name": "RAID Log",
     "version": "1.0.0",
-    "description": "A project management register tracking Risks, Assumptions, Issues, and Dependencies: the four categories most likely to derail a project if left unmanaged.",
+    "description": "A project management register tracking Risks, Assumptions, Issues, and Dependencies, the four categories most likely to derail a project if left unmanaged.",
     "category": "program_mgmt",
     "origin": {
       "type": "practitioner",
@@ -22520,6 +22546,222 @@ var UPG_STRUCTURE_PATTERNS = [
   "quadrant",
   "flow"
 ];
+var UPG_CANONICAL_FORMAT_VERSION = "1.0.0";
+var INTEGRITY_HASH_PRIMITIVE = "sha256";
+var INTEGRITY_DIGEST_HEX = 32;
+var INTEGRITY_ALGORITHM = "sha256-128";
+function canonicalizeOpen(value) {
+  if (Array.isArray(value)) return value.map(canonicalizeOpen);
+  if (value !== null && typeof value === "object") {
+    const out = {};
+    for (const key of Object.keys(value).sort(byCodeUnit)) {
+      out[key] = canonicalizeOpen(value[key]);
+    }
+    return out;
+  }
+  return value;
+}
+function byCodeUnit(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+function isEmpty(value) {
+  if (value === null || value === void 0) return true;
+  if (typeof value === "string") return value.length === 0;
+  if (Array.isArray(value)) return value.length === 0;
+  if (typeof value === "object") return Object.keys(value).length === 0;
+  return false;
+}
+function orderedObject(source, keyOrder, opts = {}) {
+  const force = new Set(opts.forceKeys ?? []);
+  const open = new Set(opts.openKeys ?? []);
+  const out = {};
+  const emit = (key) => {
+    if (!(key in source)) return;
+    const raw = source[key];
+    if (!force.has(key) && isEmpty(raw)) return;
+    out[key] = open.has(key) ? canonicalizeOpen(raw) : raw;
+  };
+  for (const key of keyOrder) emit(key);
+  for (const key of Object.keys(source).sort(byCodeUnit)) {
+    if (!keyOrder.includes(key)) emit(key);
+  }
+  return out;
+}
+function repairNodeDrift(node) {
+  const out = { ...node };
+  if (typeof out.properties === "string") {
+    out.properties = parseDriftString(out.properties, "object", `node ${node.id}.properties`);
+  }
+  if (typeof out.tags === "string") {
+    out.tags = parseDriftString(out.tags, "array", `node ${node.id}.tags`);
+  }
+  return out;
+}
+function parseDriftString(raw, expect, where) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`[upg fmt] ${where} is a string that is not valid JSON: ${truncate(raw)}`);
+  }
+  const ok = expect === "array" ? Array.isArray(parsed) : parsed !== null && typeof parsed === "object" && !Array.isArray(parsed);
+  if (!ok) throw new Error(`[upg fmt] ${where} is a string that does not parse to a JSON ${expect}: ${truncate(raw)}`);
+  return parsed;
+}
+function truncate(s) {
+  return s.length > 60 ? s.slice(0, 57) + "..." : s;
+}
+function deriveSummary(description) {
+  if (!description) return void 0;
+  const firstLine = description.split("\n").map((l) => l.trim()).find((l) => l.length > 0);
+  if (!firstLine) return void 0;
+  return firstLine.length > 200 ? firstLine.slice(0, 197) + "..." : firstLine;
+}
+function sortNodes(nodes) {
+  return [...nodes].sort(
+    (a, b) => byCodeUnit(a.type ?? "", b.type ?? "") || byCodeUnit(a.slug ?? a.title ?? "", b.slug ?? b.title ?? "") || byCodeUnit(a.id ?? "", b.id ?? "")
+  );
+}
+function sortEdges(edges) {
+  return [...edges].sort(
+    (a, b) => byCodeUnit(a.source ?? "", b.source ?? "") || byCodeUnit(a.target ?? "", b.target ?? "") || byCodeUnit(a.type ?? "", b.type ?? "") || byCodeUnit(a.id ?? "", b.id ?? "")
+  );
+}
+var NODE_KEY_ORDER = [
+  "id",
+  "type",
+  "title",
+  "slug",
+  "aliases",
+  "description",
+  "tags",
+  "status",
+  "lifecycle_status",
+  "source_id",
+  "source_type",
+  "mapping_confidence",
+  "external_tool",
+  "external_ref",
+  "external_id",
+  "sort_order",
+  "properties"
+];
+var EDGE_KEY_ORDER = ["id", "source", "target", "type", "mapping_confidence"];
+var CROSS_EDGE_KEY_ORDER = ["id", "source", "target", "type", "source_product_id", "target_product_id", "mapping_confidence"];
+var PRODUCT_KEY_ORDER = ["id", "title", "description", "stage", "properties"];
+function canonicalNode(node) {
+  const repaired = repairNodeDrift(node);
+  if (Array.isArray(repaired.tags)) {
+    repaired.tags = [...new Set(repaired.tags)].sort(byCodeUnit);
+  }
+  return orderedObject(repaired, NODE_KEY_ORDER, { forceKeys: ["id", "type", "title"], openKeys: ["properties"] });
+}
+function canonicalEdge(edge) {
+  return orderedObject(edge, EDGE_KEY_ORDER, {
+    forceKeys: ["id", "source", "target", "type"]
+  });
+}
+function canonicalCrossEdge(edge) {
+  return orderedObject(edge, CROSS_EDGE_KEY_ORDER, {
+    forceKeys: ["id", "source", "target", "type"]
+  });
+}
+function canonicalProduct(product) {
+  return orderedObject(product, PRODUCT_KEY_ORDER, { forceKeys: ["id", "title"], openKeys: ["properties"] });
+}
+function singleBody(doc) {
+  return {
+    product: canonicalProduct(doc.product),
+    nodes: sortNodes(doc.nodes ?? []).map(canonicalNode),
+    edges: sortEdges(doc.edges ?? []).map(canonicalEdge)
+  };
+}
+function portfolioBody(doc) {
+  const products = [...doc.products ?? []].sort((a, b) => byCodeUnit(a.id ?? "", b.id ?? "")).map((p) => {
+    const { nodes, edges, ...rest } = p;
+    return {
+      ...canonicalProduct(rest),
+      nodes: sortNodes(nodes ?? []).map(canonicalNode),
+      edges: sortEdges(edges ?? []).map(canonicalEdge)
+    };
+  });
+  return {
+    organization: orderedObject(doc.organization, ["id", "title", "description", "logo_url", "industry"], { forceKeys: ["id", "title"] }),
+    product_areas: [...doc.product_areas ?? []].sort((a, b) => byCodeUnit(a.id ?? "", b.id ?? "")).map((a) => orderedObject(a, ["id", "title", "description", "parent_area_id", "strategic_priority", "products"], { forceKeys: ["id", "title"] })),
+    portfolios: [...doc.portfolios ?? []].sort((a, b) => byCodeUnit(a.id ?? "", b.id ?? "")).map((p) => orderedObject(p, ["id", "title", "description", "parent_portfolio_id", "hierarchy_model", "products"], { forceKeys: ["id", "title"] })),
+    products,
+    cross_edges: sortEdges(doc.cross_edges ?? []).map(canonicalCrossEdge)
+  };
+}
+function computeBodyChecksum(doc) {
+  const body = isPortfolio(doc) ? portfolioBody(doc) : singleBody(doc);
+  const content = JSON.stringify(body);
+  return createHash2(INTEGRITY_HASH_PRIMITIVE).update(content).digest("hex").slice(0, INTEGRITY_DIGEST_HEX);
+}
+function isPortfolio(doc) {
+  return doc.type === "portfolio" || "cross_edges" in doc;
+}
+function serializeCanonical(doc, opts = {}) {
+  if (isPortfolio(doc)) return serializePortfolioWithHeader(doc, opts);
+  return serializeSingleWithHeader(doc, opts);
+}
+function buildProvenance(doc, opts) {
+  const source = opts.source ?? doc.source ?? { tool: "unknown" };
+  return orderedObject(
+    {
+      tool: source.tool,
+      tool_version: source.tool_version,
+      workspace_id: source.workspace_id,
+      exported_at: opts.exportedAt ?? doc.exported_at
+    },
+    ["tool", "tool_version", "workspace_id", "exported_at"],
+    { forceKeys: ["tool"] }
+  );
+}
+function serializeSingleWithHeader(doc, opts) {
+  const body = singleBody(doc);
+  const product = doc.product;
+  const header = {
+    format_version: UPG_CANONICAL_FORMAT_VERSION,
+    spec_version: doc.upg_version,
+    product: orderedObject(
+      { id: product.id, title: product.title, stage: product.stage },
+      ["id", "title", "stage"],
+      { forceKeys: ["id", "title"] }
+    )
+  };
+  const summary = deriveSummary(product.description);
+  if (summary) header.summary = summary;
+  header.counts = { nodes: doc.nodes?.length ?? 0, edges: doc.edges?.length ?? 0 };
+  header.provenance = buildProvenance(doc, opts);
+  header.integrity = { algorithm: INTEGRITY_ALGORITHM, body: computeBodyChecksum(doc) };
+  return JSON.stringify({ $upg: header, ...body }, null, 2) + "\n";
+}
+function serializePortfolioWithHeader(doc, opts) {
+  const body = portfolioBody(doc);
+  const org = doc.organization;
+  const header = {
+    format_version: UPG_CANONICAL_FORMAT_VERSION,
+    spec_version: doc.upg_version,
+    kind: "portfolio",
+    organization: orderedObject(
+      { id: org.id, title: org.title },
+      ["id", "title"],
+      { forceKeys: ["id", "title"] }
+    )
+  };
+  const summary = deriveSummary(org.description);
+  if (summary) header.summary = summary;
+  header.counts = {
+    products: doc.products?.length ?? 0,
+    product_areas: doc.product_areas?.length ?? 0,
+    portfolios: doc.portfolios?.length ?? 0,
+    cross_edges: doc.cross_edges?.length ?? 0
+  };
+  header.provenance = buildProvenance(doc, opts);
+  header.integrity = { algorithm: INTEGRITY_ALGORITHM, body: computeBodyChecksum(doc) };
+  return JSON.stringify({ $upg: header, ...body }, null, 2) + "\n";
+}
 var UPG_VERSION = "0.7.3";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
@@ -22769,6 +23011,62 @@ var getGraphDigest = (args, ctx) => {
   }
   return text(JSON.stringify({ ...digest, lens: sessionContext.lens, lens_digest: lensDigest, _hash: currentHash }, null, 2));
 };
+var YOUNG_GRAPH_THRESHOLD = 8;
+var start = (_args, ctx) => {
+  const { store } = ctx;
+  const allNodes = store.getAllNodes();
+  const realNodes = allNodes.filter((n) => n.type !== "product");
+  const nodeCount = realNodes.length;
+  const product = store.getProduct();
+  const presentTypes = new Set(allNodes.map((n) => n.type));
+  const productInfo = product ? { title: product.title, stage: product.stage ?? null } : null;
+  const state = nodeCount === 0 ? "empty" : nodeCount < YOUNG_GRAPH_THRESHOLD ? "young" : "established";
+  if (state === "established") {
+    return text(
+      JSON.stringify(
+        {
+          graph_state: state,
+          product: productInfo,
+          node_count: nodeCount,
+          recommendation: `Graph is established (${nodeCount} entities). Use plan for the missing-entities backlog, inspect for issues, and get_graph_digest for health.`,
+          next_tools: ["plan", "inspect", "get_graph_digest"]
+        },
+        null,
+        2
+      )
+    );
+  }
+  const canonicalPlaybooks = UPG_PLAYBOOKS.filter((p) => p.is_canonical === true);
+  const recommend = canonicalPlaybooks.find(
+    (p) => p.target_anchor_entity ? !presentTypes.has(p.target_anchor_entity) : true
+  ) ?? canonicalPlaybooks[0];
+  const response = {
+    graph_state: state,
+    product: productInfo,
+    node_count: nodeCount
+  };
+  if (recommend) {
+    const anchor = recommend.target_anchor_entity;
+    response.recommended_playbook = {
+      id: recommend.id,
+      name: recommend.name,
+      region: recommend.region,
+      target_anchor_entity: anchor ?? null,
+      description: recommend.description
+    };
+    if (anchor) {
+      response.first_action = {
+        tool: "create_node",
+        args: { type: anchor, title: `<your first ${anchor}>` }
+      };
+    }
+    response.recommendation = state === "empty" ? `Your graph is empty. Begin with the "${recommend.name}" playbook${anchor ? `: create your first ${anchor}` : ""}. Open the full sequence with get_playbook("${recommend.id}").` : `You have ${nodeCount} ${nodeCount === 1 ? "entity" : "entities"}. Continue with the "${recommend.name}" playbook${anchor ? `: add a ${anchor}` : ""}. Use plan for the full missing-entities backlog.`;
+  } else {
+    response.recommendation = "No canonical playbooks available. Use plan to see the missing-entities backlog.";
+  }
+  response.next_tools = state === "empty" ? ["get_playbook", "create_node", "list_playbooks"] : ["plan", "get_playbook", "get_graph_digest"];
+  return text(JSON.stringify(response, null, 2));
+};
 var getSessionContext = (_args, ctx) => {
   const { sessionContext } = ctx;
   const recommendationsToAvoid = Array.from(
@@ -23496,6 +23794,21 @@ function buildFirstUseHints(canonicalType) {
   if (edgesOut.length > 0) hints.canonical_edges_out = edgesOut;
   return hints;
 }
+function buildOrphanWarning(canonicalType) {
+  let schema;
+  try {
+    schema = buildEntitySchema(canonicalType);
+  } catch {
+    return void 0;
+  }
+  const guide = schema.domain_guide;
+  if (!guide || guide.position_in_sequence <= 0) return void 0;
+  const anchor = guide.anchor_entity;
+  if (!anchor || anchor === canonicalType) return void 0;
+  const edge = resolveContainmentEdge(anchor, canonicalType);
+  const via = edge ? ` (canonical edge: ${edge})` : "";
+  return `Orphan: created ${canonicalType} with no parent. ${canonicalType} typically attaches under ${anchor}${via}. Pass parent_id on create, or wire it later with create_edge.`;
+}
 var createNode = async (args, ctx) => {
   const { store } = ctx;
   if (!args.type) return textError(`Missing required parameter: type`);
@@ -23562,6 +23875,10 @@ var createNode = async (args, ctx) => {
     const aggregatedWarnings = [];
     if (warning) aggregatedWarnings.push(warning);
     if (lengthWarnings.length > 0) aggregatedWarnings.push(...lengthWarnings);
+    if (!args.parent_id && !result.edge) {
+      const orphanWarning = buildOrphanWarning(result.node.type);
+      if (orphanWarning) aggregatedWarnings.push(orphanWarning);
+    }
     const libWarning = result.warning;
     const combinedWarning = libWarning ? aggregatedWarnings.length > 0 ? `${libWarning} | ${aggregatedWarnings.join(" | ")}` : libWarning : aggregatedWarnings.length > 0 ? aggregatedWarnings.join(" | ") : void 0;
     if (unknown_properties.length > 0 || combinedWarning || hints) {
@@ -26511,6 +26828,14 @@ var TOOL_DEFINITIONS = [
       }
     }
   },
+  {
+    name: "start",
+    description: 'Zero-state on-ramp: "there is nothing here yet, where do I begin?". Reads the live graph and, for an empty or barely-started graph, recommends the first canonical playbook (from UPG_PLAYBOOKS) plus the exact create_node call for its anchor entity. Established graphs are routed to plan / inspect / get_graph_digest instead. Takes no arguments.',
+    inputSchema: {
+      type: "object",
+      properties: {}
+    }
+  },
   {
     name: "list_nodes",
     description: "List entities with filtering, edge inclusion, count-only mode, and pagination. For graph-wide edge enumeration, prefer `export_edges` (flat) or `query` (traversal). `list_nodes(include_edges:true)` is for entity-scoped reads.",
@@ -27810,6 +28135,7 @@ var TOOL_DEFINITIONS = [
 var HANDLERS = {
   get_product_context: getProductContext,
   get_graph_digest: getGraphDigest,
+  start,
   list_nodes: listNodes,
   get_node: getNode,
   get_nodes: getNodes,
@@ -28112,11 +28438,7 @@ async function runMcpServer() {
       edges: []
     };
     await fs3.mkdir(path6.dirname(defaultFile), { recursive: true });
-    await fs3.writeFile(
-      defaultFile,
-      JSON.stringify(blank, null, 2) + "\n",
-      "utf-8"
-    );
+    await fs3.writeFile(defaultFile, serializeCanonical(blank), "utf-8");
     process.stderr.write(`Created new UPG file: ${defaultFile}
 `);
     resolvedPath = defaultFile;
@@ -28140,11 +28462,7 @@ async function runMcpServer() {
         edges: []
       };
       await fs3.mkdir(path6.dirname(resolvedPath), { recursive: true });
-      await fs3.writeFile(
-        resolvedPath,
-        JSON.stringify(blank, null, 2) + "\n",
-        "utf-8"
-      );
+      await fs3.writeFile(resolvedPath, serializeCanonical(blank), "utf-8");
       process.stderr.write(`Created new UPG file: ${resolvedPath}
 `);
     }