@unified-product-graph/mcp-server 0.8.6 → 0.8.8

package/dist/tools-manifest.json

@@ -1,7 +1,7 @@
 {
   "schema_version": "2",
   "package": "@unified-product-graph/mcp-server",
-  "package_version": "0.8.6",
+  "package_version": "0.8.8",
   "tool_count": 96,
   "domains": [
     "context",
@@ -308,7 +308,7 @@
         "create_node",
         "batch_create_edges"
       ],
-      "source": "src/tools/nodes.ts:1013",
+      "source": "src/tools/nodes.ts:1019",
       "symbol": "batchCreateNodes",
       "returns": "JSON: `{ created, edges_created, count, edges_count, warnings? }`.",
       "return_shape": "{ created, edges_created, count, edges_count, warnings? }",
@@ -347,7 +347,7 @@
       "see": [
         "delete_node"
       ],
-      "source": "src/tools/nodes.ts:1117",
+      "source": "src/tools/nodes.ts:1123",
       "symbol": "batchDeleteNodes",
       "returns": "JSON: `{ deleted, edges_removed, count }`.",
       "return_shape": "{ deleted, edges_removed, count }",
@@ -408,7 +408,7 @@
       "see": [
         "update_node"
       ],
-      "source": "src/tools/nodes.ts:1041",
+      "source": "src/tools/nodes.ts:1047",
       "symbol": "batchUpdateNodes",
       "returns": "JSON: `{ updated, count, warnings? }`. `warnings` carries\nlifecycle-phase hints aggregated across the batch.",
       "return_shape": "{ updated, count, warnings? }",
@@ -480,7 +480,7 @@
         "batch_create_nodes",
         "update_node"
       ],
-      "source": "src/tools/nodes.ts:727",
+      "source": "src/tools/nodes.ts:733",
       "symbol": "createNode",
       "returns": "JSON: `{ node, edge?, unknown_properties?, warning? }`. The `edge`\nfield is present only when `parent_id` was supplied and a canonical\nhierarchy edge could be inferred. `unknown_properties` and `warning` are\npresent when the caller passed properties not in the entity's schema.\nPass `strict: true` to reject unknown properties instead of\nwarning. For portfolio-scoped types the response shape is\n`{ node, portfolio_file, written_to, warning? }` where `node` is the\npersisted typed record.",
       "return_shape": "{ node, edge?, unknown_properties?, warning? }",
@@ -532,7 +532,7 @@
         "batch_delete_nodes",
         "validate_graph"
       ],
