@unified-product-graph/mcp-server 0.9.0 → 0.9.2

package/dist/index.js

@@ -2,16 +2,16 @@
 
 // src/index.ts
 import { parseArgs } from "util";
-import * as fs3 from "fs/promises";
-import * as path6 from "path";
-import { UPGFileStore } from "@unified-product-graph/sdk";
+import * as fs4 from "fs/promises";
+import * as path7 from "path";
+import { UPGFileStore as UPGFileStore2 } from "@unified-product-graph/sdk";
 
 // src/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import fs2 from "fs";
+import fs3 from "fs";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import * as path5 from "path";
+import * as path6 from "path";
 import {
   CallToolRequestSchema,
   ListToolsRequestSchema
@@ -1303,8 +1303,24 @@ var UPG_EDGE_CATALOG = {
   journey_step_realised_by_feature: { forward_verb: "realised_by", reverse_verb: "realises", classification: "cross-domain", source_type: "journey_step", target_type: "feature" },
   opportunity_improves_user_journey: { forward_verb: "improves", reverse_verb: "improved_by", classification: "cross-domain", source_type: "opportunity", target_type: "user_journey" },
   user_journey_passes_through_journey_phase: { forward_verb: "passes_through", reverse_verb: "is_phase_of", classification: "hierarchy", source_type: "user_journey", target_type: "journey_phase" },
-  journey_phase_has_step: { forward_verb: "has_step", reverse_verb: "is_step_in", classification: "hierarchy", source_type: "journey_phase", target_type: "journey_step" },
+  // (since v0.9.2, UPG-663) A journey_phase is a temporal BAND over the
+  // journey's single step timeline, not a container that owns steps. Steps
+  // belong to the journey via `user_journey_contains_journey_step` (the stable
+  // 0.1.0 spine); a phase merely SPANS a range of them. Mirrors the marketing
+  // precedent `customer_journey_stage_spans_journey_step`. Renamed from the
+  // owning `journey_phase_has_step` (hierarchy) so a step has exactly one
+  // containment parent. See UPG_EDGE_MIGRATIONS['0.9.2'].
+  journey_phase_spans_journey_step: { forward_verb: "spans", reverse_verb: "spanned_by", classification: "cross-domain", source_type: "journey_phase", target_type: "journey_step" },
   journey_step_has_action: { forward_verb: "has_action", reverse_verb: "is_action_in", classification: "hierarchy", source_type: "journey_step", target_type: "journey_action" },
+  // (since v0.9.2, UPG-663) journey_action outbound edges. Fixes the
+  // discovery dead-end (D2). The finest blueprint layer carries pain_score /
+  // opportunity_score "to drive opportunity discovery" but previously had zero
+  // outbound edges. Opportunity discovery routes through `need` (mirroring
+  // `journey_step_reveals_need`), which already reaches `opportunity` via the
+  // user chain; the action does not link an opportunity directly. The feature
+  // edge mirrors `journey_step_realised_by_feature` one level deeper.
+  journey_action_surfaces_need: { forward_verb: "surfaces", reverse_verb: "surfaced_in", classification: "cross-domain", source_type: "journey_action", target_type: "need" },
+  journey_action_realised_by_feature: { forward_verb: "realised_by", reverse_verb: "realises", classification: "cross-domain", source_type: "journey_action", target_type: "feature" },
   // 2.5 UI System Domain
   product_systematised_in_design_system: { forward_verb: "systematised_in", reverse_verb: "systematises", classification: "hierarchy", source_type: "product", target_type: "design_system" },
   product_built_with_design_component: { forward_verb: "built_with", reverse_verb: "built_for", classification: "hierarchy", source_type: "product", target_type: "design_component" },
@@ -2741,7 +2757,8 @@ var UPG_CROSS_EDGE_TYPES = [
   "depends_on_product",
   "cannibalises",
   "succeeds",
-  "hosts"
+  "hosts",
+  "contributes_to"
 ];
 var TYPES = getTypes();
 var TYPES_SET = new Set(TYPES);
@@ -3028,8 +3045,13 @@ var UPG_VALID_CHILDREN = {
   // parallel to `observation: ['quote']`. Research-synthesis canon.
   // Pairs with `insight_evidenced_by_quote` in the edge catalog.
   // ── Design hierarchy ────────────────────────────────────────────────────────
+  // (UPG-663, v0.9.2) A user_journey owns its steps (the stable 0.1.0 spine)
+  // and carries phases as a non-owning band overlay. A journey_phase is NO
+  // LONGER a containment parent of journey_step: it SPANS steps via the
+  // `journey_phase_spans_journey_step` edge (mirroring the marketing
+  // `customer_journey_stage_spans_journey_step` precedent), so each step has
+  // exactly one containment parent and the journey has one canonical step list.
   user_journey: ["journey_step", "journey_phase"],
-  journey_phase: ["journey_step"],
   journey_step: ["journey_action"],
   // v0.5.8 (UPG-528 Part 2d): insights own their evidencing quotes;
   // parallel to `observation: ['quote']`. Research-synthesis canon
@@ -7126,6 +7148,20 @@ var UPG_SPLIT_MIGRATIONS = {
   ]
 };
 var UPG_EDGE_MIGRATIONS = {
+  "0.9.2": [
+    // (since v0.9.2, UPG-663) Journey-model disambiguation. A journey_phase
+    // is a temporal BAND over the journey's single step timeline, not a
+    // container that owns steps. The owning hierarchy edge
+    // `journey_phase_has_step` is renamed to the non-owning
+    // `journey_phase_spans_journey_step` (mirroring the marketing precedent
+    // `customer_journey_stage_spans_journey_step`). Steps stay owned by the
+    // journey via `user_journey_contains_journey_step` (the stable 0.1.0
+    // spine), so each step keeps a single containment parent and the journey
+    // renders one canonical step list. Endpoints are unchanged
+    // (journey_phase → journey_step); only the edge key and its grammar
+    // (verb has_step → spans, classification hierarchy → cross-domain) change.
+    { kind: "rename", from: "journey_phase_has_step", to: "journey_phase_spans_journey_step", requires_source_type: "journey_phase", requires_target_type: "journey_step", reason: "Journey-model disambiguation (UPG-663): a phase spans steps, it does not own them. The phase to step edge becomes non-owning (verb has_step to spans), so the step keeps a single containment parent (the journey) and the journey has one canonical step list." }
+  ],
   "0.9.0": [
     // (since v0.9.0, UPG-660) theme → roadmap_theme. The four canonical edges that
     // touch the roadmap theme are renamed to the roadmap_theme form. Endpoint guards
@@ -9544,6 +9580,7 @@ var UPG_PROPERTY_SCHEMA = {
   },
   // JourneyActionProperties: Discrete action at a journey step, classified by service layer.
   journey_action: {
+    action_order: { type: "number", description: "Display order of this action within its step (0-indexed). The scalar ordering convention shared with `journey_phase.phase_order` and `journey_step.step_order` (UPG-663). Orders the service-blueprint rows within a single moment." },
     layer: { type: "string", enum: ["user", "frontstage", "backstage", "support"], description: "Service layer" },
     action_description: { type: "string", description: "Plain-language description. Primary content of the action." },
     channel: { type: "string", enum: ["in-app", "email", "web", "mobile", "phone", "in-person", "sms", "social", "other"], description: "Channel or surface. Keeps service-blueprint columns consistent across the journey." },
@@ -9575,7 +9612,7 @@ var UPG_PROPERTY_SCHEMA = {
     system: { type: "string", description: "Performing system or service" },
     notes: { type: "string", description: "Free-text notes, observations, or follow-up questions" }
   },
-  // JourneyPhaseProperties: Phase within a user journey. Groups journey steps into stages.
+  // JourneyPhaseProperties: Phase within a user journey. A temporal BAND over the journey's step
   journey_phase: {
     phase_order: { type: "number", description: "Display order within the journey (0-indexed)" },
     label: { type: "string", description: 'Short human-readable name. @example "Discovery", "Onboarding", "Activation"' },
@@ -9586,8 +9623,9 @@ var UPG_PROPERTY_SCHEMA = {
     key_questions: { type: "string[]", description: "Open questions the user asks themselves. Fuel for design and content priorities." },
     timeframe: { type: "string", description: 'Typical time window. @example "first 30 seconds", "days 1\u20137", "onboarding week"' }
   },
-  // JourneyStepProperties: Single step within a user journey.
+  // JourneyStepProperties: Single step within a user journey. A user-moment on the journey's single
   journey_step: {
+    step_order: { type: "number", description: "Display order within the journey's step timeline (0-indexed). The scalar ordering convention shared with `journey_phase.phase_order` and `journey_action.action_order` (UPG-663). For branching journeys, the explicit `journey_step_precedes_journey_step` edge captures the chain." },
     touchpoint: { type: "string", description: "Interaction touchpoint" },
     channel: { type: "string", description: 'Channel (e.g. "web", "email", "in-store")' },
     emotion_score: {
@@ -17072,8 +17110,13 @@ var STANDARD_LABELS = {
   interview_guide: { alt_labels: ["discussion guide", "interview script", "moderator guide"] },
   survey_response: { alt_labels: ["survey answer", "questionnaire response"] },
   // Design layer
-  user_journey: { alt_labels: ["journey map", "customer journey", "experience map", "journey"] },
-  journey_step: { alt_labels: ["touchpoint", "journey stage", "journey phase"] },
+  // (UPG-663) alt_labels must not collide with other entity types' canonical
+  // names or alt_labels, or the string->type resolver is ambiguous.
+  // Dropped 'customer journey' (collides with customer_journey_stage),
+  // 'touchpoint' and 'journey phase' (both distinct entity surfaces: a
+  // touchpoint is the journey_step.touchpoint property, a phase is journey_phase).
+  user_journey: { alt_labels: ["journey map", "experience map", "journey"] },
+  journey_step: { alt_labels: ["journey moment", "journey stage"] },
   design_component: { alt_labels: ["component", "ui component", "design element"] },
   design_token: { alt_labels: ["token", "style token", "css variable"] },
   wireframe: { alt_labels: ["wireflow", "lo-fi mockup", "skeleton"] },
@@ -19085,7 +19128,11 @@ var PRODUCT_SPEC_GUIDE = {
 var UX_DESIGN_GUIDE = {
   domain_id: "ux_design",
   anchor_entity: "user_journey",
-  creation_sequence: ["user_journey", "journey_phase", "journey_action", "journey_step", "screen", "screen_state", "user_flow", "wireframe", "prototype", "design_question", "design_concept"],
+  // (UPG-663) creation order follows containment: a journey_action is a child
+  // of a journey_step, so the step must precede the action. The journey is the
+  // anchor; phases are the band overlay; steps are the timeline; actions
+  // decompose a step into service-blueprint rows.
+  creation_sequence: ["user_journey", "journey_phase", "journey_step", "journey_action", "screen", "screen_state", "user_flow", "wireframe", "prototype", "design_question", "design_concept"],
   patterns: [
     {
       name: "Journey to Screen Flow",
@@ -22357,6 +22404,40 @@ var UPG_ANTI_PATTERNS = [
     stages: ["concept", "validation", "build", "beta", "launch", "growth", "mature"],
     severity: "medium",
     source: { kind: "fundamental" }
+  },
+  // ── Experience-design layer ─────────────────────────────────────────────
+  {
+    id: "journey-phases-without-canonical-steps",
+    name: "Journey phases without a step spine",
+    description: 'The graph has journey phases spanning steps (`journey_phase_spans_journey_step`), but no journey owns its steps via `user_journey_contains_journey_step`. A phase is a band over a step timeline, not a container. When the timeline itself is missing there is no canonical answer to "what are the steps of this journey?". The phase overlay points at steps the journey does not own.',
+    structured_condition: {
+      operator: "and",
+      checks: [
+        {
+          check: {
+            type: "relationship",
+            source_type: "journey_phase",
+            edge_type: "journey_phase_spans_journey_step",
+            target_type: "journey_step",
+            comparison: "exists"
+          }
+        },
+        {
+          check: {
+            type: "relationship",
+            source_type: "user_journey",
+            edge_type: "user_journey_contains_journey_step",
+            target_type: "journey_step",
+            comparison: "not_exists"
+          }
+        }
+      ]
+    },
+    why_it_matters: "Steps owned by no journey render a different step list per consumer: the phase overlay sees them, a journey-direct walk does not. The journey has no deterministic step spine to traverse, score, or map to screens.",
+    remediation: "Own every step under its journey with `user_journey_contains_journey_step`, then let phases span ranges of that single timeline via `journey_phase_spans_journey_step`. The phase is a non-owning band overlay, not the step container.",
+    stages: ["concept", "validation", "build", "beta", "launch", "growth"],
+    severity: "high",
+    source: { kind: "fundamental" }
   }
 ];
 var SEVERITY_ORDER = {
@@ -24646,7 +24727,7 @@ function serializePortfolioWithHeader(doc, opts) {
   header.integrity = { algorithm: INTEGRITY_ALGORITHM, body: computeBodyChecksum(doc) };
   return JSON.stringify({ $upg: header, ...body }, null, 2) + "\n";
 }
-var UPG_VERSION = "0.9.0";
+var UPG_VERSION = "0.9.2";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
 var UPG_TYPES_SET = new Set(UPG_TYPES);
@@ -26849,6 +26930,38 @@ import {
   WorkspaceAlreadyExistsError,
   WorkspaceNotInitialisedError
 } from "@unified-product-graph/sdk";
+function isExistingFile(p) {
+  try {
+    return fs.statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+function findWorkspaceUpgFiles(cwd) {
+  const candidates = [];
+  let topEntries;
+  try {
+    topEntries = fs.readdirSync(cwd, { withFileTypes: true });
+  } catch {
+    return candidates;
+  }
+  for (const entry of topEntries) {
+    if (entry.isFile() && entry.name.endsWith(".upg")) {
+      candidates.push(path3.join(cwd, entry.name));
+    } else if (entry.isDirectory() && (entry.name === ".upg" || !entry.name.startsWith("."))) {
+      try {
+        const subEntries = fs.readdirSync(path3.join(cwd, entry.name), { withFileTypes: true });
+        for (const sub of subEntries) {
+          if (sub.isFile() && sub.name.endsWith(".upg")) {
+            candidates.push(path3.join(cwd, entry.name, sub.name));
+          }
+        }
+      } catch {
+      }
+    }
+  }
+  return candidates;
+}
 var listLocalProducts = (_args, _ctx) => {
   const cwd = process.cwd();
   const products = [];
@@ -26871,26 +26984,7 @@ var listLocalProducts = (_args, _ctx) => {
     }
   } catch {
   }
-  const candidates = [];
-  const topEntries = fs.readdirSync(cwd, { withFileTypes: true });
-  for (const entry of topEntries) {
-    if (entry.isFile() && entry.name.endsWith(".upg")) {
-      candidates.push(path3.join(cwd, entry.name));
-    } else if (entry.isDirectory() && (entry.name === ".upg" || !entry.name.startsWith("."))) {
-      try {
-        const subEntries = fs.readdirSync(
-          path3.join(cwd, entry.name),
-          { withFileTypes: true }
-        );
-        for (const sub of subEntries) {
-          if (sub.isFile() && sub.name.endsWith(".upg")) {
-            candidates.push(path3.join(cwd, entry.name, sub.name));
-          }
-        }
-      } catch {
-      }
-    }
-  }
+  const candidates = findWorkspaceUpgFiles(cwd);
   for (const filePath of candidates) {
     try {
       const raw = fs.readFileSync(filePath, "utf-8");
@@ -26920,21 +27014,19 @@ var switchProduct = async (args, ctx) => {
   if (typeof fileArg !== "string" || fileArg.length === 0) {
     return textError("Missing required parameter: file (alias: product). Pass a .upg path or a bare product name.");
   }
-  let resolved = path3.resolve(fileArg);
-  if (!fs.existsSync(resolved)) {
-    const cwd = process.cwd();
-    const workspaceCandidates = [
-      path3.join(cwd, ".upg", fileArg),
-      path3.join(cwd, ".upg", fileArg + ".upg")
-    ];
-    const found = workspaceCandidates.find((c) => fs.existsSync(c));
-    if (found) {
-      resolved = found;
-    } else {
-      return textError(
-        `File not found: ${resolved} (also checked .upg/${fileArg} and .upg/${fileArg}.upg)`
-      );
-    }
+  const cwd = process.cwd();
+  const direct = path3.resolve(fileArg);
+  const candidates = [
+    path3.join(cwd, ".upg", fileArg),
+    path3.join(cwd, ".upg", `${fileArg}.upg`),
+    direct,
+    `${direct}.upg`
+  ];
+  const resolved = candidates.find(isExistingFile);
+  if (!resolved) {
+    return textError(
+      `File not found: ${direct} (also checked .upg/${fileArg} and .upg/${fileArg}.upg). Pass a .upg path or a bare product name from list_local_products.`
+    );
   }
   try {
     await store.flush();
@@ -27419,6 +27511,312 @@ var batchCreateCrossProductEdges = async (args, _ctx) => {
   );
 };
 
+// src/tools/portfolio-read.ts
+import * as path4 from "path";
+import * as fs2 from "fs";
+import { UPGFileStore, computeGraphDigest as computeGraphDigest2 } from "@unified-product-graph/sdk";
+
+// src/lib/graph-traverse.ts
+function traverseGraph(reader, params) {
+  const fromType = params.from;
+  const fromId = params.from_id;
+  if (!fromType && !fromId) {
+    return { ok: false, error: 'Provide either "from" (entity type) or "from_id" (node ID)' };
+  }
+  const traverseEdgeTypes = params.traverse;
+  const maxDepth = Math.min(Math.max(params.depth ?? 3, 1), 10);
+  const maxNodes = Math.min(Math.max(params.limit ?? 200, 1), 1e3);
+  const includeFields = new Set(params.include ?? ["title", "status", "type"]);
+  includeFields.add("id");
+  includeFields.add("type");
+  let startNodes;
+  if (fromId) {
+    const node = reader.getNode(fromId);
+    if (!node) return { ok: false, error: `Node not found: ${fromId}` };
+    startNodes = [node];
+  } else {
+    startNodes = reader.getAllNodes().filter((n) => n.type === fromType);
+  }
+  if (startNodes.length === 0) {
+    return { ok: true, result: { nodes: [], edges: [], total_nodes: 0, total_edges: 0, truncated: false } };
+  }
+  const visited = /* @__PURE__ */ new Set();
+  const collectedNodes = [];
+  const collectedEdges = /* @__PURE__ */ new Map();
+  const queue = [];
+  let truncated = false;
+  let maxDepthReached = 0;
+  for (const n of startNodes) {
+    if (collectedNodes.length >= maxNodes) {
+      truncated = true;
+      break;
+    }
+    visited.add(n.id);
+    collectedNodes.push(n);
+    queue.push({ id: n.id, level: 0 });
+  }
+  while (queue.length > 0) {
+    if (collectedNodes.length >= maxNodes) {
+      truncated = true;
+      break;
+    }
+    const { id, level } = queue.shift();
+    if (level > maxDepthReached) maxDepthReached = level;
+    if (level >= maxDepth) continue;
+    const edges = reader.getEdgesForNode(id);
+    for (const edge of edges) {
+      if (edge.source !== id) continue;
+      if (traverseEdgeTypes && traverseEdgeTypes.length > 0) {
+        const edgeTypeForLevel = level < traverseEdgeTypes.length ? traverseEdgeTypes[level] : traverseEdgeTypes[traverseEdgeTypes.length - 1];
+        if (edgeTypeForLevel.startsWith("!")) {
+          if (edge.type === edgeTypeForLevel.slice(1)) continue;
+        } else {
+          if (edge.type !== edgeTypeForLevel) continue;
+        }
+      }
+      collectedEdges.set(edge.id, edge);
+      const neighborId = edge.target;
+      if (!visited.has(neighborId)) {
+        visited.add(neighborId);
+        const neighbor = reader.getNode(neighborId);
+        if (neighbor) {
+          if (collectedNodes.length >= maxNodes) {
+            truncated = true;
+            break;
+          }
+          collectedNodes.push(neighbor);
+          queue.push({ id: neighborId, level: level + 1 });
+        }
+      }
+    }
+  }
+  const propInclude = params.property_include;
+  const propFilter = propInclude && propInclude.length > 0 ? new Set(propInclude) : null;
+  const projectedNodes = collectedNodes.map((n) => {
+    const projected = { id: n.id, type: n.type };
+    if (includeFields.has("title")) projected.title = n.title;
+    if (includeFields.has("status")) projected.status = n.status;
+    if (includeFields.has("tags")) projected.tags = n.tags;
+    if (includeFields.has("description")) projected.description = n.description;
+    if (includeFields.has("properties")) {
+      if (propFilter && n.properties) {
+        const filtered = {};
+        for (const key of propFilter) {
+          if (key in n.properties) filtered[key] = n.properties[key];
+        }
+        projected.properties = filtered;
+      } else {
+        projected.properties = n.properties;
+      }
+    }
+    return projected;
+  });
+  const edgeInclude = params.edge_include;
+  let edgeArray;
+  if (edgeInclude !== void 0 && edgeInclude.length === 0) {
+    edgeArray = [];
+  } else {
+    const edgeFields = edgeInclude ? new Set(edgeInclude) : null;
+    edgeArray = [...collectedEdges.values()].map((e) => {
+      if (!edgeFields) return { id: e.id, type: e.type, source: e.source, target: e.target };
+      const projected = {};
+      if (edgeFields.has("id")) projected.id = e.id;
+      if (edgeFields.has("type")) projected.type = e.type;
+      if (edgeFields.has("source")) projected.source = e.source;
+      if (edgeFields.has("target")) projected.target = e.target;
+      return projected;
+    });
+  }
+  const result = {
+    nodes: projectedNodes,
+    edges: edgeArray,
+    total_nodes: projectedNodes.length,
+    total_edges: edgeArray.length,
+    truncated
+  };
+  if (truncated) result.truncated_at_depth = maxDepthReached;
+  return { ok: true, result };
+}
+
+// src/tools/portfolio-read.ts
+function resolveScopedProducts(cwd, scope) {
+  const all = [];
+  for (const absPath of findWorkspaceUpgFiles(cwd)) {
+    try {
+      const doc = JSON.parse(fs2.readFileSync(absPath, "utf-8"));
+      if (!doc.product) continue;
+      all.push({
+        id: doc.product.id ?? null,
+        title: doc.product.title ?? "(untitled)",
+        file: path4.relative(cwd, absPath),
+        absPath
+      });
+    } catch {
+    }
+  }
+  if (!scope || scope.length === 0) {
+    return { products: all, unmatched: [] };
+  }
+  const matches = (p, want) => p.id === want || p.file === want || path4.basename(p.file) === want || path4.basename(p.file, ".upg") === want;
+  const products = all.filter((p) => scope.some((want) => matches(p, want)));
+  const unmatched = scope.filter((want) => !all.some((p) => matches(p, want)));
+  return { products, unmatched };
+}
+async function readerFor(product, activeStore) {
+  const activePath = activeStore.getFilePath();
+  if (activePath && path4.resolve(activePath) === path4.resolve(product.absPath)) {
+    return { reader: activeStore, store: activeStore, active: true };
+  }
+  const store = new UPGFileStore();
+  await store.loadReadOnly(product.absPath);
+  return { reader: store, store, active: false };
+}
+var portfolioQuery = async (args, ctx) => {
+  const { store } = ctx;
+  const from = args.from;
+  const fromId = args.from_id;
+  if (!from && !fromId) {
+    return textError('Provide either "from" (entity type) or "from_id" (node ID)');
+  }
+  const scope = args.scope;
+  const cwd = process.cwd();
+  const { products, unmatched } = resolveScopedProducts(cwd, scope);
+  if (products.length === 0) {
+    return text(
+      JSON.stringify(
+        {
+          products: [],
+          products_searched: 0,
+          products_with_matches: 0,
+          empty_products: [],
+          ...unmatched.length > 0 ? { unmatched_scope: unmatched } : {},
+          note: scope && scope.length > 0 ? "No workspace products matched the requested scope." : "No products found in the workspace. Run from a directory with a .upg/ workspace."
+        },
+        null,
+        2
+      )
+    );
+  }
+  const perProductLimit = Math.min(Math.max(args.limit ?? 100, 1), 1e3);
+  const params = {
+    from,
+    from_id: fromId,
+    traverse: args.traverse,
+    depth: args.depth,
+    limit: perProductLimit,
+    include: args.include,
+    edge_include: args.edge_include,
+    property_include: args.property_include
+  };
+  const matched = [];
+  const emptyProducts = [];
+  const errored = [];
+  let totalNodes = 0;
+  let totalEdges = 0;
+  for (const product of products) {
+    let reader;
+    try {
+      ;
+      ({ reader } = await readerFor(product, store));
+    } catch (err) {
+      errored.push({ product_id: product.id, file: product.file, error: err.message });
+      continue;
+    }
+    const outcome = traverseGraph(reader, params);
+    if (!outcome.ok) {
+      emptyProducts.push(product.id ?? product.file);
+      continue;
+    }
+    const r = outcome.result;
+    if (r.total_nodes === 0) {
+      emptyProducts.push(product.id ?? product.file);
+      continue;
+    }
+    totalNodes += r.total_nodes;
+    totalEdges += r.total_edges;
+    matched.push({
+      product_id: product.id,
+      file: product.file,
+      title: product.title,
+      total_nodes: r.total_nodes,
+      total_edges: r.total_edges,
+      nodes: r.nodes,
+      edges: r.edges,
+      ...r.truncated ? { truncated: true, truncated_at_depth: r.truncated_at_depth } : {}
+    });
+  }
+  const guard = preflightPayload({
+    toolName: "portfolio_query",
+    nodeCount: totalNodes,
+    edgeCount: totalEdges,
+    compactEdges: true,
+    argsHint: `from=${from ?? fromId}, products=${matched.length}, limit=${perProductLimit}`
+  });
+  if (guard.kind === "refuse") return guard.result;
+  const response = {
+    products: matched,
+    products_searched: products.length,
+    products_with_matches: matched.length,
+    total_nodes: totalNodes,
+    total_edges: totalEdges,
+    empty_products: emptyProducts
+  };
+  if (errored.length > 0) response.errored_products = errored;
+  if (unmatched.length > 0) response.unmatched_scope = unmatched;
+  if (guard.kind === "warn") Object.assign(response, guard.fields);
+  return text(JSON.stringify(response, null, 2));
+};
+var portfolioDigest = async (args, ctx) => {
+  const { store } = ctx;
+  const scope = args.scope;
+  const cwd = process.cwd();
+  const { products, unmatched } = resolveScopedProducts(cwd, scope);
+  const summaries = [];
+  const errored = [];
+  const byStage = {};
+  let totalNodes = 0;
+  let totalEdges = 0;
+  for (const product of products) {
+    try {
+      const { store: reader } = await readerFor(product, store);
+      const digest = computeGraphDigest2(reader);
+      const stage = digest.product.stage || "unset";
+      byStage[stage] = (byStage[stage] ?? 0) + 1;
+      totalNodes += digest.counts.total_nodes;
+      totalEdges += digest.counts.total_edges;
+      const topTypes = Object.entries(digest.counts.by_type).sort((a, b) => b[1] - a[1]).slice(0, 5).map(([type, count]) => ({ type, count }));
+      summaries.push({
+        product_id: product.id,
+        file: product.file,
+        title: digest.product.title,
+        stage: digest.product.stage || null,
+        total_nodes: digest.counts.total_nodes,
+        total_edges: digest.counts.total_edges,
+        health: digest.health,
+        coverage_pct: digest.coverage.stage_summary?.overall_pct ?? null,
+        top_types: topTypes
+      });
+    } catch (err) {
+      errored.push({ product_id: product.id, file: product.file, error: err.message });
+    }
+  }
+  const response = {
+    products: summaries,
+    rollup: {
+      products: summaries.length,
+      total_nodes: totalNodes,
+      total_edges: totalEdges,
+      by_stage: byStage
+    }
+  };
+  if (errored.length > 0) response.errored_products = errored;
+  if (unmatched.length > 0) response.unmatched_scope = unmatched;
+  if (products.length === 0) {
+    response.note = scope && scope.length > 0 ? "No workspace products matched the requested scope." : "No products found in the workspace. Run from a directory with a .upg/ workspace.";
+  }
+  return text(JSON.stringify(response, null, 2));
+};
+
 // src/tools/schema.ts
 var getEntitySchema = (args, _ctx) => {
   const rawType = args.type;
@@ -28120,24 +28518,24 @@ var prioritise = (args, ctx) => {
 };
 var trace = (args, ctx) => {
   const anchor = args.anchor;
-  const path7 = args.path;
+  const path8 = args.path;
   const edgesOverride = args.edges_override;
   if (!anchor) {
     return textError("Missing required parameter: anchor (entity_id)");
   }
-  if (!path7 || !Array.isArray(path7) || path7.length === 0) {
+  if (!path8 || !Array.isArray(path8) || path8.length === 0) {
     return textError("Missing required parameter: path (UPGEntityType[])");
   }
-  if (edgesOverride && edgesOverride.length !== path7.length) {
+  if (edgesOverride && edgesOverride.length !== path8.length) {
     return textError(
-      `edges_override length (${edgesOverride.length}) must match path length (${path7.length})`
+      `edges_override length (${edgesOverride.length}) must match path length (${path8.length})`
     );
   }
-  const result = executeTrace(ctx.store, anchor, path7, edgesOverride);
+  const result = executeTrace(ctx.store, anchor, path8, edgesOverride);
   const payload = {
     params: {
       anchor,
-      path: path7,
+      path: path8,
       edges_override: edgesOverride ?? null
     },
     trail: result.trail,
@@ -28733,7 +29131,7 @@ var migrateStatus = (args, ctx) => {
 
 // src/tools/sync.ts
 import * as fsp4 from "fs/promises";
-import * as path4 from "path";
+import * as path5 from "path";
 import { nodeId, edgeId as edgeId4 } from "@unified-product-graph/sdk";
 var getSyncState = async (_args, ctx) => {
   const { store, sync } = ctx;
@@ -28901,7 +29299,7 @@ var pushToCloud = async (args, ctx) => {
   const productId = args.product_id;
   if (!cloudEndpoint || !apiKey) {
     try {
-      const mcpConfigPath = path4.join(process.cwd(), ".mcp.json");
+      const mcpConfigPath = path5.join(process.cwd(), ".mcp.json");
       const mcpRaw = await fsp4.readFile(mcpConfigPath, "utf-8");
       const mcpConfig = JSON.parse(mcpRaw);
       const upgCloud = mcpConfig.mcpServers?.["upg-cloud"];
@@ -28986,8 +29384,8 @@ var pushToCloud = async (args, ctx) => {
 };
 
 // src/tools/skills.ts
-import { existsSync as existsSync2, lstatSync, readlinkSync, readFileSync as readFileSync2, readdirSync as readdirSync2, realpathSync } from "fs";
-import { join as join5, resolve as resolve2, dirname as dirname3 } from "path";
+import { existsSync as existsSync2, lstatSync, readlinkSync, readFileSync as readFileSync3, readdirSync as readdirSync2, realpathSync } from "fs";
+import { join as join5, resolve as resolve3, dirname as dirname3 } from "path";
 import { fileURLToPath } from "url";
 function repoRoot() {
   return process.cwd();
@@ -29016,7 +29414,7 @@ function resolveBundledSkillsDir() {
   } catch {
     md = process.cwd();
   }
-  for (const c of [resolve2(md, "..", "skills"), resolve2(md, "..", "..", "skills"), resolve2(md, "skills")]) {
+  for (const c of [resolve3(md, "..", "skills"), resolve3(md, "..", "..", "skills"), resolve3(md, "skills")]) {
     if (isSkillsDir(c)) return c;
   }
   let dir = md;
@@ -29030,12 +29428,12 @@ function resolveBundledSkillsDir() {
   return null;
 }
 function sourceSkillsDir() {
-  const cwdPath = resolve2(repoRoot(), "packages/upg-mcp-server/skills");
+  const cwdPath = resolve3(repoRoot(), "packages/upg-mcp-server/skills");
   if (existsSync2(cwdPath)) return cwdPath;
   return resolveBundledSkillsDir() ?? cwdPath;
 }
 function deployedSkillsDir() {
-  return resolve2(repoRoot(), ".claude/skills");
+  return resolve3(repoRoot(), ".claude/skills");
 }
 function parseFrontmatter(body) {
   if (!body.startsWith("---\n")) return null;
@@ -29079,11 +29477,11 @@ function auditOne(name) {
   let deployedFrontmatter = null;
   let deployedFirstHeading = null;
   if (deployedExists) {
-    const deployedBody = readFileSync2(deployedPath, "utf8");
+    const deployedBody = readFileSync3(deployedPath, "utf8");
     deployedFrontmatter = parseFrontmatter(deployedBody);
     deployedFirstHeading = firstHeading(deployedBody);
     if (sourceExists) {
-      const sourceBody = readFileSync2(sourcePath, "utf8");
+      const sourceBody = readFileSync3(sourcePath, "utf8");
       inSync = deployedBody === sourceBody;
       if (!inSync) {
         issues.push("Deployed SKILL.md differs from canonical source; symlink is stale or broken");
@@ -30044,7 +30442,7 @@ var TOOL_DEFINITIONS = [
   },
   {
     name: "list_cross_edge_types",
-    description: "List the canonical cross-product edge types from `UPG_CROSS_EDGE_TYPES`: `shares_persona`, `shares_competitor`, `shares_metric`, `depends_on_product`, `cannibalises`, `succeeds`, `hosts`. Portfolio-level relationships across products. Distinct from the within-product `UPG_EDGE_CATALOG`.",
+    description: "List the canonical cross-product edge types from `UPG_CROSS_EDGE_TYPES`: `shares_persona`, `shares_competitor`, `shares_metric`, `depends_on_product`, `cannibalises`, `succeeds`, `hosts`, `contributes_to`. Portfolio-level relationships across products. Distinct from the within-product `UPG_EDGE_CATALOG`.",
     inputSchema: { type: "object", properties: {} }
   },
   {
@@ -30525,7 +30923,7 @@ var TOOL_DEFINITIONS = [
   },
   {
     name: "create_cross_product_edge",
-    description: "Create a cross-product relationship between two entities in different products within a portfolio graph. Types: `shares_persona`, `shares_competitor`, `shares_metric`, `depends_on_product`, `cannibalises`, `succeeds`, `hosts` (host product runs the hosted product inside itself, directed host to hosted).",
+    description: "Create a cross-product relationship between two entities in different products within a portfolio graph. Types: `shares_persona`, `shares_competitor`, `shares_metric`, `depends_on_product`, `cannibalises`, `succeeds`, `hosts` (host product runs the hosted product inside itself, directed host to hosted), `contributes_to` (a product strategy entity rolls up to a higher-level one, e.g. product objective \u2192 company objective, product key_result \u2192 company key_result; directed subordinate to superior).",
     inputSchema: {
       type: "object",
       properties: {
@@ -30533,7 +30931,7 @@ var TOOL_DEFINITIONS = [
         target_id: { type: "string", description: "Target node ID" },
         type: {
           type: "string",
-          enum: ["shares_persona", "shares_competitor", "shares_metric", "depends_on_product", "cannibalises", "succeeds", "hosts"],
+          enum: ["shares_persona", "shares_competitor", "shares_metric", "depends_on_product", "cannibalises", "succeeds", "hosts", "contributes_to"],
           description: "Cross-product relationship type"
         },
         source_product_id: { type: "string", description: "Product ID of the source node" },
@@ -30569,7 +30967,7 @@ var TOOL_DEFINITIONS = [
               target_id: { type: "string", description: "Target node ID (bare or qualified {product_id}/{node_id})" },
               type: {
                 type: "string",
-                enum: ["shares_persona", "shares_competitor", "shares_metric", "depends_on_product", "cannibalises", "succeeds", "hosts"],
+                enum: ["shares_persona", "shares_competitor", "shares_metric", "depends_on_product", "cannibalises", "succeeds", "hosts", "contributes_to"],
                 description: "Cross-product relationship type"
               },
               source_product_id: { type: "string", description: "Product ID of the source node (qualifies a bare source_id)" },
@@ -30588,6 +30986,58 @@ var TOOL_DEFINITIONS = [
     description: "List all cross-product edges stored in the portfolio document (`.upg/portfolio.upg`). Empty list when the portfolio document is absent.",
     inputSchema: { type: "object", properties: {} }
   },
+  {
+    name: "portfolio_query",
+    description: 'Traverse the graph ACROSS products in one call (the multi-product `query`). Runs the same BFS (typed-edge traversal + field projection) against every product in scope and tags each subgraph with its source `product_id`, without `switch_product` (the active product is read live; others are read-only). Use for portfolio-level questions ("every product\'s strategy region", "which products have a persona"). `from_id` only matches in its owning product. Read-only.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        from: { type: "string", description: "Start from all nodes of this type (in each product)" },
+        from_id: { type: "string", description: "Start from a specific node ID. Node IDs are product-local; only the owning product returns results." },
+        traverse: {
+          type: "array",
+          items: { type: "string" },
+          description: "Edge types to follow at each level (in order). If omitted, follows all edges. Prefix with ! to exclude."
+        },
+        depth: { type: "number", description: "Max traversal depth (default 3, max 10)" },
+        include: {
+          type: "array",
+          items: { type: "string" },
+          description: 'Fields per node: "title", "status", "tags", "description", "properties" (default: title, status, type)'
+        },
+        limit: { type: "number", description: "Max nodes per product (default 100, max 1000)" },
+        edge_include: {
+          type: "array",
+          items: { type: "string" },
+          description: 'Edge fields to return: "id", "type", "source", "target". Empty array = no edges. Default: all fields.'
+        },
+        property_include: {
+          type: "array",
+          items: { type: "string" },
+          description: 'When "properties" is in include, only return these property keys.'
+        },
+        scope: {
+          type: "array",
+          items: { type: "string" },
+          description: "Product IDs (or files) to query. Omit to query ALL products in the workspace. Match by product id, relative file, or basename."
+        }
+      }
+    }
+  },
+  {
+    name: "portfolio_digest",
+    description: "Roll up every product's counts, health, and stage-coverage in one call (the multi-product `get_graph_digest`). The strategic-surface read that otherwise required `switch_product` + `get_graph_digest` per graph. Returns per-product summaries plus a portfolio rollup (totals, products-by-stage). Read-only; never mutates active-product state.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        scope: {
+          type: "array",
+          items: { type: "string" },
+          description: "Product IDs (or files) to summarise. Omit to summarise ALL products in the workspace."
+        }
+      }
+    }
+  },
   {
     name: "migrate_cross_edges",
     description: "Migrate inline cross-product edges from the current product's `edges[]` into the portfolio document (`.upg/portfolio.upg`) with qualified IDs. `dry_run: true` (default) previews; `dry_run: false` applies. Requires `source_product_id` to qualify source node IDs.",
@@ -30774,6 +31224,8 @@ var HANDLERS = {
   attach_product_to_portfolio: attachProductToPortfolioTool,
   detach_product_from_portfolio: detachProductFromPortfolioTool,
   list_portfolio_cross_edges: listPortfolioCrossEdges,
+  portfolio_query: portfolioQuery,
+  portfolio_digest: portfolioDigest,
   migrate_cross_edges: migrateCrossEdges,
   get_sync_state: getSyncState,
   apply_pull_changeset: applyPullChangeset,
@@ -30832,9 +31284,9 @@ var SERVER_INSTRUCTIONS = [
 ].join("\n");
 function resolvePackageVersion() {
   try {
-    const here = path5.dirname(fileURLToPath2(import.meta.url));
-    const pkgPath = path5.resolve(here, "..", "package.json");
-    const raw = fs2.readFileSync(pkgPath, "utf-8");
+    const here = path6.dirname(fileURLToPath2(import.meta.url));
+    const pkgPath = path6.resolve(here, "..", "package.json");
+    const raw = fs3.readFileSync(pkgPath, "utf-8");
     const pkg = JSON.parse(raw);
     if (typeof pkg.version === "string" && pkg.version.length > 0) return pkg.version;
   } catch {
@@ -30876,7 +31328,7 @@ function createServer(store) {
     const result = handler ? await handler(args, ctx) : textError(`Unknown tool: ${name}`);
     if (logFile) {
       const entry = JSON.stringify({ ts: t0, tool: name, params: args, result, durationMs: Date.now() - t0 });
-      fs2.appendFileSync(logFile, entry + "\n");
+      fs3.appendFileSync(logFile, entry + "\n");
     }
     return result;
   });
@@ -30893,15 +31345,15 @@ import { nanoid } from "nanoid";
 import { fileURLToPath as fileURLToPath3 } from "url";
 import { realpathSync as realpathSync2 } from "fs";
 async function discoverUPGFile(explicitFile) {
-  if (explicitFile) return path6.resolve(explicitFile);
+  if (explicitFile) return path7.resolve(explicitFile);
   const cwd = process.cwd();
-  const workspacePath = path6.join(cwd, ".upg", "workspace.json");
+  const workspacePath = path7.join(cwd, ".upg", "workspace.json");
   try {
-    const raw = await fs3.readFile(workspacePath, "utf-8");
+    const raw = await fs4.readFile(workspacePath, "utf-8");
     const workspace = JSON.parse(raw);
     if (workspace.default_product) {
-      const filePath = path6.join(cwd, ".upg", workspace.default_product);
-      await fs3.access(filePath);
+      const filePath = path7.join(cwd, ".upg", workspace.default_product);
+      await fs4.access(filePath);
       const title = workspace.products?.find(
         (p) => p.file === workspace.default_product
       )?.title ?? workspace.default_product;
@@ -30912,16 +31364,16 @@ async function discoverUPGFile(explicitFile) {
       return filePath;
     }
   } catch {
-    const upgDir = path6.join(cwd, ".upg");
+    const upgDir = path7.join(cwd, ".upg");
     try {
-      const dirEntries = await fs3.readdir(upgDir);
+      const dirEntries = await fs4.readdir(upgDir);
       const upgFiles = dirEntries.filter((f) => f.endsWith(".upg")).sort();
       if (upgFiles.length > 0) {
         const products = [];
         for (const file of upgFiles) {
-          let title = path6.basename(file, ".upg");
+          let title = path7.basename(file, ".upg");
           try {
-            const raw = await fs3.readFile(path6.join(upgDir, file), "utf-8");
+            const raw = await fs4.readFile(path7.join(upgDir, file), "utf-8");
             const doc = JSON.parse(raw);
             if (doc.product?.title) title = doc.product.title;
           } catch {
@@ -30933,12 +31385,12 @@ async function discoverUPGFile(explicitFile) {
           default_product: upgFiles[0],
           products
         };
-        await fs3.writeFile(workspacePath, JSON.stringify(workspace, null, 2) + "\n", "utf-8");
+        await fs4.writeFile(workspacePath, JSON.stringify(workspace, null, 2) + "\n", "utf-8");
         process.stderr.write(
           `UPG workspace: auto-created workspace.json (${upgFiles.length} product${upgFiles.length > 1 ? "s" : ""})
 `
         );
-        const filePath = path6.join(upgDir, upgFiles[0]);
+        const filePath = path7.join(upgDir, upgFiles[0]);
         process.stderr.write(`UPG workspace: loading "${products[0].title}"
 `);
         return filePath;
@@ -30947,17 +31399,17 @@ async function discoverUPGFile(explicitFile) {
     }
   }
   try {
-    const entries = await fs3.readdir(cwd);
+    const entries = await fs4.readdir(cwd);
     const upgFiles = entries.filter((f) => f.endsWith(".upg")).sort();
     if (upgFiles.length === 1) {
-      return path6.resolve(upgFiles[0]);
+      return path7.resolve(upgFiles[0]);
     }
     if (upgFiles.length > 1) {
       process.stderr.write(
         `Found ${upgFiles.length} .upg files: loading ${upgFiles[0]}. Use --file to pick a specific one.
 `
       );
-      return path6.resolve(upgFiles[0]);
+      return path7.resolve(upgFiles[0]);
     }
   } catch {
   }
@@ -30977,7 +31429,7 @@ async function runMcpServer() {
   });
   let resolvedPath = await discoverUPGFile(values.file);
   if (!resolvedPath) {
-    const defaultFile = path6.resolve("product.upg");
+    const defaultFile = path7.resolve("product.upg");
     const title = values.title ?? "My Product";
     const blank = {
       upg_version: UPG_VERSION,
@@ -30993,16 +31445,16 @@ async function runMcpServer() {
       nodes: [],
       edges: []
     };
-    await fs3.mkdir(path6.dirname(defaultFile), { recursive: true });
-    await fs3.writeFile(defaultFile, serializeCanonical(blank), "utf-8");
+    await fs4.mkdir(path7.dirname(defaultFile), { recursive: true });
+    await fs4.writeFile(defaultFile, serializeCanonical(blank), "utf-8");
     process.stderr.write(`Created new UPG file: ${defaultFile}
 `);
     resolvedPath = defaultFile;
   } else {
     try {
-      await fs3.access(resolvedPath);
+      await fs4.access(resolvedPath);
     } catch {
-      const title = values.title ?? path6.basename(resolvedPath, ".upg");
+      const title = values.title ?? path7.basename(resolvedPath, ".upg");
       const blank = {
         upg_version: UPG_VERSION,
         exported_at: (/* @__PURE__ */ new Date()).toISOString(),
@@ -31017,13 +31469,13 @@ async function runMcpServer() {
         nodes: [],
         edges: []
       };
-      await fs3.mkdir(path6.dirname(resolvedPath), { recursive: true });
-      await fs3.writeFile(resolvedPath, serializeCanonical(blank), "utf-8");
+      await fs4.mkdir(path7.dirname(resolvedPath), { recursive: true });
+      await fs4.writeFile(resolvedPath, serializeCanonical(blank), "utf-8");
       process.stderr.write(`Created new UPG file: ${resolvedPath}
 `);
     }
   }
-  const store = new UPGFileStore();
+  const store = new UPGFileStore2();
   store.setWriter("upg-mcp-local", SERVER_VERSION);
   await store.load(resolvedPath);
   const nodes = store.getAllNodes();