@unified-product-graph/mcp-server 0.8.16 → 0.9.1

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
@@ -116,7 +116,7 @@ var UPG_DOMAINS = [
   {
     id: "product_spec",
     label: "Product Specification",
-    description: "What you are building and shipping. Feature areas group related capabilities. Features, epics, and user stories break work down. Acceptance criteria define done. Tasks and bugs track execution. Releases and changelogs mark what shipped. Roadmaps and roadmap items plan what comes next. Themes group strategic bets. Translates Strategy into Engineering and tracks delivery through Program Management.",
+    description: "What you are building and shipping. Feature areas group related capabilities. Features, epics, and user stories break work down. Acceptance criteria define done. Tasks and bugs track execution. Releases and changelogs mark what shipped. Roadmaps and roadmap items plan what comes next. Roadmap themes group roadmap work around the customer problem it solves, one level down from the strategic themes in Strategy. Translates Strategy into Engineering and tracks delivery through Program Management.",
     types: [
       "feature",
       "feature_area",
@@ -128,7 +128,7 @@ var UPG_DOMAINS = [
       "bug",
       "roadmap",
       "roadmap_item",
-      "theme",
+      "roadmap_theme",
       "changelog"
     ]
   },
@@ -556,8 +556,8 @@ var UPG_ENTITY_META = [
   { name: "need", type_id: "ent_313", maturity: "stable", since: "0.1.0" },
   { name: "switching_cost", type_id: "ent_022", maturity: "stable", since: "0.1.0" },
   // ── Discovery ──
-  { name: "opportunity", type_id: "ent_023", maturity: "stable", since: "0.1.0" },
-  { name: "solution", type_id: "ent_024", maturity: "stable", since: "0.1.0" },
+  { name: "opportunity", type_id: "ent_023", maturity: "stable", since: "0.1.0", default_frameworks: ["opportunity-sizing", "rice-scoring"] },
+  { name: "solution", type_id: "ent_024", maturity: "stable", since: "0.1.0", default_frameworks: ["rice-scoring"] },
   { name: "feasibility_study", type_id: "ent_025", maturity: "stable", since: "0.1.0" },
   { name: "design_sprint", type_id: "ent_026", maturity: "stable", since: "0.1.0" },
   // ── Validation ──
@@ -658,7 +658,8 @@ var UPG_ENTITY_META = [
   { name: "bug", type_id: "ent_077", maturity: "stable", since: "0.1.0" },
   { name: "roadmap", type_id: "ent_078", maturity: "stable", since: "0.1.0" },
   { name: "roadmap_item", type_id: "ent_079", maturity: "stable", since: "0.1.0" },
-  { name: "theme", type_id: "ent_080", maturity: "stable", since: "0.1.0" },
+  { name: "theme", type_id: "ent_080", maturity: "deprecated", since: "0.1.0", deprecated_in: "0.9.0", replacement: "roadmap_theme" },
+  { name: "roadmap_theme", type_id: "ent_351", maturity: "stable", since: "0.1.0" },
   { name: "changelog", type_id: "ent_081", maturity: "stable", since: "0.1.0" },
   // ── Engineering ──
   { name: "bounded_context", type_id: "ent_082", maturity: "stable", since: "0.1.0" },
@@ -1165,6 +1166,12 @@ var UPG_EDGE_CATALOG = {
   strategic_pillar_delivers_value_stream: { forward_verb: "delivers", reverse_verb: "delivered_by", classification: "hierarchy", source_type: "strategic_pillar", target_type: "value_stream" },
   strategic_pillar_decided_via_decision: { forward_verb: "decided_via", reverse_verb: "decided_for", classification: "hierarchy", source_type: "strategic_pillar", target_type: "decision" },
   strategic_theme_pursues_initiative: { forward_verb: "pursues", reverse_verb: "pursued_under", classification: "hierarchy", source_type: "strategic_theme", target_type: "initiative" },
+  // v0.9.0 (UPG-660): the soft bridge from the annual strategy focus area to the
+  // roadmap grouping that realises it. Semantic, NOT hierarchy: strategic_theme and
+  // roadmap_theme sit on different spines (strategy cascade vs roadmap cascade), so
+  // this is a cross-reference, not containment. Pairs with the theme → roadmap_theme
+  // rename that removed the bare-'theme' collision (N6/UPG-652 lineage).
+  strategic_theme_realised_by_roadmap_theme: { forward_verb: "realised_by", reverse_verb: "realises", classification: "semantic", source_type: "strategic_theme", target_type: "roadmap_theme" },
   // v0.5.4 (UPG-511): three edges that lift strategic_theme from structural
   // isolation to a conceptually central strategy node.
   //
@@ -1222,7 +1229,7 @@ var UPG_EDGE_CATALOG = {
   product_builds_feature: { forward_verb: "builds", reverse_verb: "built_by", classification: "hierarchy", source_type: "product", target_type: "feature" },
   product_ships_via_release: { forward_verb: "ships_via", reverse_verb: "ships", classification: "hierarchy", source_type: "product", target_type: "release" },
   product_plans_via_roadmap: { forward_verb: "plans_via", reverse_verb: "plans_for", classification: "hierarchy", source_type: "product", target_type: "roadmap" },
-  product_categorises_by_theme: { forward_verb: "categorises_by", reverse_verb: "categorises", classification: "hierarchy", source_type: "product", target_type: "theme" },
+  product_categorises_by_roadmap_theme: { forward_verb: "categorises_by", reverse_verb: "categorises", classification: "hierarchy", source_type: "product", target_type: "roadmap_theme" },
   feature_area_contains_feature: { forward_verb: "contains", reverse_verb: "belongs_to", classification: "hierarchy", source_type: "feature_area", target_type: "feature" },
   feature_area_contains_feature_area: { forward_verb: "contains", reverse_verb: "belongs_to", classification: "hierarchy", source_type: "feature_area", target_type: "feature_area" },
   outcome_delivered_by_feature: { forward_verb: "delivered_by", reverse_verb: "delivers", classification: "cross-domain", source_type: "outcome", target_type: "feature" },
@@ -1246,12 +1253,12 @@ var UPG_EDGE_CATALOG = {
   release_contains_bug: { forward_verb: "contains", reverse_verb: "belongs_to", classification: "hierarchy", source_type: "release", target_type: "bug" },
   release_documented_in_changelog: { forward_verb: "documented_in", reverse_verb: "documents", classification: "hierarchy", source_type: "release", target_type: "changelog" },
   roadmap_contains_roadmap_item: { forward_verb: "contains", reverse_verb: "belongs_to", classification: "hierarchy", source_type: "roadmap", target_type: "roadmap_item" },
-  roadmap_categorised_by_theme: { forward_verb: "categorised_by", reverse_verb: "categorises", classification: "hierarchy", source_type: "roadmap", target_type: "theme" },
+  roadmap_categorised_by_roadmap_theme: { forward_verb: "categorised_by", reverse_verb: "categorises", classification: "hierarchy", source_type: "roadmap", target_type: "roadmap_theme" },
   roadmap_schedules_release: { forward_verb: "schedules", reverse_verb: "scheduled_in", classification: "hierarchy", source_type: "roadmap", target_type: "release" },
-  theme_groups_feature: { forward_verb: "groups", reverse_verb: "grouped_in", classification: "hierarchy", source_type: "theme", target_type: "feature" },
-  // feature_area is not contained by theme; themes span multiple
+  roadmap_theme_groups_feature: { forward_verb: "groups", reverse_verb: "grouped_in", classification: "hierarchy", source_type: "roadmap_theme", target_type: "feature" },
+  // feature_area is not contained by roadmap_theme; roadmap themes span multiple
   // areas cross-cuttingly. Containment path: product → feature_area.
-  theme_spans_feature_area: { forward_verb: "spans", reverse_verb: "spanned_by", classification: "semantic", source_type: "theme", target_type: "feature_area" },
+  roadmap_theme_spans_feature_area: { forward_verb: "spans", reverse_verb: "spanned_by", classification: "semantic", source_type: "roadmap_theme", target_type: "feature_area" },
   // The legacy `story_task` collapsed into `task` (v0.4.0), so the implements
   // relationship is the canonical `task_implements_user_story` above; there is
   // no separate story_task edge. (v0.2.7 introduced the Statement/Implementation
@@ -2734,7 +2741,8 @@ var UPG_CROSS_EDGE_TYPES = [
   "depends_on_product",
   "cannibalises",
   "succeeds",
-  "hosts"
+  "hosts",
+  "contributes_to"
 ];
 var TYPES = getTypes();
 var TYPES_SET = new Set(TYPES);
@@ -2828,7 +2836,7 @@ var UPG_VALID_CHILDREN = {
     "feature_area",
     "release",
     "roadmap",
-    "theme",
+    "roadmap_theme",
     // Engineering
     "bounded_context",
     "code_repository",
@@ -3224,8 +3232,8 @@ var UPG_VALID_CHILDREN = {
   a11y_standard: ["a11y_guideline", "a11y_audit", "a11y_annotation"],
   a11y_audit: ["a11y_issue"],
   // ── Product Specification expansion ─────────────────────────────────────────
-  roadmap: ["roadmap_item", "theme", "release"],
-  theme: ["feature"],
+  roadmap: ["roadmap_item", "roadmap_theme", "release"],
+  roadmap_theme: ["feature"],
   // ── Unified Context Layer hierarchy ─────────────────────────────────────────
   design_system: [
     "design_component",
@@ -5821,7 +5829,7 @@ var UPG_LIFECYCLE_FREE_TYPES = /* @__PURE__ */ new Set([
   //    v0.7.0/UPG-571. ─
   "acceptance_criterion",
   "changelog",
-  "theme",
+  "roadmap_theme",
   "user_story",
   // ── Strategy: metric is a measurement definition; metric_quality_assessment
   //    is a point-in-time snapshot; value_stream is a mapped flow;
@@ -6122,6 +6130,21 @@ var UPG_SCALES = {
   }
 };
 var UPG_MIGRATIONS = {
+  "0.9.0": [
+    // (since v0.9.0, UPG-660) theme → roadmap_theme. `theme` was the only bare,
+    // unqualified theme among four domain-prefixed siblings (strategic_theme,
+    // content_theme, feedback_theme); it claimed the unqualified word and read as
+    // interchangeable with strategic_theme (the N6/UPG-652 confusion). Renamed to
+    // roadmap_theme so all four read consistently and the customer-problem roadmap
+    // grouping is explicit. Lifecycle-free, identical property surface (theme_scope
+    // / priority); no property migration required. Paired edge renames live in
+    // UPG_EDGE_MIGRATIONS['0.9.0'].
+    {
+      from: "theme",
+      to: "roadmap_theme",
+      reason: 'theme renamed to roadmap_theme (UPG-660). The bare "theme" was the only domain-unprefixed theme among strategic_theme / content_theme / feedback_theme; it grabbed the unqualified word and read as interchangeable with strategic_theme. roadmap_theme makes the customer-problem roadmap grouping explicit and consistent across the four. Same property surface (theme_scope / priority); no property migration needed.'
+    }
+  ],
   "0.7.0": [
     // (since v0.7.0, UPG-571) story_statement → user_story. The v0.2.7 split
     // correctly separated the templated promise from the engineering work
@@ -7104,6 +7127,17 @@ var UPG_SPLIT_MIGRATIONS = {
   ]
 };
 var UPG_EDGE_MIGRATIONS = {
+  "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
+    // reference the POST-migration (roadmap_theme) types; edge migration runs after
+    // node migration, so by the time these rules apply the node has already been
+    // renamed theme → roadmap_theme (UPG_MIGRATIONS['0.9.0']).
+    { kind: "rename", from: "product_categorises_by_theme", to: "product_categorises_by_roadmap_theme", requires_source_type: "product", requires_target_type: "roadmap_theme", reason: "theme \u2192 roadmap_theme (UPG-660). Product categorises by the roadmap theme; edge key updated to the renamed target type." },
+    { kind: "rename", from: "roadmap_categorised_by_theme", to: "roadmap_categorised_by_roadmap_theme", requires_source_type: "roadmap", requires_target_type: "roadmap_theme", reason: "theme \u2192 roadmap_theme (UPG-660). Roadmap is categorised by the roadmap theme; edge key updated to the renamed target type." },
+    { kind: "rename", from: "theme_groups_feature", to: "roadmap_theme_groups_feature", requires_source_type: "roadmap_theme", requires_target_type: "feature", reason: "theme \u2192 roadmap_theme (UPG-660). The roadmap theme groups features; edge key updated to the renamed source type." },
+    { kind: "rename", from: "theme_spans_feature_area", to: "roadmap_theme_spans_feature_area", requires_source_type: "roadmap_theme", requires_target_type: "feature_area", reason: "theme \u2192 roadmap_theme (UPG-660). The roadmap theme spans feature areas; edge key updated to the renamed source type." }
+  ],
   "0.7.0": [
     // (since v0.7.0, UPG-571) story_statement → user_story re-canon. The four
     // canonical edges that touch the statement are renamed to the user_story
@@ -9920,7 +9954,7 @@ var UPG_PROPERTY_SCHEMA = {
     reach: {
       type: "assessment",
       scale_id: "reach_5",
-      description: "How many users experience this problem",
+      description: "How many users experience this problem. @deprecated 0.9.0:a framework-scoped scoring input, not an intrinsic property. Apply the `opportunity-sizing` framework; the value lives on the framework_exercise includes-edge. Removed in 0.9.1.",
       properties: {
         value: { type: "number", description: "The numeric value, used for computation." },
         label: { type: "string", description: "The qualitative label (what the assessor meant)." },
@@ -9932,7 +9966,7 @@ var UPG_PROPERTY_SCHEMA = {
     frequency: {
       type: "assessment",
       scale_id: "frequency_5",
-      description: "How often users experience this problem",
+      description: "How often users experience this problem. @deprecated 0.9.0:framework-scoped (opportunity-sizing). Removed in 0.9.1.",
       properties: {
         value: { type: "number", description: "The numeric value, used for computation." },
         label: { type: "string", description: "The qualitative label (what the assessor meant)." },
@@ -9944,7 +9978,7 @@ var UPG_PROPERTY_SCHEMA = {
     pain: {
       type: "assessment",
       scale_id: "pain_5",
-      description: "How painful it is when unaddressed",
+      description: "How painful it is when unaddressed. @deprecated 0.9.0:framework-scoped (opportunity-sizing). Removed in 0.9.1.",
       properties: {
         value: { type: "number", description: "The numeric value, used for computation." },
         label: { type: "string", description: "The qualitative label (what the assessor meant)." },
@@ -9953,7 +9987,7 @@ var UPG_PROPERTY_SCHEMA = {
       },
       required: ["value", "label"]
     },
-    opportunity_score: { type: "number", description: "Computed: normalized_reach x normalized_frequency x normalized_pain (0-1)" }
+    opportunity_score: { type: "number", description: "Computed: normalized_reach x normalized_frequency x normalized_pain (0-1). @deprecated 0.9.0:computed by the `opportunity-sizing` framework on its application edge, not stored on the entity. Removed in 0.9.1." }
   },
   // OrganizationProperties: Organization entity.
   organization: {
@@ -10367,6 +10401,11 @@ var UPG_PROPERTY_SCHEMA = {
     start_date: { type: "string", description: "ISO date work begins. More precise than `quarter` for continuous planning." },
     target_date: { type: "string", description: "ISO date completion is expected. For shipped items, the actual completion date." }
   },
+  // RoadmapThemeProperties: Thematic grouping of roadmap work, around the customer problem it solves.
+  roadmap_theme: {
+    theme_scope: { type: "string", description: "Scope description" },
+    priority: { type: "string", enum: ["urgent", "high", "medium", "low", "none"], description: "Priority" }
+  },
   // RoleProperties: Role entity.
   role: {
     responsibilities: { type: "string[]", description: "Key responsibilities of the role" },
@@ -10552,7 +10591,7 @@ var UPG_PROPERTY_SCHEMA = {
     reach: {
       type: "assessment",
       scale_id: "reach_5",
-      description: "How many users this solution reaches (1 = few, 5 = most)",
+      description: "How many users this solution reaches (1 = few, 5 = most). @deprecated 0.9.0:a framework-scoped scoring input, not an intrinsic property. Apply the `rice-scoring` framework; the value lives on the framework_exercise includes-edge. Removed in 0.9.1.",
       properties: {
         value: { type: "number", description: "The numeric value, used for computation." },
         label: { type: "string", description: "The qualitative label (what the assessor meant)." },
@@ -10564,7 +10603,7 @@ var UPG_PROPERTY_SCHEMA = {
     impact: {
       type: "assessment",
       scale_id: "impact_5",
-      description: "Expected impact on the target outcome (1 = minimal, 5 = transformative)",
+      description: "Expected impact on the target outcome (1 = minimal, 5 = transformative). @deprecated 0.9.0:framework-scoped (rice-scoring). Removed in 0.9.1.",
       properties: {
         value: { type: "number", description: "The numeric value, used for computation." },
         label: { type: "string", description: "The qualitative label (what the assessor meant)." },
@@ -10576,7 +10615,7 @@ var UPG_PROPERTY_SCHEMA = {
     confidence: {
       type: "assessment",
       scale_id: "confidence_5",
-      description: "How confident the team is in this solution (1 = speculative, 5 = proven)",
+      description: "How confident the team is in this solution (1 = speculative, 5 = proven). @deprecated 0.9.0:framework-scoped (rice-scoring). Removed in 0.9.1.",
       properties: {
         value: { type: "number", description: "The numeric value, used for computation." },
         label: { type: "string", description: "The qualitative label (what the assessor meant)." },
@@ -10588,7 +10627,7 @@ var UPG_PROPERTY_SCHEMA = {
     effort: {
       type: "assessment",
       scale_id: "effort_5",
-      description: "Level of effort required to implement (1 = trivial, 5 = very large)",
+      description: "Level of effort required to implement (1 = trivial, 5 = very large). @deprecated 0.9.0:effort is a framework-scoped scoring input (it varies by assessor and method), not an intrinsic property. Removed in 0.9.1.",
       properties: {
         value: { type: "number", description: "The numeric value, used for computation." },
         label: { type: "string", description: "The qualitative label (what the assessor meant)." },
@@ -10597,7 +10636,7 @@ var UPG_PROPERTY_SCHEMA = {
       },
       required: ["value", "label"]
     },
-    rice_score: { type: "number", description: "Computed: (reach \xD7 impact \xD7 confidence) / effort" }
+    rice_score: { type: "number", description: "Computed: (reach \xD7 impact \xD7 confidence) / effort. @deprecated 0.9.0:computed by the `rice-scoring` framework on its application edge, not stored on the entity. Removed in 0.9.1." }
   },
   // StakeholderProperties: Stakeholder entity.
   stakeholder: {
@@ -10844,11 +10883,6 @@ var UPG_PROPERTY_SCHEMA = {
     skipped_count: { type: "number", description: "Number of tests that were skipped in the last run" },
     flaky_count: { type: "number", description: "Number of tests that passed only on retry (flaky) in the last run" }
   },
-  // ThemeProperties: Thematic grouping of work.
-  theme: {
-    theme_scope: { type: "string", description: "Scope description" },
-    priority: { type: "string", enum: ["urgent", "high", "medium", "low", "none"], description: "Priority" }
-  },
   // ThreatProperties: Threat.
   threat: {
     category: { type: "string", description: 'Attack or threat scenario. @example "injection", "misconfiguration", "social engineering", "supply chain"' },
@@ -11077,6 +11111,188 @@ function getPropertySchema(entityType) {
   return UPG_PROPERTY_SCHEMA[entityType];
 }
 var UPG_FRAMEWORKS = [
+  {
+    "id": "opportunity-sizing",
+    "approach_ids": [
+      "prioritise"
+    ],
+    "name": "Opportunity Sizing",
+    "version": "1.0.0",
+    "description": "Size opportunities by Reach, Frequency, and Pain to rank which problems are most worth solving before committing to solutions.",
+    "category": "prioritization",
+    "origin": {
+      "type": "practitioner",
+      "attribution": "Continuous discovery practice",
+      "description": "A lightweight discovery-prioritisation method: weigh how many users hit a problem, how often, and how much it hurts, to rank opportunities before investing in solutions.",
+      "url": "https://www.producttalk.org/2016/08/opportunity-solution-tree/",
+      "year": 2016,
+      "license": "open_attribution"
+    },
+    "tags": [
+      "prioritization",
+      "discovery",
+      "table"
+    ],
+    "slots": [
+      {
+        "label": "Opportunities to size",
+        "entityTypeId": "opportunity",
+        "description": "Opportunities scored on Reach, Frequency, and Pain."
+      }
+    ],
+    "data": {
+      "entity_types": [
+        {
+          "type": "opportunity",
+          "role": "scored_item"
+        }
+      ],
+      "required_properties": {
+        "opportunity": [
+          {
+            "property": "reach",
+            "type": "assessment",
+            "scale_id": "reach_5",
+            "required": true,
+            "scope": "framework",
+            "label": "Reach",
+            "description": "How many users experience this problem?"
+          },
+          {
+            "property": "frequency",
+            "type": "assessment",
+            "scale_id": "frequency_5",
+            "required": true,
+            "scope": "framework",
+            "label": "Frequency",
+            "description": "How often do they run into it?"
+          },
+          {
+            "property": "pain",
+            "type": "assessment",
+            "scale_id": "pain_5",
+            "required": true,
+            "scope": "framework",
+            "label": "Pain",
+            "description": "How painful is it when left unaddressed?"
+          }
+        ]
+      },
+      "computed_properties": [
+        {
+          "property": "opportunity_score",
+          "expression": "reach * frequency * pain",
+          "entity_type": "opportunity",
+          "label": "Opportunity Score",
+          "format": "number"
+        }
+      ],
+      "scoring_method": {
+        "applies_to": [
+          "opportunity"
+        ],
+        "inputs": [
+          {
+            "property": "reach",
+            "type": "assessment",
+            "scale_id": "reach_5",
+            "required": true,
+            "scope": "framework",
+            "label": "Reach",
+            "description": "How many users experience this problem?"
+          },
+          {
+            "property": "frequency",
+            "type": "assessment",
+            "scale_id": "frequency_5",
+            "required": true,
+            "scope": "framework",
+            "label": "Frequency",
+            "description": "How often do they run into it?"
+          },
+          {
+            "property": "pain",
+            "type": "assessment",
+            "scale_id": "pain_5",
+            "required": true,
+            "scope": "framework",
+            "label": "Pain",
+            "description": "How painful is it when left unaddressed?"
+          }
+        ],
+        "computed": [
+          {
+            "property": "opportunity_score",
+            "expression": "reach * frequency * pain",
+            "label": "Opportunity Score",
+            "format": "number"
+          }
+        ]
+      }
+    },
+    "structure": {
+      "pattern": "table"
+    },
+    "presentation": {
+      "layout": {
+        "type": "table",
+        "columns": [
+          {
+            "property": "title",
+            "label": "Opportunities to size",
+            "sortable": true
+          },
+          {
+            "property": "reach",
+            "label": "Reach",
+            "sortable": true,
+            "format": "number"
+          },
+          {
+            "property": "frequency",
+            "label": "Frequency",
+            "sortable": true,
+            "format": "number"
+          },
+          {
+            "property": "pain",
+            "label": "Pain",
+            "sortable": true,
+            "format": "number"
+          },
+          {
+            "property": "opportunity_score",
+            "label": "Opportunity Score",
+            "sortable": true,
+            "format": "score_pill"
+          }
+        ]
+      },
+      "sort_by": {
+        "property": "opportunity_score",
+        "direction": "desc"
+      },
+      "colour_by": "score",
+      "card_fields": [
+        "title",
+        "description",
+        "status"
+      ]
+    },
+    "education": {
+      "purpose": "Rank opportunities by how widely, how often, and how painfully a problem is felt, so discovery effort flows to the problems most worth solving.",
+      "core_question": "Of the problems we could pursue, which affect the most users, most often, with the most pain?",
+      "when_to_use": [
+        "You have more opportunities than you can pursue",
+        "You need to compare problems before committing to solutions",
+        "You want a defensible, transparent way to choose what to explore"
+      ],
+      "when_not_to_use": [
+        "A single opportunity is already validated and obvious",
+        "You have no signal yet on reach, frequency, or pain"
+      ]
+    }
+  },
   {
     "id": "opportunity-solution-tree",
     "approach_ids": [
@@ -12333,7 +12549,7 @@ var UPG_FRAMEWORKS = [
     ],
     "name": "RICE Scoring",
     "version": "1.0.0",
-    "description": "Score features, opportunities, and needs by Reach, Impact, Confidence, and Effort to produce a ranked priority list.",
+    "description": "Score features, solutions, opportunities, and needs by Reach, Impact, Confidence, and Effort to produce a ranked priority list.",
     "category": "prioritization",
     "origin": {
       "type": "practitioner",
@@ -12358,6 +12574,11 @@ var UPG_FRAMEWORKS = [
         "entityTypeId": "opportunity",
         "description": "Opportunities scored on the same RICE Scoring inputs as features."
       },
+      {
+        "label": "Solutions to score",
+        "entityTypeId": "solution",
+        "description": "Solutions scored on the same RICE Scoring inputs as features."
+      },
       {
         "label": "Needs to score",
         "entityTypeId": "need",
@@ -12374,6 +12595,10 @@ var UPG_FRAMEWORKS = [
           "type": "opportunity",
           "role": "scored_item"
         },
+        {
+          "type": "solution",
+          "role": "scored_item"
+        },
         {
           "type": "need",
           "role": "scored_item"
@@ -12456,6 +12681,44 @@ var UPG_FRAMEWORKS = [
             "description": "How much work is required to build and ship this, on the effort scale?"
           }
         ],
+        "solution": [
+          {
+            "property": "reach",
+            "type": "assessment",
+            "scale_id": "reach_5",
+            "required": true,
+            "scope": "framework",
+            "label": "Reach",
+            "description": "How many users will this impact per quarter?"
+          },
+          {
+            "property": "impact",
+            "type": "assessment",
+            "scale_id": "impact_5",
+            "required": true,
+            "scope": "framework",
+            "label": "Impact",
+            "description": "How much will this impact each user, on the impact scale?"
+          },
+          {
+            "property": "confidence",
+            "type": "assessment",
+            "scale_id": "confidence_5",
+            "required": true,
+            "scope": "framework",
+            "label": "Confidence",
+            "description": "How confident are you in the reach, impact, and effort estimates?"
+          },
+          {
+            "property": "effort",
+            "type": "assessment",
+            "scale_id": "effort_5",
+            "required": true,
+            "scope": "framework",
+            "label": "Effort",
+            "description": "How much work is required to build and ship this, on the effort scale?"
+          }
+        ],
         "need": [
           {
             "property": "reach",
@@ -12510,6 +12773,13 @@ var UPG_FRAMEWORKS = [
           "label": "RICE Score",
           "format": "number"
         },
+        {
+          "property": "rice_score",
+          "expression": "(reach * impact * confidence) / effort",
+          "entity_type": "solution",
+          "label": "RICE Score",
+          "format": "number"
+        },
         {
           "property": "rice_score",
           "expression": "(reach * impact * confidence) / effort",
@@ -12522,6 +12792,7 @@ var UPG_FRAMEWORKS = [
         "applies_to": [
           "feature",
           "opportunity",
+          "solution",
           "need"
         ],
         "inputs": [
@@ -16768,7 +17039,8 @@ var STANDARD_LABELS = {
   product: { alt_labels: ["offering", "app", "service", "platform"] },
   vision: { alt_labels: ["product vision", "north star vision", "long-term vision"] },
   mission: { alt_labels: ["mission statement", "purpose"] },
-  strategic_theme: { alt_labels: ["theme", "strategic pillar", "focus area"] },
+  strategic_theme: { alt_labels: ["focus area", "strategic focus area"] },
+  // N6: not 'theme'/'strategic pillar' (own types)
   initiative: { alt_labels: ["strategic initiative", "program initiative", "workstream"] },
   capability: { alt_labels: ["business capability", "organizational capability"] },
   value_stream: { alt_labels: ["value chain", "stream"] },
@@ -16830,7 +17102,8 @@ var STANDARD_LABELS = {
   fix: { alt_labels: ["bugfix", "patch", "remediation"] },
   roadmap: { alt_labels: ["product roadmap", "release plan", "timeline"] },
   roadmap_item: { alt_labels: ["roadmap entry", "planned item"] },
-  theme: { alt_labels: ["product theme", "bucket", "category"] },
+  roadmap_theme: { alt_labels: ["product theme", "roadmap theme"] },
+  // UPG-660: renamed from bare 'theme' (N6 lineage)
   // Engineering layer
   bounded_context: { alt_labels: ["context", "domain boundary", "module boundary"] },
   service: { alt_labels: ["microservice", "backend service", "api service"] },
@@ -17029,7 +17302,8 @@ var STANDARD_LABELS = {
   feedback_vote: { alt_labels: ["upvote", "vote", "user vote"] },
   user_advisory_board: { alt_labels: ["cab", "customer advisory board", "advisory council"] },
   beta_program: { alt_labels: ["beta", "early access", "preview program"] },
-  feedback_theme: { alt_labels: ["feedback cluster", "theme", "feedback category"] },
+  feedback_theme: { alt_labels: ["feedback cluster", "feedback category"] },
+  // N6: not bare 'theme'
   // Pricing & Packaging layer
   pricing_strategy: { alt_labels: ["pricing model", "monetization strategy"] },
   package: { alt_labels: ["product package", "bundle", "sku"] },
@@ -17533,9 +17807,9 @@ var PRODUCT_DELIVERY_PLAYBOOK = {
     ),
     seqStep(
       6,
-      "Themes & Changelog",
-      ["theme", "changelog"],
-      "Group releases into strategic themes. Maintain a changelog the team and customers can read together."
+      "Roadmap Themes & Changelog",
+      ["roadmap_theme", "changelog"],
+      "Group roadmap work into roadmap themes around the customer problem. Maintain a changelog the team and customers can read together."
     )
   ]
 };
@@ -18789,7 +19063,7 @@ var PRODUCT_SPEC_GUIDE = {
   // registered to product_spec but missing from the navigation order).
   // `changelog` lives here because it is a structural product-shipping
   // artefact; content domain references it only via cross-domain bridges.
-  creation_sequence: ["feature_area", "feature", "epic", "user_story", "acceptance_criterion", "task", "bug", "release", "roadmap", "roadmap_item", "theme", "changelog"],
+  creation_sequence: ["feature_area", "feature", "epic", "user_story", "acceptance_criterion", "task", "bug", "release", "roadmap", "roadmap_item", "roadmap_theme", "changelog"],
   patterns: [
     {
       name: "Feature Decomposition",
@@ -23214,7 +23488,7 @@ var UPG_REGIONS = [
         role: "leaf"
       },
       {
-        type: "theme",
+        type: "roadmap_theme",
         role: "container",
         notes: "semantic spanner, not containment"
       },
@@ -23250,10 +23524,10 @@ var UPG_REGIONS = [
       "user_story_verified_by_acceptance_criterion",
       "task_implements_user_story",
       "roadmap_contains_roadmap_item",
-      "roadmap_categorised_by_theme",
+      "roadmap_categorised_by_roadmap_theme",
       "roadmap_schedules_release",
       "release_documented_in_changelog",
-      "theme_spans_feature_area",
+      "roadmap_theme_spans_feature_area",
       "milestone_gates_release",
       "roadmap_item_references_feature",
       "feature_request_voted_on_by_feedback_vote"
@@ -24373,7 +24647,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.8.16";
+var UPG_VERSION = "0.9.1";
 var MARKDOWN_FORMAT_VERSION = "0.1";
 var UPG_TYPES = getTypes();
 var UPG_TYPES_SET = new Set(UPG_TYPES);
@@ -26576,6 +26850,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 = [];
@@ -26598,26 +26904,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");
@@ -26647,21 +26934,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();
@@ -27146,6 +27431,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;
@@ -27847,24 +28438,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,
@@ -28460,7 +29051,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;
@@ -28628,7 +29219,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"];
@@ -28713,8 +29304,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();
@@ -28743,7 +29334,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;
@@ -28757,12 +29348,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;
@@ -28806,11 +29397,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");
@@ -29771,7 +30362,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: {} }
   },
   {
@@ -30252,7 +30843,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: {
@@ -30260,7 +30851,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" },
@@ -30296,7 +30887,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)" },
@@ -30315,6 +30906,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.",
@@ -30501,6 +31144,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,
@@ -30559,9 +31204,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 {
@@ -30603,7 +31248,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;
   });
@@ -30620,15 +31265,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;
@@ -30639,16 +31284,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 {
@@ -30660,12 +31305,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;
@@ -30674,17 +31319,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 {
   }
@@ -30704,7 +31349,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,
@@ -30720,16 +31365,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(),
@@ -30744,13 +31389,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();