-      "source": "src/tools/nodes.ts:1362",
+      "source": "src/tools/nodes.ts:1368",
       "symbol": "deduplicateNodes",
       "returns": "JSON: with `dry_run: true`, `{ duplicates, total_groups,\ntotal_duplicate_nodes, dry_run, message }`. With `dry_run: false`,\n`{ merged: true, groups_merged, nodes_removed, edges_redirected,\nstrategy }`.",
       "return_notes": [
@@ -571,7 +571,7 @@
       "see": [
         "batch_delete_nodes"
       ],
-      "source": "src/tools/nodes.ts:987",
+      "source": "src/tools/nodes.ts:993",
       "symbol": "deleteNode",
       "returns": "JSON: `{ node, removed_edge_ids }`.",
       "return_shape": "{ node, removed_edge_ids }",
@@ -586,7 +586,11 @@
         "properties": {
           "node_id": {
             "type": "string",
-            "description": "The node ID"
+            "description": "The node ID. Alias: `id`."
+          },
+          "id": {
+            "type": "string",
+            "description": "Alias for `node_id`."
           },
           "compact_edges": {
             "type": "boolean",
@@ -598,7 +602,7 @@
         ]
       },
       "throws": [
-        "Returns a textError when `node_id` is missing or the node does not\nexist."
+        "Returns a textError when neither `node_id` nor `id` is provided, or\nthe node does not exist."
       ],
       "examples": [
         {
@@ -611,7 +615,7 @@
       "see": [
         "get_nodes"
       ],
-      "source": "src/tools/nodes.ts:207",
+      "source": "src/tools/nodes.ts:209",
       "symbol": "getNode",
       "returns": "JSON: the node object plus an `edges` array. `compact_edges: true`\nomits `source_title` and `target_title` (saves ~30% on edge-heavy nodes).",
       "return_notes": [
@@ -660,7 +664,7 @@
       "see": [
         "get_node"
       ],
-      "source": "src/tools/nodes.ts:251",
+      "source": "src/tools/nodes.ts:257",
       "symbol": "getNodes",
       "returns": "JSON array of node objects with edges. Missing IDs are silently\nskipped. May include a `degraded` block when the response was\nauto-trimmed to fit.",
       "return_notes": [
@@ -773,7 +777,7 @@
         "validate_graph",
         "list_type_migrations"
       ],
-      "source": "src/tools/nodes.ts:1308",
+      "source": "src/tools/nodes.ts:1314",
       "symbol": "migrateProperties",
       "returns": "JSON: `{ top_level_renames, lifted_properties, dropped_props,\ndropped_self_referential, dry_run }`.",
       "return_shape": "{ top_level_renames, lifted_properties, dropped_props, dropped_self_referential, dry_run }",
@@ -872,7 +876,7 @@
         "export_edges",
         "update_node"
       ],
-      "source": "src/tools/nodes.ts:1171",
+      "source": "src/tools/nodes.ts:1177",
       "symbol": "migrateType",
       "returns": "JSON: `{ migrated_nodes, migrated_edges, edge_renames,\ndropped_edges, unmapped_legacy_edges, defaults_applied, dry_run }`.\n`edge_renames` is `[{ id, from, to, flipped }]`; `dropped_edges` is\n`[{ id, from }]`; `unmapped_legacy_edges` is `[{ type, count }]`.\n`migrated_edges` is the total mutated count (renames + drops).",
       "return_shape": "{ migrated_nodes, migrated_edges, edge_renames, dropped_edges, unmapped_legacy_edges, defaults_applied, dry_run }",
@@ -956,7 +960,7 @@
         "list_nodes",
         "get_area_graph"
       ],
-      "source": "src/tools/nodes.ts:406",
+      "source": "src/tools/nodes.ts:412",
       "symbol": "query",
       "returns": "JSON: `{ nodes, edges, total_nodes, total_edges, _result_id,\ntruncated?, truncated_at_depth?, diff? }`. The `_result_id` is a cache\nhandle for `diff_from`; cache holds the last 20 results.",
       "return_shape": "{ nodes, edges, total_nodes, total_edges, _result_id, truncated?, truncated_at_depth?, diff? }",
@@ -1011,7 +1015,7 @@
         "list_nodes",
         "query"
       ],
-      "source": "src/tools/nodes.ts:355",
+      "source": "src/tools/nodes.ts:361",
       "symbol": "searchNodes",
       "returns": "JSON: `{ results: Array<{ id, type, title, status, tags,\nmatch_field, score }>, total, searched_fields }`.",
       "return_shape": "{ results: Array<{ id, type, title, status, tags, match_field, score }>, total, searched_fields }",
@@ -1078,7 +1082,7 @@
         "migrate_type",
         "batch_update_nodes"
       ],
-      "source": "src/tools/nodes.ts:880",
+      "source": "src/tools/nodes.ts:886",
       "symbol": "updateNode",
       "returns": "JSON: `{ node, warning?, unknown_properties?, unset? }`. `warning`\naggregates migration warnings and any unknown-property notice.\n`unknown_properties` lists property keys not in the entity's schema.\n`unset` lists the keys actually removed. Pass `strict: true` to reject\nunknown properties instead of warning.",
       "return_shape": "{ node, warning?, unknown_properties?, unset? }",
@@ -1758,7 +1762,7 @@
         "list_portfolio_cross_edges",
         "migrate_cross_edges"
       ],
-      "source": "src/tools/workspace.ts:403",
+      "source": "src/tools/workspace.ts:413",
       "symbol": "createCrossProductEdge",
       "returns": "JSON: `{ edge, portfolio_file }`.",
       "return_shape": "{ edge, portfolio_file }",
@@ -1810,7 +1814,7 @@
       "see": [
         "init_workspace"
       ],
