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

package/dist/tools-manifest.json

@@ -1,8 +1,8 @@
 {
   "schema_version": "2",
   "package": "@unified-product-graph/mcp-server",
-  "package_version": "0.7.4",
-  "tool_count": 93,
+  "package_version": "0.7.6",
+  "tool_count": 94,
   "domains": [
     "context",
     "nodes",
@@ -12,9 +12,7 @@
     "schema",
     "spec",
     "sync",
-    "validation",
-    "migrations",
-    "skills"
+    "validation"
   ],
   "tools": [
     {
@@ -42,9 +40,13 @@
       "see": [
         "get_product_context"
       ],
-      "source": "src/tools/context.ts:240",
+      "source": "src/tools/context.ts:241",
       "symbol": "getGraphDigest",
       "returns": "JSON object: `{ counts, health, chains, coverage, lifecycle,\nlens, lens_digest, _hash }`. ~500 tokens vs ~5-8K for equivalent manual\nfetches.",
+      "return_shape": "{ counts, health, chains, coverage, lifecycle, lens, lens_digest, _hash }",
+      "return_notes": [
+        "~500 tokens vs ~5-8K for equivalent manual fetches."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -77,9 +79,12 @@
         "get_graph_digest",
         "get_entity_schema"
       ],
-      "source": "src/tools/context.ts:55",
+      "source": "src/tools/context.ts:56",
       "symbol": "getProductContext",
       "returns": "Markdown string with product header, lens preamble, entity counts,\nactive-domain creation sequences, and `_hash` footer for `if_changed_since`\ndiffing.",
+      "return_notes": [
+        "Markdown string with product header, lens preamble, entity counts, active-domain creation sequences, and `_hash` footer for `if_changed_since` diffing."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -102,9 +107,41 @@
       "see": [
         "update_session_context"
       ],
-      "source": "src/tools/context.ts:295",
+      "source": "src/tools/context.ts:417",
       "symbol": "getSessionContext",
       "returns": "JSON: `{ lens, skills_invoked, recommendations_given,\nrecommendations_to_avoid, focus_area, custom, skills_count, last_skill,\nlast_recommendation }`. `recommendations_to_avoid` is the deduped list of\nevery recommendation given this session; runners should filter their\nnext recommendation against this array rather than re-deriving the\ndedup rule from prose.",
+      "return_shape": "{ lens, skills_invoked, recommendations_given, recommendations_to_avoid, focus_area, custom, skills_count, last_skill, last_recommendation }",
+      "return_notes": [
+        "`recommendations_to_avoid` is the deduped list of every recommendation given this session; runners should filter their next recommendation against this array rather than re-deriving the dedup rule from prose."
+      ],
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "start",
+      "description": "Zero-state on-ramp: \"there is nothing here yet, where do I begin?\". Reads the live graph and, for an empty or barely-started graph, recommends the first canonical playbook (from UPG_PLAYBOOKS) plus the exact create_node call for its anchor entity. Established graphs are routed to plan / inspect / get_graph_digest instead. Takes no arguments.",
+      "domain": "context",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      },
+      "throws": [],
+      "examples": [
+        "// Input (empty graph):\n{}\n// Output (truncated):\n{\n  \"graph_state\": \"empty\",\n  \"node_count\": 0,\n  \"recommended_playbook\": { \"id\": \"playbook:users-needs\", \"name\": \"Users & Needs\", \"target_anchor_entity\": \"persona\" },\n  \"first_action\": { \"tool\": \"create_node\", \"args\": { \"type\": \"persona\", \"title\": \"<your first persona>\" } },\n  \"recommendation\": \"Your graph is empty. Begin with the \\\"Users & Needs\\\" playbook: create your first persona.\"\n}"
+      ],
+      "warnings": [],
+      "see": [
+        "plan",
+        "get_playbook",
+        "list_playbooks",
+        "get_graph_digest"
+      ],
+      "source": "src/tools/context.ts:326",
+      "symbol": "start",
+      "returns": "JSON: `{ graph_state: \"empty\" | \"young\" | \"established\", product,\nnode_count, recommended_playbook?, first_action?, recommendation,\nnext_tools }`. `recommended_playbook` and `first_action` are present only\nfor empty/young graphs.",
+      "return_shape": "{ graph_state: \"empty\" | \"young\" | \"established\", product, node_count, recommended_playbook?, first_action?, recommendation, next_tools }",
+      "return_notes": [
+        "`recommended_playbook` and `first_action` are present only for empty/young graphs."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -158,9 +195,13 @@
       "see": [
         "get_session_context"
       ],
-      "source": "src/tools/context.ts:336",
+      "source": "src/tools/context.ts:458",
       "symbol": "updateSessionContext",
       "returns": "JSON: `{ updated: true, session: SessionContext }` reflecting the\nnew state.",
+      "return_shape": "{ updated: true, session: SessionContext }",
+      "return_notes": [
+        "reflecting the new state."
+      ],
       "atomicity": "non-atomic. Session mutates in-memory immediately; lens\npersistence flushes the .upg file as a separate side-effect that may\nsucceed or fail independently of the session update."
     },
     {
@@ -263,9 +304,10 @@
         "create_node",
         "batch_create_edges"
       ],
-      "source": "src/tools/nodes.ts:958",
+      "source": "src/tools/nodes.ts:991",
       "symbol": "batchCreateNodes",
       "returns": "JSON: `{ created, edges_created, count, edges_count, warnings? }`.",
+      "return_shape": "{ created, edges_created, count, edges_count, warnings? }",
       "atomicity": "atomic-with-rollback. Full validation pass first, then commit."
     },
     {
@@ -301,9 +343,10 @@
       "see": [
         "delete_node"
       ],
-      "source": "src/tools/nodes.ts:1062",
+      "source": "src/tools/nodes.ts:1095",
       "symbol": "batchDeleteNodes",
       "returns": "JSON: `{ deleted, edges_removed, count }`.",
+      "return_shape": "{ deleted, edges_removed, count }",
       "atomicity": "atomic. Validation pass rejects the entire batch before any\nmutation lands."
     },
     {
@@ -361,9 +404,13 @@
       "see": [
         "update_node"
       ],
-      "source": "src/tools/nodes.ts:986",
+      "source": "src/tools/nodes.ts:1019",
       "symbol": "batchUpdateNodes",
       "returns": "JSON: `{ updated, count, warnings? }`. `warnings` carries\nlifecycle-phase hints aggregated across the batch.",
+      "return_shape": "{ updated, count, warnings? }",
+      "return_notes": [
+        "`warnings` carries lifecycle-phase hints aggregated across the batch."
+      ],
       "atomicity": "atomic. Validation pass rejects the entire batch before any\nmutation lands."
     },
     {
@@ -429,9 +476,16 @@
         "batch_create_nodes",
         "update_node"
       ],
-      "source": "src/tools/nodes.ts:702",
+      "source": "src/tools/nodes.ts:727",
       "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\n. Pass `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.",
+      "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? }",
+      "return_notes": [
+        "The `edge` field is present only when `parent_id` was supplied and a canonical hierarchy edge could be inferred.",
+        "`unknown_properties` and `warning` are present when the caller passed properties not in the entity's schema.",
+        "Pass `strict: true` to reject unknown properties instead of warning.",
+        "For portfolio-scoped types the response shape is `{ node, portfolio_file, written_to, warning? }` where `node` is the persisted typed record."
+      ],
       "atomicity": "atomic-with-rollback. Schema validation runs before mutation."
     },
     {
@@ -474,9 +528,13 @@
         "batch_delete_nodes",
         "validate_graph"
       ],
-      "source": "src/tools/nodes.ts:1307",
+      "source": "src/tools/nodes.ts:1340",
       "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": [
+        "JSON: with `dry_run: true`, `{ duplicates, total_groups, total_duplicate_nodes, dry_run, message }`.",
+        "With `dry_run: false`, `{ merged: true, groups_merged, nodes_removed, edges_redirected, strategy }`."
+      ],
       "atomicity": "non-atomic. Merges are applied group-by-group; a mid-flight\nerror leaves earlier groups merged."
     },
     {
@@ -509,9 +567,10 @@
       "see": [
         "batch_delete_nodes"
       ],
-      "source": "src/tools/nodes.ts:932",
+      "source": "src/tools/nodes.ts:965",
       "symbol": "deleteNode",
       "returns": "JSON: `{ node, removed_edge_ids }`.",
+      "return_shape": "{ node, removed_edge_ids }",
       "atomicity": "atomic. Node + cascading edges removed in one mutation."
     },
     {
@@ -548,9 +607,13 @@
       "see": [
         "get_nodes"
       ],
-      "source": "src/tools/nodes.ts:206",
+      "source": "src/tools/nodes.ts:207",
       "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": [
+        "JSON: the node object plus an `edges` array.",
+        "`compact_edges: true` omits `source_title` and `target_title` (saves ~30% on edge-heavy nodes)."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -593,9 +656,14 @@
       "see": [
         "get_node"
       ],
-      "source": "src/tools/nodes.ts:250",
+      "source": "src/tools/nodes.ts:251",
       "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": [
+        "JSON array of node objects with edges.",
+        "Missing IDs are silently skipped.",
+        "May include a `degraded` block when the response was auto-trimmed to fit."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -662,9 +730,14 @@
         "search_nodes",
         "query"
       ],
-      "source": "src/tools/nodes.ts:106",
+      "source": "src/tools/nodes.ts:107",
       "symbol": "listNodes",
       "returns": "JSON: `{ nodes, total, offset, limit, _hash }`. With\n`count_only: true`, returns `{ total, _hash }` only. May include a\n`degraded` block when the response was auto-trimmed to fit.",
+      "return_shape": "{ nodes, total, offset, limit, _hash }",
+      "return_notes": [
+        "With `count_only: true`, returns `{ total, _hash }` only.",
+        "May include a `degraded` block when the response was auto-trimmed to fit."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -696,11 +769,64 @@
         "validate_graph",
         "list_type_migrations"
       ],
-      "source": "src/tools/nodes.ts:1253",
+      "source": "src/tools/nodes.ts:1286",
       "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 }",
       "atomicity": "non-atomic. Mutations are applied node-by-node; a mid-flight\nerror may leave the graph partially migrated."
     },
+    {
+      "name": "migrate_status",
+      "description": "Apply `UPG_STATUS_MIGRATIONS` graph-wide: rewrite legacy lifecycle status values to canonical phase ids. Auto-mode (no filters) selects nodes whose current status is invalid against the entity type's lifecycle and has a registered replacement (the same invariant that drives `validate_graph` lifecycle_drift). Surgical mode (`from_status` + `to_status`) overrides the registry and rewrites every (entity_type?, from_status) match. Nodes with invalid statuses but no registered replacement surface under `skipped_no_migration`. Default `dry_run=true`; pass `dry_run=false` to commit.",
+      "domain": "nodes",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "entity_type": {
+            "type": "string",
+            "description": "Optional. Restrict the rewrite to nodes of this canonical entity type (e.g. \"service\", \"feature\")."
+          },
+          "from_status": {
+            "type": "string",
+            "description": "Optional. Restrict the rewrite to nodes whose current status equals this exact value. When provided, `to_status` is required and the registry is bypassed."
+          },
+          "to_status": {
+            "type": "string",
+            "description": "Required when `from_status` is provided. The canonical phase id to write."
+          },
+          "dry_run": {
+            "type": "boolean",
+            "description": "Preview changes without applying (default true). Pass false to commit."
+          }
+        }
+      },
+      "throws": [
+        "Returns a textError when `from_status` is provided without\n`to_status`, or when `entity_type` is provided but isn't a string."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"migrated_nodes\": 0,\n  \"skipped_no_migration\": 0,\n  \"changes\": [],\n  \"dry_run\": true\n}"
+        }
+      ],
+      "warnings": [
+        "Default is `dry_run: true`. Pass `dry_run: false` to commit.\nIdempotent on retry; re-running after a successful commit reports\nzero changes (canonical statuses pass the validity check)."
+      ],
+      "see": [
+        "migrate_type",
+        "migrate_properties",
+        "validate_graph",
+        "list_lifecycles"
+      ],
+      "source": "src/tools/migrations.ts:64",
+      "symbol": "migrateStatus",
+      "returns": "JSON: `MigrateStatusResult`.",
+      "return_notes": [
+        "JSON: `MigrateStatusResult`."
+      ],
+      "atomicity": "per-node. Status writes go through `store.updateNode`\none at a time. Dry-run is read-only."
+    },
     {
       "name": "migrate_type",
       "description": "Migrate every entity of one type to another, applying defaults from `UPG_MIGRATIONS`. Three passes commit as one write: (1) node rename, (2) edges through `UPG_EDGE_MIGRATIONS` (catalog-aware renames, direction flips, drops; endpoint guards check post-migration types; uncatalogued edges surface as `unmapped_legacy_edges`), (3) every node through `UPG_PROPERTY_MIGRATIONS` (top-level renames, lifts, drops, self-referential cleanup). Type-specific property rules see the post-rename type.",
@@ -742,9 +868,14 @@
         "export_edges",
         "update_node"
       ],