-      "source": "src/tools/workspace.ts:283",
+      "source": "src/tools/workspace.ts:293",
       "symbol": "createProductTool",
       "returns": "JSON: `{ message, ...result }`. `result` carries `id`, `title`,\n`slug`, `file_path`, and the optional portfolio edge.",
       "return_shape": "{ message,...result }",
@@ -1839,7 +1843,7 @@
       "see": [
         "list_portfolios"
       ],
-      "source": "src/tools/workspace.ts:352",
+      "source": "src/tools/workspace.ts:362",
       "symbol": "getOrganization",
       "returns": "JSON: `{ organization: UPGOrganization | null, portfolio_file? }`.\nReturns `{ organization: null }` when no portfolio document exists yet.",
       "return_shape": "{ organization: UPGOrganization | null, portfolio_file? }",
@@ -1868,7 +1872,7 @@
       "see": [
         "init_workspace"
       ],
-      "source": "src/tools/workspace.ts:171",
+      "source": "src/tools/workspace.ts:181",
       "symbol": "getWorkspaceInfo",
       "returns": "JSON: `{ mode, workspace_path?, current_product?, current_file?,\nproducts }`. The shape depends on whether `.upg/workspace.json` exists.",
       "return_shape": "{ mode, workspace_path?, current_product?, current_file?, products }",
@@ -1908,7 +1912,7 @@
         "switch_product",
         "get_workspace_info"
       ],
-      "source": "src/tools/workspace.ts:247",
+      "source": "src/tools/workspace.ts:257",
       "symbol": "initWorkspaceTool",
       "returns": "JSON: `{ message, ...result }`. `result` carries the workspace\npath and the moved file's new location.",
       "return_shape": "{ message,...result }",
@@ -1961,7 +1965,7 @@
       "see": [
         "create_cross_product_edge"
       ],
-      "source": "src/tools/workspace.ts:542",
+      "source": "src/tools/workspace.ts:552",
       "symbol": "listPortfolioCrossEdges",
       "returns": "JSON: `{ cross_edges: UPGCrossEdge[], total, portfolio_file? }`.",
       "return_shape": "{ cross_edges: UPGCrossEdge[], total, portfolio_file? }",
@@ -1988,7 +1992,7 @@
         "create_cross_product_edge",
         "get_organization"
       ],
-      "source": "src/tools/workspace.ts:325",
+      "source": "src/tools/workspace.ts:335",
       "symbol": "listPortfolios",
       "returns": "JSON: `{ portfolios: Array<{ id, title, description?,\nparent_portfolio_id?, hierarchy_model?, products? }>, total }`.",
       "return_shape": "{ portfolios: Array<{ id, title, description?, parent_portfolio_id?, hierarchy_model?, products? }>, total }",
@@ -2031,7 +2035,7 @@
         "list_cross_edge_types",
         "init_workspace"
       ],
-      "source": "src/tools/workspace.ts:611",
+      "source": "src/tools/workspace.ts:621",
       "symbol": "migrateCrossEdges",
       "returns": "JSON: `{ migrated, skipped, dry_run, portfolio_file? }`.",
       "return_shape": "{ migrated, skipped, dry_run, portfolio_file? }",
@@ -2046,7 +2050,11 @@
         "properties": {
           "file": {
             "type": "string",
-            "description": "Path to the .upg file (relative, absolute, or a bare product name in workspace mode)."
+            "description": "Path to the .upg file (relative, absolute, or a bare product name in workspace mode). Alias: `product`."
+          },
+          "product": {
+            "type": "string",
+            "description": "Alias for `file`."
           }
         },
         "required": [
@@ -2054,7 +2062,7 @@
         ]
       },
       "throws": [
-        "Returns a textError when the file cannot be resolved or the load\nfails (file watcher / parse error)."
+        "Returns a textError when neither `file` nor `product` is provided, or\nthe file cannot be resolved, or the load fails (file watcher / parse error)."
       ],
       "examples": [],
       "warnings": [
@@ -2065,7 +2073,7 @@
         "list_local_products",
         "init_workspace"
       ],
-      "source": "src/tools/workspace.ts:116",
+      "source": "src/tools/workspace.ts:118",
       "symbol": "switchProduct",
       "returns": "JSON: `{ message, file, product: { title, stage }, entities }`.",
       "return_shape": "{ message, file, product: { title, stage }, entities }",
@@ -2145,17 +2153,20 @@
         ]
       },
       "throws": [
-        "textError on a missing/unknown framework_id."
+        "textError on a missing/unknown framework_id, or when no requested\nentity resolves (no dangling exercise is left behind)."
       ],
       "examples": [],
       "warnings": [],
       "see": [
         "score_entity"
       ],
-      "source": "src/tools/frameworks.ts:22",
+      "source": "src/tools/frameworks.ts:25",
       "symbol": "applyFramework",
-      "returns": "JSON: `{ exercise_id, exercise, included: [{ edge_id, entity_id }], warnings }`.",
-      "return_shape": "{ exercise_id, exercise, included: [{ edge_id, entity_id }], warnings }",
+      "returns": "JSON: `{ exercise_id, exercise, included: [{ edge_id, entity_id, edge_type }], warnings }`\n(the shared cross-surface envelope; identical to CLI `apply --json`).",
+      "return_shape": "{ exercise_id, exercise, included: [{ edge_id, entity_id, edge_type }], warnings }",
+      "return_notes": [
+        "(the shared cross-surface envelope; identical to CLI `apply --json`)."
+      ],
       "atomicity": "atomic."
     },
     {
@@ -2191,7 +2202,7 @@
         "inspect",
         "validate_graph"
       ],
-      "source": "src/tools/spec.ts:1440",
+      "source": "src/tools/spec.ts:1471",
       "symbol": "getAntiPattern",
       "returns": "JSON: `UPGCuratedAntiPattern`",
       "return_notes": [
@@ -2320,7 +2331,7 @@
         "list_domains",
         "get_domain_guide"
       ],
-      "source": "src/tools/spec.ts:1896",
+      "source": "src/tools/spec.ts:1927",
       "symbol": "getDomainRing",
       "returns": "JSON: the full `UPGDomainRing` record.",
       "return_notes": [
@@ -2361,7 +2372,7 @@
         "list_edge_migrations",
         "rename_edge_type"
       ],
-      "source": "src/tools/spec.ts:892",
+      "source": "src/tools/spec.ts:923",
       "symbol": "getEdgeType",
       "returns": "JSON: `{ type, forward_verb, reverse_verb, classification, source_type, target_type }`",
       "return_shape": "{ type, forward_verb, reverse_verb, classification, source_type, target_type }",
@@ -2400,7 +2411,7 @@
         "get_entity_schema",
         "list_type_migrations"
       ],
-      "source": "src/tools/spec.ts:1355",
+      "source": "src/tools/spec.ts:1386",
       "symbol": "getEntityMeta",
       "returns": "JSON: `EntityTypeMeta & { domain_id: string | null }`",
       "return_notes": [
@@ -2417,7 +2428,11 @@
         "properties": {
           "id": {
             "type": "string",
-            "description": "Framework id (kebab-case)."
+            "description": "Framework id (kebab-case). Alias: `framework_id`."
+          },
+          "framework_id": {
+            "type": "string",
+            "description": "Alias for `id` (matches the key used by apply_framework / prioritise)."
           }
         },
         "required": [
@@ -2425,7 +2440,7 @@
         ]
       },
       "throws": [
-        "textError when `id` is missing or unknown."
+        "textError when neither `id` nor `framework_id` is provided, or the\nid is unknown."
       ],
       "examples": [
         {
@@ -2441,7 +2456,7 @@
         "get_playbook",
         "get_approach"
       ],
-      "source": "src/tools/spec.ts:829",
+      "source": "src/tools/spec.ts:852",
       "symbol": "getFramework",
       "returns": "JSON: the full `UPGFramework` record.",
       "return_notes": [
@@ -2482,7 +2497,7 @@
         "get_framework",
         "list_entity_types"
       ],
-      "source": "src/tools/spec.ts:1149",
+      "source": "src/tools/spec.ts:1180",
       "symbol": "getLensTool",
       "returns": "JSON: `{ ...UPGLens, visible_types: string[] }`",
       "return_shape": "{...UPGLens, visible_types: string[] }",
@@ -2518,7 +2533,7 @@
         "get_entity_meta",
         "get_entity_schema"
       ],