-      "source": "src/tools/nodes.ts:1116",
+      "source": "src/tools/nodes.ts:1149",
       "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 }",
+      "return_notes": [
+        "`edge_renames` is `[{ id, from, to, flipped }]`; `dropped_edges` is `[{ id, from }]`; `unmapped_legacy_edges` is `[{ type, count }]`.",
+        "`migrated_edges` is the total mutated count (renames + drops)."
+      ],
       "atomicity": "atomic. Single store-level migration call commits or fails as\none mutation. Note: full graph canonicalisation runs as a side-effect of\nany node-type migration, so unrelated legacy edges may also be retargeted."
     },
     {
@@ -821,9 +952,13 @@
         "list_nodes",
         "get_area_graph"
       ],
-      "source": "src/tools/nodes.ts:405",
+      "source": "src/tools/nodes.ts:406",
       "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? }",
+      "return_notes": [
+        "The `_result_id` is a cache handle for `diff_from`; cache holds the last 20 results."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -872,9 +1007,10 @@
         "list_nodes",
         "query"
       ],
-      "source": "src/tools/nodes.ts:354",
+      "source": "src/tools/nodes.ts:355",
       "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 }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -931,9 +1067,15 @@
         "migrate_type",
         "batch_update_nodes"
       ],
-      "source": "src/tools/nodes.ts:841",
+      "source": "src/tools/nodes.ts:874",
       "symbol": "updateNode",
       "returns": "JSON: `{ node, warning?, unknown_properties? }`. `warning`\naggregates lifecycle-status hints, migration warnings, and any\nunknown-property notice. `unknown_properties` lists property\nkeys not in the entity's schema. Pass `strict: true` to reject unknown\nproperties instead of warning.",