-      "source": "src/tools/spec.ts:1766",
+      "source": "src/tools/spec.ts:1797",
       "symbol": "getLifecycle",
       "returns": "JSON: the full `UPGLifecycle` record, or a descriptive message.",
       "return_notes": [
@@ -2600,7 +2615,7 @@
         "get_playbook",
         "list_lenses"
       ],
-      "source": "src/tools/spec.ts:951",
+      "source": "src/tools/spec.ts:982",
       "symbol": "getRegion",
       "returns": "JSON: the full `UPGRegion` record.",
       "return_notes": [
@@ -2641,7 +2656,7 @@
         "get_entity_meta",
         "list_entity_types"
       ],
-      "source": "src/tools/spec.ts:973",
+      "source": "src/tools/spec.ts:1004",
       "symbol": "getRegionForEntity",
       "returns": "JSON: the full `UPGRegion` record.",
       "return_notes": [
@@ -2672,7 +2687,7 @@
         "list_scales",
         "get_entity_schema"
       ],
-      "source": "src/tools/spec.ts:1812",
+      "source": "src/tools/spec.ts:1843",
       "symbol": "getScale",
       "returns": "JSON: the full `UPGScaleDefinition` record including all points.",
       "return_notes": [
@@ -2703,7 +2718,7 @@
         "list_edge_types",
         "list_regions"
       ],
-      "source": "src/tools/spec.ts:1001",
+      "source": "src/tools/spec.ts:1032",
       "symbol": "getSpecVersion",
       "returns": "JSON: `{ upg_version, markdown_format_version, entity_count, edge_count, domain_count, region_count }`",
       "return_shape": "{ upg_version, markdown_format_version, entity_count, edge_count, domain_count, region_count }",
@@ -2749,7 +2764,7 @@
         "get_entity_meta",
         "list_frameworks"
       ],
-      "source": "src/tools/spec.ts:1217",
+      "source": "src/tools/spec.ts:1248",
       "symbol": "getTypeLabel",
       "returns": "JSON: `{ ...UPGTypeLabel, resolved_label: string }`",
       "return_shape": "{...UPGTypeLabel, resolved_label: string }",
@@ -2788,7 +2803,7 @@
         "get_entity_meta",
         "create_node"
       ],
-      "source": "src/tools/spec.ts:1247",
+      "source": "src/tools/spec.ts:1278",
       "symbol": "getValidChildrenTool",
       "returns": "JSON: `{ parent_type, valid_children: string[] }`",
       "return_shape": "{ parent_type, valid_children: string[] }",
@@ -2891,7 +2906,7 @@
         "inspect",
         "get_domain_guide"
       ],
-      "source": "src/tools/spec.ts:1398",
+      "source": "src/tools/spec.ts:1429",
       "symbol": "listAntiPatterns",
       "returns": "JSON: `{ total, count, next_cursor?, anti_patterns: UPGCuratedAntiPattern[] }`",
       "return_shape": "{ total, count, next_cursor?, anti_patterns: UPGCuratedAntiPattern[] }",
@@ -2992,7 +3007,7 @@
         "list_domains",
         "list_anti_patterns"
       ],
-      "source": "src/tools/spec.ts:1487",
+      "source": "src/tools/spec.ts:1518",
       "symbol": "listBenchmarks",
       "returns": "JSON: `{ kind, total, count, benchmarks: ... }`",
       "return_shape": "{ kind, total, count, benchmarks:... }",
@@ -3020,7 +3035,7 @@
         "list_portfolio_cross_edges",
         "migrate_cross_edges"
       ],
-      "source": "src/tools/spec.ts:1087",
+      "source": "src/tools/spec.ts:1118",
       "symbol": "listCrossEdgeTypes",
       "returns": "JSON: `{ count, types: readonly UPGCrossEdgeType[] }`",
       "return_shape": "{ count, types: readonly UPGCrossEdgeType[] }",
@@ -3048,7 +3063,7 @@
         "list_domains",
         "get_domain_guide"
       ],
-      "source": "src/tools/spec.ts:1875",
+      "source": "src/tools/spec.ts:1906",
       "symbol": "listDomainRings",
       "returns": "JSON: `{ rings: UPGDomainRing[], total: number }`",
       "return_shape": "{ rings: UPGDomainRing[], total: number }",
@@ -3118,7 +3133,7 @@
         "list_edge_types",
         "validate_graph"
       ],
-      "source": "src/tools/spec.ts:1659",
+      "source": "src/tools/spec.ts:1690",
       "symbol": "listEdgeMigrations",
       "returns": "JSON: `{ migrations: [{ kind, from, to?, since }], total: number }`",
       "return_shape": "{ migrations: [{ kind, from, to?, since }], total: number }",
@@ -3157,7 +3172,7 @@
         "list_edge_migrations",
         "create_edge"
       ],
-      "source": "src/tools/spec.ts:873",
+      "source": "src/tools/spec.ts:904",
       "symbol": "listEdgeTypes",
       "returns": "JSON: `{ count, edges: Array<{ type, forward_verb, reverse_verb, classification, source_type, target_type }> }`",
       "return_shape": "{ count, edges: Array<{ type, forward_verb, reverse_verb, classification, source_type, target_type }> }",
@@ -3215,7 +3230,7 @@
         "list_type_migrations",
         "list_domains"
       ],
-      "source": "src/tools/spec.ts:1299",
+      "source": "src/tools/spec.ts:1330",
       "symbol": "listEntityTypes",
       "returns": "JSON: `{ total, count, next_cursor?, types: Array<EntityTypeMeta & { domain_id: string | null }> }`",
       "return_shape": "{ total, count, next_cursor?, types: Array<EntityTypeMeta & { domain_id: string | null }> }",
@@ -3242,7 +3257,7 @@
         "list_frameworks",
         "list_framework_structure_patterns"
       ],
-      "source": "src/tools/spec.ts:1831",
+      "source": "src/tools/spec.ts:1862",
       "symbol": "listFrameworkCategories",
       "returns": "JSON: `{ categories: string[], total: number }`",
       "return_shape": "{ categories: string[], total: number }",
@@ -3270,7 +3285,7 @@
         "list_framework_categories",
         "get_framework"
       ],
-      "source": "src/tools/spec.ts:1852",
+      "source": "src/tools/spec.ts:1883",
       "symbol": "listFrameworkStructurePatterns",
       "returns": "JSON: `{ patterns: string[], total: number }`",
       "return_shape": "{ patterns: string[], total: number }",
@@ -3278,7 +3293,7 @@
     },
     {
       "name": "list_frameworks",
-      "description": "List the canonical `UPGFramework` definitions; the 34 curated, famous product frameworks that anchor the public catalog (spanning strategy, discovery, prioritisation, design, growth, engineering, and reflection classics). Paginated (default 50, max 200). Cursor is opaque: pass `next_cursor` from a previous response. Optional `category` is exact-match against `UPGFramework.category` and applies before pagination.",
+      "description": "List the canonical `UPGFramework` definitions: the curated, famous product frameworks that anchor the public catalog (spanning strategy, discovery, prioritisation, design, growth, engineering, and reflection classics). Returns a lightweight summary per framework (id, name, category, description, tags, approach_ids, structure_pattern); call `get_framework(id)` for the full record. Paginated (default 50, max 200). Cursor is opaque: pass `next_cursor` from a previous response. Optional `category` is exact-match against `UPGFramework.category` and applies before pagination.",
       "domain": "spec",
       "inputSchema": {
         "type": "object",
@@ -3313,10 +3328,10 @@
         "prioritise",
         "list_approaches"
       ],
-      "source": "src/tools/spec.ts:793",
+      "source": "src/tools/spec.ts:798",
       "symbol": "listFrameworks",
-      "returns": "JSON: `{ total, count, next_cursor?, frameworks: UPGFramework[] }`",
-      "return_shape": "{ total, count, next_cursor?, frameworks: UPGFramework[] }",
+      "returns": "JSON: `{ total, count, next_cursor?, frameworks: Array<{ id, name, category, description, tags, approach_ids, structure_pattern }> }`",
+      "return_shape": "{ total, count, next_cursor?, frameworks: Array<{ id, name, category, description, tags, approach_ids, structure_pattern }> }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -3342,7 +3357,7 @@
         "list_playbooks",
         "list_frameworks"
       ],