+      "return_shape": "{ node, warning?, unknown_properties? }",
+      "return_notes": [
+        "`warning` aggregates lifecycle-status hints, migration warnings, and any unknown-property notice.",
+        "`unknown_properties` lists property keys not in the entity's schema.",
+        "Pass `strict: true` to reject unknown properties instead of warning."
+      ],
       "atomicity": "atomic-with-rollback (when `type` is changed); atomic for\nshallow-merge patches."
     },
     {
@@ -984,6 +1126,7 @@
       "source": "src/tools/edges.ts:209",
       "symbol": "batchCreateEdges",
       "returns": "JSON: `{ created, count }`.",
+      "return_shape": "{ created, count }",
       "atomicity": "atomic. Full validation pass before any mutation lands."
     },
     {
@@ -1022,6 +1165,7 @@
       "source": "src/tools/edges.ts:293",
       "symbol": "batchDeleteEdges",
       "returns": "JSON: `{ deleted, count }`.",
+      "return_shape": "{ deleted, count }",
       "atomicity": "atomic. Validation pass rejects the batch before any mutation\nlands."
     },
     {
@@ -1072,6 +1216,10 @@
       "source": "src/tools/edges.ts:177",
       "symbol": "batchMoveNodes",
       "returns": "JSON: `{ moves, warnings? }` mirroring the per-move result of\n`move_node`.",
+      "return_shape": "{ moves, warnings? }",
+      "return_notes": [
+        "mirroring the per-move result of `move_node`."
+      ],
       "atomicity": "atomic-with-rollback."
     },
     {
@@ -1122,6 +1270,9 @@
       "source": "src/tools/edges.ts:85",
       "symbol": "createEdge",
       "returns": "JSON: the created edge object plus optional resolution metadata.",
+      "return_notes": [
+        "JSON: the created edge object plus optional resolution metadata."
+      ],
       "atomicity": "atomic. Single store mutation."
     },
     {
@@ -1153,6 +1304,9 @@
       "source": "src/tools/edges.ts:122",
       "symbol": "deleteEdge",
       "returns": "JSON: the removed edge object.",
+      "return_notes": [
+        "JSON: the removed edge object."
+      ],
       "atomicity": "atomic."
     },
     {
@@ -1201,6 +1355,10 @@
       "source": "src/tools/edges.ts:403",
       "symbol": "exportEdges",
       "returns": "JSON: `{ edges, total, offset, limit, types?, _hash }`. Each edge\ncarries `{ id, source, target, type, mapping_confidence? }`.",
+      "return_shape": "{ edges, total, offset, limit, types?, _hash }",
+      "return_notes": [
+        "Each edge carries `{ id, source, target, type, mapping_confidence? }`."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1243,6 +1401,10 @@
       "source": "src/tools/edges.ts:149",
       "symbol": "moveNode",
       "returns": "JSON: `{ moved: true, node_id, new_parent_id, new_edge,\nold_edge_id?, warning? }`. The internal `removed_edge` field is stripped\nfrom the wire payload.",
+      "return_shape": "{ moved: true, node_id, new_parent_id, new_edge, old_edge_id?, warning? }",
+      "return_notes": [
+        "The internal `removed_edge` field is stripped from the wire payload."
+      ],
       "atomicity": "atomic-with-rollback. Pre-validates the new edge before\ntouching the old one."
     },
     {
@@ -1286,6 +1448,10 @@
       "source": "src/tools/edges.ts:490",
       "symbol": "renameEdgeType",
       "returns": "JSON: with `dry_run: true`, `{ dry_run, from, to, flip, would_rename, sample }`.\nWith `dry_run: false`, `{ dry_run, from, to, flip, renamed, ids }`.",
+      "return_notes": [
+        "JSON: with `dry_run: true`, `{ dry_run, from, to, flip, would_rename, sample }`.",
+        "With `dry_run: false`, `{ dry_run, from, to, flip, renamed, ids }`."
+      ],
       "atomicity": "atomic. Single-pass mutation; an empty match-set is a clean\nno-op rather than an error."
     },
     {
@@ -1330,6 +1496,11 @@
       "source": "src/tools/edges.ts:337",
       "symbol": "repairDanglingEdges",
       "returns": "JSON: `{ dry_run, report, dropped?, remaining? }`. `report` is\nthe pre-action classification. With `dry_run: false`, `dropped` is the\ncount of edges removed and `remaining` is the post-action report.",
+      "return_shape": "{ dry_run, report, dropped?, remaining? }",
+      "return_notes": [
+        "`report` is the pre-action classification.",
+        "With `dry_run: false`, `dropped` is the count of edges removed and `remaining` is the post-action report."
+      ],
       "atomicity": "atomic-with-rollback. Classification runs against the live\ndocument before any mutation; with `dry_run: false`, the drop set is\ncomputed up-front and applied in a single index rebuild."
     },
     {
@@ -1387,6 +1558,10 @@
       "source": "src/tools/areas.ts:261",
       "symbol": "createArea",
       "returns": "JSON: `{ node, portfolio_file, written_to }`. `node` is the typed\n`UPGProductArea` record persisted to `portfolio_areas[]`.",
+      "return_shape": "{ node, portfolio_file, written_to }",
+      "return_notes": [
+        "`node` is the typed `UPGProductArea` record persisted to `portfolio_areas[]`."
+      ],
       "atomicity": "atomic per write; the portfolio file is read, mutated, and\nflushed in one pass."
     },
     {
@@ -1410,6 +1585,10 @@
       "source": "src/tools/areas.ts:211",
       "symbol": "getAreaContext",
       "returns": "JSON: `{ has_area_context: false }` or\n`{ has_area_context: true, area_id, area_name, found_at }`.",
+      "return_shape": "{ has_area_context: false }",
+      "return_notes": [
+        "or `{ has_area_context: true, area_id, area_name, found_at }`."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1446,6 +1625,10 @@
       "source": "src/tools/areas.ts:69",
       "symbol": "getAreaGraph",
       "returns": "JSON: `{ area, nodes, edges, node_count, edge_count }`. May\ninclude a `degraded` block when the response was auto-trimmed.",
+      "return_shape": "{ area, nodes, edges, node_count, edge_count }",
+      "return_notes": [
+        "May include a `degraded` block when the response was auto-trimmed."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1474,6 +1657,10 @@
       "source": "src/tools/areas.ts:300",
       "symbol": "getChanges",
       "returns": "JSON: `{ changes, summary: { create, update, delete }, total }`.\n`since` filters to ISO 8601 timestamps after the cutoff.",
+      "return_shape": "{ changes, summary: { create, update, delete }, total }",
+      "return_notes": [
+        "`since` filters to ISO 8601 timestamps after the cutoff."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1500,6 +1687,7 @@
       "source": "src/tools/areas.ts:33",
       "symbol": "listProductAreas",
       "returns": "JSON: `{ areas: Array<{ id, title, strategic_priority?,\nparent_area_id?, products? }>, total }`.",
+      "return_shape": "{ areas: Array<{ id, title, strategic_priority?, parent_area_id?, products? }>, total }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1557,6 +1745,7 @@
       "source": "src/tools/workspace.ts:395",
       "symbol": "createCrossProductEdge",
       "returns": "JSON: `{ edge, portfolio_file }`.",
+      "return_shape": "{ edge, portfolio_file }",
       "atomicity": "non-atomic. Portfolio file create (if new) + edge append are\nseparate filesystem operations."
     },
     {
@@ -1608,6 +1797,10 @@
       "source": "src/tools/workspace.ts:275",
       "symbol": "createProductTool",
       "returns": "JSON: `{ message, ...result }`. `result` carries `id`, `title`,\n`slug`, `file_path`, and the optional portfolio edge.",
+      "return_shape": "{ message,...result }",
+      "return_notes": [
+        "`result` carries `id`, `title`, `slug`, `file_path`, and the optional portfolio edge."
+      ],
       "atomicity": "non-atomic. File write + workspace.json patch + optional\nportfolio edge are separate mutations."
     },
     {
@@ -1633,6 +1826,10 @@
       "source": "src/tools/workspace.ts:344",
       "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? }",
+      "return_notes": [
+        "Returns `{ organization: null }` when no portfolio document exists yet."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1658,6 +1855,10 @@
       "source": "src/tools/workspace.ts:163",
       "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 }",
+      "return_notes": [
+        "The shape depends on whether `.upg/workspace.json` exists."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1694,6 +1895,10 @@
       "source": "src/tools/workspace.ts:239",
       "symbol": "initWorkspaceTool",
       "returns": "JSON: `{ message, ...result }`. `result` carries the workspace\npath and the moved file's new location.",
+      "return_shape": "{ message,...result }",
+      "return_notes": [
+        "`result` carries the workspace path and the moved file's new location."
+      ],
       "atomicity": "non-atomic. The operation creates a directory and (optionally)\nmoves a file as separate filesystem mutations."
     },
     {
@@ -1720,6 +1925,7 @@
       "source": "src/tools/workspace.ts:40",
       "symbol": "listLocalProducts",
       "returns": "JSON: `{ products: Array<{ file, title, stage, nodes, edges }> }`.",
+      "return_shape": "{ products: Array<{ file, title, stage, nodes, edges }> }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1739,6 +1945,7 @@
       "source": "src/tools/workspace.ts:534",
       "symbol": "listPortfolioCrossEdges",
       "returns": "JSON: `{ cross_edges: UPGCrossEdge[], total, portfolio_file? }`.",
+      "return_shape": "{ cross_edges: UPGCrossEdge[], total, portfolio_file? }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1765,6 +1972,7 @@
       "source": "src/tools/workspace.ts:317",
       "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 }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1807,6 +2015,7 @@
       "source": "src/tools/workspace.ts:603",
       "symbol": "migrateCrossEdges",
       "returns": "JSON: `{ migrated, skipped, dry_run, portfolio_file? }`.",
+      "return_shape": "{ migrated, skipped, dry_run, portfolio_file? }",
       "atomicity": "non-atomic. Portfolio write + product file save are separate."
     },
     {
@@ -1840,6 +2049,7 @@
       "source": "src/tools/workspace.ts:108",
       "symbol": "switchProduct",
       "returns": "JSON: `{ message, file, product: { title, stage }, entities }`.",
+      "return_shape": "{ message, file, product: { title, stage }, entities }",
       "atomicity": "non-atomic. Flushes the current store, stops watching, and\nloads the new file as separate filesystem operations."
     },
     {
@@ -1881,6 +2091,7 @@
       "source": "src/tools/schema.ts:32",
       "symbol": "getEntitySchema",
       "returns": "JSON: `{ type, alias_of?, domain, expected_properties, edges_out,\nedges_in, phases?, initial_phase?, terminal_phases?, domain_guide? }`.",
+      "return_shape": "{ type, alias_of?, domain, expected_properties, edges_out, edges_in, phases?, initial_phase?, terminal_phases?, domain_guide? }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1919,6 +2130,9 @@
       "source": "src/tools/spec.ts:1425",
       "symbol": "getAntiPattern",
       "returns": "JSON: `UPGCuratedAntiPattern`",
+      "return_notes": [
+        "JSON: `UPGCuratedAntiPattern`"
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -1966,6 +2180,9 @@
       "source": "src/tools/spec.ts:321",
       "symbol": "getApproach",
       "returns": "JSON: the full `UPGApproach` record.",
+      "return_notes": [
+        "JSON: the full `UPGApproach` record."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2004,6 +2221,9 @@
       "source": "src/tools/spec.ts:746",
       "symbol": "getDomainGuide",
       "returns": "JSON: the full `UPGDomainUsageGuide` record.",
+      "return_notes": [
+        "JSON: the full `UPGDomainUsageGuide` record."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2039,6 +2259,9 @@
       "source": "src/tools/spec.ts:1881",
       "symbol": "getDomainRing",
       "returns": "JSON: the full `UPGDomainRing` record.",
+      "return_notes": [
+        "JSON: the full `UPGDomainRing` record."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2077,6 +2300,7 @@
       "source": "src/tools/spec.ts:877",
       "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 }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2115,6 +2339,9 @@
       "source": "src/tools/spec.ts:1340",
       "symbol": "getEntityMeta",
       "returns": "JSON: `EntityTypeMeta & { domain_id: string | null }`",
+      "return_notes": [
+        "JSON: `EntityTypeMeta & { domain_id: string | null }`"
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2153,6 +2380,9 @@
       "source": "src/tools/spec.ts:814",
       "symbol": "getFramework",
       "returns": "JSON: the full `UPGFramework` record.",
+      "return_notes": [
+        "JSON: the full `UPGFramework` record."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2191,6 +2421,7 @@
       "source": "src/tools/spec.ts:1134",
       "symbol": "getLensTool",
       "returns": "JSON: `{ ...UPGLens, visible_types: string[] }`",
+      "return_shape": "{...UPGLens, visible_types: string[] }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2226,6 +2457,9 @@
       "source": "src/tools/spec.ts:1751",
       "symbol": "getLifecycle",
       "returns": "JSON: the full `UPGLifecycle` record, or a descriptive message.",
+      "return_notes": [
+        "JSON: the full `UPGLifecycle` record, or a descriptive message."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2264,6 +2498,9 @@
       "source": "src/tools/spec.ts:253",
       "symbol": "getPlaybook",
       "returns": "JSON: the full `UPGPlaybook` record.",
+      "return_notes": [
+        "JSON: the full `UPGPlaybook` record."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2302,6 +2539,9 @@
       "source": "src/tools/spec.ts:936",
       "symbol": "getRegion",
       "returns": "JSON: the full `UPGRegion` record.",
+      "return_notes": [
+        "JSON: the full `UPGRegion` record."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2340,6 +2580,9 @@
       "source": "src/tools/spec.ts:958",
       "symbol": "getRegionForEntity",
       "returns": "JSON: the full `UPGRegion` record.",
+      "return_notes": [
+        "JSON: the full `UPGRegion` record."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2368,6 +2611,9 @@
       "source": "src/tools/spec.ts:1797",
       "symbol": "getScale",
       "returns": "JSON: the full `UPGScaleDefinition` record including all points.",
+      "return_notes": [
+        "JSON: the full `UPGScaleDefinition` record including all points."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2396,6 +2642,7 @@
       "source": "src/tools/spec.ts:986",
       "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 }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2441,6 +2688,7 @@
       "source": "src/tools/spec.ts:1202",
       "symbol": "getTypeLabel",
       "returns": "JSON: `{ ...UPGTypeLabel, resolved_label: string }`",
+      "return_shape": "{...UPGTypeLabel, resolved_label: string }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2479,6 +2727,7 @@
       "source": "src/tools/spec.ts:1232",
       "symbol": "getValidChildrenTool",
       "returns": "JSON: `{ parent_type, valid_children: string[] }`",
+      "return_shape": "{ parent_type, valid_children: string[] }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2516,6 +2765,9 @@
       "source": "src/tools/spec.ts:459",
       "symbol": "inspect",
       "returns": "JSON envelope: `{ approach_id, scope, generated_at, approach,\nparams, violations, summary, execution_mode: \"execution_v0_4_0\" }`",
+      "return_notes": [
+        "JSON envelope: `{ approach_id, scope, generated_at, approach, params, violations, summary, execution_mode: \"execution_v0_4_0\" }`"
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2578,6 +2830,7 @@
       "source": "src/tools/spec.ts:1383",
       "symbol": "listAntiPatterns",
       "returns": "JSON: `{ total, count, next_cursor?, anti_patterns: UPGCuratedAntiPattern[] }`",
+      "return_shape": "{ total, count, next_cursor?, anti_patterns: UPGCuratedAntiPattern[] }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2614,6 +2867,7 @@
       "source": "src/tools/spec.ts:293",
       "symbol": "listApproaches",
       "returns": "JSON: `{ count, approaches: UPGApproach[] }`",
+      "return_shape": "{ count, approaches: UPGApproach[] }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2677,6 +2931,7 @@
       "source": "src/tools/spec.ts:1472",
       "symbol": "listBenchmarks",
       "returns": "JSON: `{ kind, total, count, benchmarks: ... }`",
+      "return_shape": "{ kind, total, count, benchmarks:... }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2704,6 +2959,7 @@
       "source": "src/tools/spec.ts:1072",
       "symbol": "listCrossEdgeTypes",
       "returns": "JSON: `{ count, types: readonly UPGCrossEdgeType[] }`",
+      "return_shape": "{ count, types: readonly UPGCrossEdgeType[] }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2731,6 +2987,7 @@
       "source": "src/tools/spec.ts:1860",
       "symbol": "listDomainRings",
       "returns": "JSON: `{ rings: UPGDomainRing[], total: number }`",
+      "return_shape": "{ rings: UPGDomainRing[], total: number }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2765,6 +3022,7 @@
       "source": "src/tools/spec.ts:711",
       "symbol": "listDomains",
       "returns": "JSON: `{ count, domains: Array<{ domain_id, anchor_entity, creation_sequence } | { domain_id, label, description, types, has_guide }> }`",
+      "return_shape": "{ count, domains: Array<{ domain_id, anchor_entity, creation_sequence } | { domain_id, label, description, types, has_guide }> }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2799,6 +3057,7 @@
       "source": "src/tools/spec.ts:1644",
       "symbol": "listEdgeMigrations",
       "returns": "JSON: `{ migrations: [{ kind, from, to?, since }], total: number }`",
+      "return_shape": "{ migrations: [{ kind, from, to?, since }], total: number }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2837,6 +3096,7 @@
       "source": "src/tools/spec.ts:858",
       "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 }> }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2894,6 +3154,7 @@
       "source": "src/tools/spec.ts:1284",
       "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 }> }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2920,6 +3181,7 @@
       "source": "src/tools/spec.ts:1816",
       "symbol": "listFrameworkCategories",
       "returns": "JSON: `{ categories: string[], total: number }`",
+      "return_shape": "{ categories: string[], total: number }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2947,6 +3209,7 @@
       "source": "src/tools/spec.ts:1837",
       "symbol": "listFrameworkStructurePatterns",
       "returns": "JSON: `{ patterns: string[], total: number }`",
+      "return_shape": "{ patterns: string[], total: number }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -2989,6 +3252,7 @@
       "source": "src/tools/spec.ts:778",
       "symbol": "listFrameworks",
       "returns": "JSON: `{ total, count, next_cursor?, frameworks: UPGFramework[] }`",
+      "return_shape": "{ total, count, next_cursor?, frameworks: UPGFramework[] }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -3017,6 +3281,7 @@
       "source": "src/tools/spec.ts:1101",
       "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 }> }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -3053,6 +3318,7 @@
       "source": "src/tools/spec.ts:1709",
       "symbol": "listLifecycles",
       "returns": "JSON: `{ lifecycles, total, free_types: string[], planned_types: string[] }`",
+      "return_shape": "{ lifecycles, total, free_types: string[], planned_types: string[] }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -3094,6 +3360,7 @@
       "source": "src/tools/spec.ts:205",
       "symbol": "listPlaybooks",
       "returns": "JSON: `{ count, playbooks: UPGPlaybook[] }`",
+      "return_shape": "{ count, playbooks: UPGPlaybook[] }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -3122,6 +3389,7 @@
       "source": "src/tools/spec.ts:1580",
       "symbol": "listProductStages",
       "returns": "JSON: `{ count, stages: readonly UPGProductStage[] }`",
+      "return_shape": "{ count, stages: readonly UPGProductStage[] }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -3150,6 +3418,7 @@
       "source": "src/tools/spec.ts:904",
       "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 }> }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -3176,6 +3445,7 @@
       "source": "src/tools/spec.ts:1782",
       "symbol": "listScales",
       "returns": "JSON: `{ scales: UPGScaleDefinition[], total: number }`",
+      "return_shape": "{ scales: UPGScaleDefinition[], total: number }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -3204,6 +3474,7 @@
       "source": "src/tools/spec.ts:1681",
       "symbol": "listSplitMigrations",
       "returns": "JSON: `{ splits: [...], total: number }`",
+      "return_shape": "{ splits: [...], total: number }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -3240,6 +3511,7 @@
       "source": "src/tools/spec.ts:1167",
       "symbol": "listTypeLabels",
       "returns": "JSON: `{ total, count, next_cursor?, labels: UPGTypeLabel[] }`",
+      "return_shape": "{ total, count, next_cursor?, labels: UPGTypeLabel[] }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -3275,6 +3547,7 @@
       "source": "src/tools/spec.ts:1613",
       "symbol": "listTypeMigrations",
       "returns": "JSON: `{ migrations: [{ from, to, since }], total: number }`",
+      "return_shape": "{ migrations: [{ from, to, since }], total: number }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -3309,6 +3582,9 @@
       "source": "src/tools/spec.ts:419",
       "symbol": "plan",
       "returns": "JSON envelope: `{ approach_id, scope, generated_at, approach,\nparams, missing_entities, coverage_score, expected_count, covered_count,\nexecution_mode: \"execution_v0_4_0\" }`.",
+      "return_notes": [
+        "JSON envelope: `{ approach_id, scope, generated_at, approach, params, missing_entities, coverage_score, expected_count, covered_count, execution_mode: \"execution_v0_4_0\" }`."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -3350,6 +3626,10 @@
       "source": "src/tools/spec.ts:518",
       "symbol": "prioritise",
       "returns": "JSON envelope: `{ approach_id, scope, generated_at, approach,\nparams, framework_resolved, ranked?, required_properties?,\nhint?, execution_mode }`. Execution mode is `\"execution_v0_4_0\"` when\nthe framework has an expression, `\"definition_lookup_v0_4_0\"` otherwise.",
+      "return_notes": [
+        "JSON envelope: `{ approach_id, scope, generated_at, approach, params, framework_resolved, ranked?, required_properties?, hint?, execution_mode }`.",
+        "Execution mode is `\"execution_v0_4_0\"` when the framework has an expression, `\"definition_lookup_v0_4_0\"` otherwise."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -3398,6 +3678,9 @@
       "source": "src/tools/spec.ts:661",
       "symbol": "reflect",
       "returns": "JSON envelope: `{ approach_id, scope, generated_at, approach,\nparams, prompts, execution_mode: \"execution_v0_4_0\" }`",
+      "return_notes": [
+        "JSON envelope: `{ approach_id, scope, generated_at, approach, params, prompts, execution_mode: \"execution_v0_4_0\" }`"
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -3443,6 +3726,7 @@
       "source": "src/tools/spec.ts:1040",
       "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? }",
       "atomicity": "atomic (read-only)"
     },
     {
@@ -3501,6 +3785,9 @@
       "source": "src/tools/spec.ts:598",
       "symbol": "trace",
       "returns": "JSON envelope: `{ approach_id, scope, generated_at, approach,\nparams, trail, reached, error?, halted_at_depth?,\nexecution_mode: \"execution_v0_4_0\" }`",
+      "return_notes": [
+        "JSON envelope: `{ approach_id, scope, generated_at, approach, params, trail, reached, error?, halted_at_depth?, execution_mode: \"execution_v0_4_0\" }`"
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -3564,6 +3851,7 @@
       "source": "src/tools/sync.ts:80",
       "symbol": "applyPullChangeset",
       "returns": "JSON: `{ nodes_created, nodes_updated, nodes_deleted,\nedges_created, edges_deleted, strategy, conflicts?, message? }`.",
+      "return_shape": "{ nodes_created, nodes_updated, nodes_deleted, edges_created, edges_deleted, strategy, conflicts?, message? }",
       "atomicity": "non-atomic. Node/edge mutations apply incrementally; a partial\nfailure mid-application leaves the graph in a half-merged state. The\n`.upg-sync` file is updated after the merge sweep so its hashes reflect\nwhatever landed."
     },
     {
@@ -3592,6 +3880,10 @@
       "source": "src/tools/sync.ts:31",
       "symbol": "getSyncState",
       "returns": "JSON: `{ synced: false, message }` or\n`{ synced: true, cloud_endpoint, product_id, last_synced_at,\nmapped_nodes, mapped_edges, last_snapshot_hash }`.",
+      "return_shape": "{ synced: false, message }",
+      "return_notes": [
+        "or `{ synced: true, cloud_endpoint, product_id, last_synced_at, mapped_nodes, mapped_edges, last_snapshot_hash }`."
+      ],
       "atomicity": "atomic (read-only)"
     },
     {
@@ -3640,6 +3932,7 @@
       "source": "src/tools/sync.ts:264",
       "symbol": "pushToCloud",
       "returns": "JSON: `{ success, product_id, nodes_created, edges_created,\nerrors, sync_file_updated }`.",
+      "return_shape": "{ success, product_id, nodes_created, edges_created, errors, sync_file_updated }",
       "atomicity": "non-atomic. Performs an HTTP round-trip and then writes the\nsync file as a separate filesystem mutation. A partial failure (e.g.\ncloud accepted some entities, then network broke) is reflected in the\n`errors` array; the sync file is only updated when the import call\nsucceeds."
     },
     {
@@ -3680,8 +3973,38 @@
       "source": "src/tools/validation.ts:906",
       "symbol": "getAntiPatternViolationsFor",
       "returns": "JSON: `{ entity_id, type, violations: [...] }`.",
+      "return_shape": "{ entity_id, type, violations: [...] }",
       "atomicity": "atomic (read-only)"
     },
+    {
+      "name": "skill_audit",
+      "description": "Audit one or every UPG skill for source-vs-deployed integrity. Use before recommending a skill to confirm `.claude/skills/<name>/SKILL.md` is a symlink to canonical source and the bodies match. When `in_sync: false`, what you read from `packages/upg-mcp-server/skills/` is NOT what the user will experience.",
+      "domain": "validation",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Optional skill name (e.g. \"upg-trace\"). If omitted, audits every canonical skill."
+          }
+        }
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"skills\": []\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [],
+      "source": "src/tools/skills.ts:191",
+      "symbol": "skillAudit",
+      "returns": "`{ skills: SkillAuditRecord[] }`",
+      "return_shape": "{ skills: SkillAuditRecord[] }",
+      "atomicity": "atomic (read-only filesystem stat + read)"
+    },
     {
       "name": "validate_graph",
       "description": "Walk the loaded graph and return a per-class, per-node report of schema drift plus anti-pattern violations from `UPG_ANTI_PATTERNS`. Schema-drift classes: non-canonical entity types, non-canonical edge types, top-level fields outside `UPGBaseNode`, invalid status values, self-referential `source_id`/`source_type`, properties matching `UPG_PROPERTY_MIGRATIONS` rules. Anti-patterns: catalog entries that fired against the live graph, sorted high → medium → low. Each entry carries `suggested_migration` (drift) or `remediation` (anti-pattern). Top-level `valid` is true iff drift is empty AND no violations fired. Read-only; pairs with `migrate_type`, `rename_edge_type`, `get_anti_pattern_violations_for`.",
@@ -3766,84 +4089,12 @@
       "source": "src/tools/validation.ts:257",
       "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).",
-      "atomicity": "atomic (read-only)"
-    },
-    {
-      "name": "migrate_status",
-      "description": "Apply `UPG_STATUS_MIGRATIONS` graph-wide: rewrite legacy lifecycle status values to canonical phase ids. Auto-mode (no filters) selects nodes whose current status is invalid against the entity type's lifecycle and has a registered replacement (the same invariant that drives `validate_graph` lifecycle_drift). Surgical mode (`from_status` + `to_status`) overrides the registry and rewrites every (entity_type?, from_status) match. Nodes with invalid statuses but no registered replacement surface under `skipped_no_migration`. Default `dry_run=true`; pass `dry_run=false` to commit.",
-      "domain": "migrations",
-      "inputSchema": {
-        "type": "object",
-        "properties": {
-          "entity_type": {
-            "type": "string",
-            "description": "Optional. Restrict the rewrite to nodes of this canonical entity type (e.g. \"service\", \"feature\")."
-          },
-          "from_status": {
-            "type": "string",
-            "description": "Optional. Restrict the rewrite to nodes whose current status equals this exact value. When provided, `to_status` is required and the registry is bypassed."
-          },
-          "to_status": {
-            "type": "string",
-            "description": "Required when `from_status` is provided. The canonical phase id to write."
-          },
-          "dry_run": {
-            "type": "boolean",
-            "description": "Preview changes without applying (default true). Pass false to commit."
-          }
-        }
-      },
-      "throws": [
-        "Returns a textError when `from_status` is provided without\n`to_status`, or when `entity_type` is provided but isn't a string."
-      ],
-      "examples": [
-        {
-          "description": "Live call against the Notion example graph.",
-          "input": "{}",
-          "output": "{\n  \"migrated_nodes\": 0,\n  \"skipped_no_migration\": 0,\n  \"changes\": [],\n  \"dry_run\": true\n}"
-        }
-      ],
-      "warnings": [
-        "Default is `dry_run: true`. Pass `dry_run: false` to commit.\nIdempotent on retry; re-running after a successful commit reports\nzero changes (canonical statuses pass the validity check)."
-      ],
-      "see": [
-        "migrate_type",
-        "migrate_properties",
-        "validate_graph",
-        "list_lifecycles"
-      ],
-      "source": "src/tools/migrations.ts:64",
-      "symbol": "migrateStatus",
-      "returns": "JSON: `MigrateStatusResult`.",
-      "atomicity": "per-node. Status writes go through `store.updateNode`\none at a time. Dry-run is read-only."
-    },
-    {
-      "name": "skill_audit",
-      "description": "Audit one or every UPG skill for source-vs-deployed integrity. Use before recommending a skill to confirm `.claude/skills/<name>/SKILL.md` is a symlink to canonical source and the bodies match. When `in_sync: false`, what you read from `packages/upg-mcp-server/skills/` is NOT what the user will experience.",
-      "domain": "skills",
-      "inputSchema": {
-        "type": "object",
-        "properties": {
-          "name": {
-            "type": "string",
-            "description": "Optional skill name (e.g. \"upg-trace\"). If omitted, audits every canonical skill."
-          }
-        }
-      },
-      "throws": [],
-      "examples": [
-        {
-          "description": "Live call against the Notion example graph.",
-          "input": "{}",
-          "output": "{\n  \"skills\": []\n}"
-        }
+      "return_shape": "{ 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)."
       ],
-      "warnings": [],
-      "see": [],
-      "source": "src/tools/skills.ts:191",
-      "symbol": "skillAudit",
-      "returns": "`{ skills: SkillAuditRecord[] }`",
-      "atomicity": "atomic (read-only filesystem stat + read)"
+      "atomicity": "atomic (read-only)"
     }
   ]
 }