-      "source": "src/tools/spec.ts:1116",
+      "source": "src/tools/spec.ts:1147",
       "symbol": "listLenses",
       "returns": "JSON: `{ count, lenses: Array<{ id, name, description, icon, audience, perspective, framework_id?, playbook_id?, visible_domain_count, intelligence_prompt_count }> }`",
       "return_shape": "{ count, lenses: Array<{ id, name, description, icon, audience, perspective, framework_id?, playbook_id?, visible_domain_count, intelligence_prompt_count }> }",
@@ -3379,7 +3394,7 @@
         "list_entity_types",
         "get_entity_meta"
       ],
-      "source": "src/tools/spec.ts:1724",
+      "source": "src/tools/spec.ts:1755",
       "symbol": "listLifecycles",
       "returns": "JSON: `{ lifecycles, total, free_types: string[], planned_types: string[] }`",
       "return_shape": "{ lifecycles, total, free_types: string[], planned_types: string[] }",
@@ -3450,7 +3465,7 @@
         "list_domain_rings",
         "create_product"
       ],
-      "source": "src/tools/spec.ts:1595",
+      "source": "src/tools/spec.ts:1626",
       "symbol": "listProductStages",
       "returns": "JSON: `{ count, stages: readonly UPGProductStage[] }`",
       "return_shape": "{ count, stages: readonly UPGProductStage[] }",
@@ -3479,7 +3494,7 @@
         "list_domains",
         "list_playbooks"
       ],
-      "source": "src/tools/spec.ts:919",
+      "source": "src/tools/spec.ts:950",
       "symbol": "listRegions",
       "returns": "JSON: `{ count, regions: Array<{ id, label, order, shape, mental_model, anchor_type, composes_atomic_domains, entity_count, intra_edge_count, boundary_edge_count }> }`",
       "return_shape": "{ count, regions: Array<{ id, label, order, shape, mental_model, anchor_type, composes_atomic_domains, entity_count, intra_edge_count, boundary_edge_count }> }",
@@ -3506,7 +3521,7 @@
         "get_scale",
         "get_entity_schema"
       ],
-      "source": "src/tools/spec.ts:1797",
+      "source": "src/tools/spec.ts:1828",
       "symbol": "listScales",
       "returns": "JSON: `{ scales: UPGScaleDefinition[], total: number }`",
       "return_shape": "{ scales: UPGScaleDefinition[], total: number }",
@@ -3535,7 +3550,7 @@
         "migrate_type",
         "validate_graph"
       ],
-      "source": "src/tools/spec.ts:1696",
+      "source": "src/tools/spec.ts:1727",
       "symbol": "listSplitMigrations",
       "returns": "JSON: `{ splits: [...], total: number }`",
       "return_shape": "{ splits: [...], total: number }",
@@ -3572,7 +3587,7 @@
         "list_entity_types",
         "get_entity_meta"
       ],
-      "source": "src/tools/spec.ts:1182",
+      "source": "src/tools/spec.ts:1213",
       "symbol": "listTypeLabels",
       "returns": "JSON: `{ total, count, next_cursor?, labels: UPGTypeLabel[] }`",
       "return_shape": "{ total, count, next_cursor?, labels: UPGTypeLabel[] }",
@@ -3608,7 +3623,7 @@
         "validate_graph",
         "list_entity_types"
       ],
-      "source": "src/tools/spec.ts:1628",
+      "source": "src/tools/spec.ts:1659",
       "symbol": "listTypeMigrations",
       "returns": "JSON: `{ migrations: [{ from, to, since }], total: number }`",
       "return_shape": "{ migrations: [{ from, to, since }], total: number }",
@@ -3794,7 +3809,7 @@
         "create_edge",
         "trace"
       ],
-      "source": "src/tools/spec.ts:1055",
+      "source": "src/tools/spec.ts:1086",
       "symbol": "resolveEdgeForPair",
       "returns": "JSON: `{ source_type, target_type, edge_type: string | null,\nanchor_hint?, alternate_anchors?, adjacent_edges? }`",
       "return_shape": "{ source_type, target_type, edge_type: string | null, anchor_hint?, alternate_anchors?, adjacent_edges? }",
@@ -3838,7 +3853,7 @@
       "see": [
         "apply_framework"
       ],
-      "source": "src/tools/frameworks.ts:63",
+      "source": "src/tools/frameworks.ts:55",
       "symbol": "scoreEntity",
       "returns": "JSON: `{ edge, warnings }`.",
       "return_shape": "{ edge, warnings }",
@@ -4085,7 +4100,7 @@
         "get_anti_pattern",
         "inspect"
       ],
-      "source": "src/tools/validation.ts:906",
+      "source": "src/tools/validation.ts:938",
       "symbol": "getAntiPatternViolationsFor",
       "returns": "JSON: `{ entity_id, type, violations: [...] }`.",
       "return_shape": "{ entity_id, type, violations: [...] }",
@@ -4189,7 +4204,7 @@
         }
       ],
       "warnings": [
-        "Top-level `valid` is true ONLY when both drift is empty AND no\nanti-pattern violations fired. Set `skip_anti_patterns: true` for a\npure spec-shape check; `skip_drift: true` for catalog-only."
+        "`valid` is true ONLY when both drift is empty AND no anti-pattern\nviolations fired — it conflates structure and product-health. For a pure\nspec-conformance check read `structurally_valid` (or set\n`skip_anti_patterns: true`, which makes `valid` track structure alone).\n`skip_drift: true` gives a catalog-only run and omits `structurally_valid`."
       ],
       "see": [
         "migrate_type",
@@ -4201,13 +4216,14 @@
         "list_edge_migrations",
         "inspect"
       ],
-      "source": "src/tools/validation.ts:257",
+      "source": "src/tools/validation.ts:267",
       "symbol": "validateGraph",
-      "returns": "JSON: `{ valid, summary, entity_drift?, edge_drift?,\nproperty_drift?, top_level_drift?, lifecycle_drift?, self_referential?,\nanti_pattern_violations?, notes?, _hash }`. Per-class drift arrays appear\nonly when the requested `scope` includes that class. Each array is capped\nat `limit` (default 100).",
-      "return_shape": "{ valid, summary, entity_drift?, edge_drift?, property_drift?, top_level_drift?, lifecycle_drift?, self_referential?, anti_pattern_violations?, notes?, _hash }",
+      "returns": "JSON: `{ valid, structurally_valid?, summary, entity_drift?,\nedge_drift?, property_drift?, top_level_drift?, lifecycle_drift?,\nself_referential?, anti_pattern_violations?, notes?, _hash }`. Per-class\ndrift arrays appear only when the requested `scope` includes that class.\nEach array is capped at `limit` (default 100). `structurally_valid` is\nomitted when `skip_drift: true`.",
+      "return_shape": "{ valid, structurally_valid?, summary, entity_drift?, edge_drift?, property_drift?, top_level_drift?, lifecycle_drift?, self_referential?, anti_pattern_violations?, notes?, _hash }",
       "return_notes": [
         "Per-class drift arrays appear only when the requested `scope` includes that class.",
-        "Each array is capped at `limit` (default 100)."
+        "Each array is capped at `limit` (default 100).",
+        "`structurally_valid` is omitted when `skip_drift: true`."
       ],
       "atomicity": "atomic (read-only)"
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unified-product-graph/mcp-server",
-  "version": "0.8.6",
+  "version": "0.8.8",
   "description": "Local MCP server for .upg files. Read and write product knowledge graphs offline.",
   "license": "MIT",
   "author": "The Product Creator <hello@theproductcreator.com>",
@@ -45,6 +45,7 @@
     "generate-tools:check": "tsx scripts/generate-tool-reference.ts --check",
     "test": "vitest run",
     "test:watch": "vitest",
+    "smoke": "node scripts/upg-smoke.mjs --file test-fixtures/sample.upg",
     "lint": "eslint src/",
     "type-check": "tsc --noEmit",
     "prepublishOnly": "npm run build"