@unified-product-graph/mcp-server 0.6.0

package/dist/tools-manifest.json

@@ -0,0 +1,3849 @@
+{
+  "schema_version": "2",
+  "package": "@unified-product-graph/mcp-server",
+  "package_version": "0.6.0",
+  "tool_count": 93,
+  "domains": [
+    "context",
+    "nodes",
+    "edges",
+    "areas",
+    "workspace",
+    "schema",
+    "spec",
+    "sync",
+    "validation",
+    "migrations",
+    "skills"
+  ],
+  "tools": [
+    {
+      "name": "get_graph_digest",
+      "description": "Pre-computed graph analytics in one call: counts, health, chain completeness, business-area coverage, lifecycle balance. ~500 tokens vs ~5-8K for equivalent manual fetches.",
+      "domain": "context",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "if_changed_since": {
+            "type": "string",
+            "description": "Hash from a previous response. Returns { changed: false } if graph unchanged (saves ~470 tokens)."
+          }
+        }
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"product\": {\n    \"title\": \"Notion (SATURATED test graph)\",\n    \"stage\": \"concept\"\n  },\n  \"counts\": {\n    \"total_nodes\": 2054,\n    \"total_edges\": 3120,\n    \"by_type\": {\n      \"product\": 13,\n      \"capability\": 20,\n      \"value_stream\": 3,\n      \"decision\": 13,\n      \"evidence\": 10,\n      \"assumption\": 30,\n      \"outcome\": 6,\n      \"document\": 9,\n      \"objective\": 6,\n      \"key_result\": 14,\n      \"design_component\": 15,\n      \"hypothesis\": 6,\n      \"experiment\": 5,\n      \"experiment_plan\": 13,\n      \"job\": 10,\n      \"bounded_context\": 13,\n      \"initiative\": 11,\n      \"strategic_pillar\": 6,\n      \"test_plan\": 8,\n      \"screen\": 15,\n      \"experiment_run\": 18,\n      \"design_system\": 4,\n      \"team\": 1,\n      \"compliance_requirement\": 5,\n      \"workspace\": 3,\n      \"epic\": 4,\n      \"bug\": 6,\n      \"task\": 3,\n      \"feature_area\": 3,\n      \"mission\": 2,\n      \"desired_outcome\": 4,\n      \"model_comparison\": 3,\n      \"agent_session\": 3,\n      \"learning\": 17,\n      \"research_plan\": 6,\n      \"constraint\": 3,\n      \"stakeholder\": 10,\n      \"feature\": 12,\n      \"security_review\": 8,\n      \"metric\": 23,\n      \"person\": 215,\n      \"technical_debt_item\": 12,\n      \"risk\": 9,\n      \"service\": 11,\n      \"opportunity\": 7,\n      \"solution\": 11,\n      \"feasibility_study\": 3,\n      \"design_sprint\": 3,\n      \"prototype\": 8,\n      \"design_concept\": 7,\n      \"vision\": 1,\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "get_product_context"
+      ],
+      "source": "src/tools/context.ts:240",
+      "symbol": "getGraphDigest",
+      "returns": "JSON object: `{ counts, health, chains, coverage, lifecycle,\nlens, lens_digest, _hash }`. ~500 tokens vs ~5-8K for equivalent manual\nfetches.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "get_product_context",
+      "description": "Product summary, entity counts by type, and a human-readable graph overview. Call first to understand the file. Pass include_summary for edge counts, orphans, and edges-by-type.",
+      "domain": "context",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "include_summary": {
+            "type": "boolean",
+            "description": "Include detailed graph statistics (edge counts by type, orphan count)"
+          },
+          "if_changed_since": {
+            "type": "string",
+            "description": "Hash from a previous response. Returns { changed: false } if graph unchanged."
+          }
+        }
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "## Notion (SATURATED test graph)\n\nStage: concept\n\nLens: product\n\n### 🧭 Product Lens\n- Personas: 4\n- Outcomes: 6\n- Hypotheses: 6 (0 validated)\n\n### Graph Stats\n- Nodes: 2054\n- Edges: 3120\n- Entity types: 312\n\n### Entities by Type\n- Person (`person`): 215\n- Journey Step (`journey_step`): 53\n- Test Case (`test_case`): 48\n- Screen State (`screen_state`): 36\n- Assumption (`assumption`): 30\n- Journey Phase (`journey_phase`): 28\n- Journey Action (`journey_action`): 28\n- Interaction Spec (`interaction_spec`): 28\n- Metric (`metric`): 23\n- Test Result (`test_result`): 23\n- Capability (`capability`): 20\n- Participant (`participant`): 19\n- Regression Test (`regression_test`): 19\n- Experiment Run (`experiment_run`): 18\n- Alert Rule (`alert_rule`): 18\n- Validated Learning (`learning`): 17\n- Observation (`observation`): 17\n- Survey Response (`survey_response`): 17\n- Annotation (`annotation`): 17\n- Vulnerability (`vulnerability`): 16\n- Design Component (`design_component`): 15\n- Screen (`screen`): 15\n- Monitor (`monitor`): 15\n- Research Question (`research_question`): 15\n- Service Level Indicator (`service_level_indicator`): 15\n- Error Budget (`error_budget`): 15\n- Key Result (`key_result`): 14\n- Product (`product`): 13\n- Decision (`decision`): 13\n- Experiment Plan (`experiment_plan`): 13\n- Bounded Context (`bounded_context`): 13\n- Insight (`insight`): 13\n- Theme (`theme`): 13\n- Feature\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "get_graph_digest",
+        "get_entity_schema"
+      ],
+      "source": "src/tools/context.ts:55",
+      "symbol": "getProductContext",
+      "returns": "Markdown string with product header, lens preamble, entity counts,\nactive-domain creation sequences, and `_hash` footer for `if_changed_since`\ndiffing.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "get_session_context",
+      "description": "Read session context: which skills ran, what was recommended, current focus area. Returns `recommendations_to_avoid` — the deduped list of recommendations already given this session. Pick your next recommendation NOT in that array (data-layer dedup, not prose).",
+      "domain": "context",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"lens\": \"product\",\n  \"skills_invoked\": [],\n  \"recommendations_given\": [],\n  \"recommendations_to_avoid\": [],\n  \"focus_area\": null,\n  \"custom\": {},\n  \"skills_count\": 0,\n  \"last_skill\": null,\n  \"last_recommendation\": null\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "update_session_context"
+      ],
+      "source": "src/tools/context.ts:295",
+      "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.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "update_session_context",
+      "description": "Update session context: register a skill invocation, record a recommendation, set focus area, switch lens, or store custom state for cross-skill coordination.",
+      "domain": "context",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "skill_invoked": {
+            "type": "string",
+            "description": "Register that this skill was just invoked (e.g. \"upg-status\")"
+          },
+          "recommendation": {
+            "type": "string",
+            "description": "Record a recommendation given to the user (e.g. \"Run /upg-strategy to fill strategy gap\")"
+          },
+          "focus_area": {
+            "type": "string",
+            "description": "Set the current focus area (e.g. \"strategy\", \"validation\", \"user_research\")"
+          },
+          "lens": {
+            "type": "string",
+            "enum": [
+              "product",
+              "engineering",
+              "design",
+              "growth"
+            ],
+            "description": "Switch the active lens. Changes what context, skills, and gaps are surfaced first."
+          },
+          "persist_lens": {
+            "type": "boolean",
+            "description": "If true, also save the lens to the .upg file so it persists across sessions"
+          },
+          "custom": {
+            "type": "object",
+            "description": "Arbitrary key-value pairs for cross-skill state"
+          }
+        }
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"updated\": true,\n  \"session\": {\n    \"lens\": \"product\",\n    \"skills_invoked\": [],\n    \"recommendations_given\": [],\n    \"focus_area\": null,\n    \"custom\": {}\n  }\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "get_session_context"
+      ],
+      "source": "src/tools/context.ts:336",
+      "symbol": "updateSessionContext",
+      "returns": "JSON: `{ updated: true, session: SessionContext }` reflecting the\nnew 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."
+    },
+    {
+      "name": "batch_create_nodes",
+      "description": "Create up to 50 entities in one atomic call, optionally with explicit edges in the same transaction. Use `parent_ref` (\"$0\", \"$1\") to reference nodes created earlier in the same batch. The optional `edges` array accepts the same `$N` refs (or existing node IDs) for both endpoints. All nodes and edges validate up front; on failure nothing lands.",
+      "domain": "nodes",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "nodes": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "type": {
+                  "type": "string",
+                  "description": "UPG entity type (e.g. \"persona\", \"opportunity\")"
+                },
+                "title": {
+                  "type": "string",
+                  "description": "Entity title"
+                },
+                "description": {
+                  "type": "string",
+                  "description": "Optional description"
+                },
+                "status": {
+                  "type": "string",
+                  "description": "Lifecycle status"
+                },
+                "tags": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "description": "Freeform tags"
+                },
+                "properties": {
+                  "type": "object",
+                  "description": "Type-specific fields"
+                },
+                "parent_id": {
+                  "type": "string",
+                  "description": "Parent node ID. Creates an edge automatically."
+                },
+                "parent_ref": {
+                  "type": "string",
+                  "description": "Reference a node created earlier in this batch by index, e.g. \"$0\", \"$1\""
+                }
+              },
+              "required": [
+                "type",
+                "title"
+              ]
+            },
+            "description": "Array of nodes to create (max 50)"
+          },
+          "edges": {
+            "type": "array",
+            "description": "Optional edges to create alongside the nodes (same atomic transaction). Each edge's from/to may be a `$N` ref into the `nodes` array OR an existing node ID.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "from_ref": {
+                  "type": "string",
+                  "description": "`$N` ref or existing node id for the source endpoint"
+                },
+                "to_ref": {
+                  "type": "string",
+                  "description": "`$N` ref or existing node id for the target endpoint"
+                },
+                "type": {
+                  "type": "string",
+                  "description": "Optional explicit edge type (must be in UPG_EDGE_CATALOG). If omitted, inferred from canonical source/target types."
+                }
+              },
+              "required": [
+                "from_ref",
+                "to_ref"
+              ]
+            }
+          }
+        },
+        "required": [
+          "nodes"
+        ]
+      },
+      "throws": [
+        "Returns a textError when `nodes` is missing/non-array or any\nvalidation fails."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"nodes\": [\n    {\n      \"type\": \"person\",\n      \"title\": \"Example node A\"\n    },\n    {\n      \"type\": \"person\",\n      \"title\": \"Example node B\"\n    }\n  ]\n}",
+          "output": "{\n  \"created\": [\n    {\n      \"id\": \"n_j6U_8nTCFs7stzLl\",\n      \"type\": \"person\",\n      \"title\": \"Example node A\"\n    },\n    {\n      \"id\": \"n_J6z4nc-D40LV54G5\",\n      \"type\": \"person\",\n      \"title\": \"Example node B\"\n    }\n  ],\n  \"edges\": [],\n  \"count\": 2,\n  \"warnings\": [\n    \"Created 2 nodes with no edges — they are orphans. Use the edges[] array in this call to link them. See get_entity_schema(<type>) for canonical edges per type.\"\n  ]\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "create_node",
+        "batch_create_edges"
+      ],
+      "source": "src/tools/nodes.ts:958",
+      "symbol": "batchCreateNodes",
+      "returns": "JSON: `{ created, edges_created, count, edges_count, warnings? }`.",
+      "atomicity": "atomic-with-rollback. Full validation pass first, then commit."
+    },
+    {
+      "name": "batch_delete_nodes",
+      "description": "Delete up to 50 entities and their connected edges in one atomic call (all succeed or all fail).",
+      "domain": "nodes",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "node_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Array of node IDs to delete (max 50)"
+          }
+        },
+        "required": [
+          "node_ids"
+        ]
+      },
+      "throws": [
+        "Returns a textError when `node_ids` is missing/non-array, empty,\nlonger than 50, or any ID does not resolve."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"node_ids\": [\n    \"1c051617-6cb7-4a59-b0a1-7779f404145b\"\n  ]\n}",
+          "output": "{\n  \"deleted\": [\n    {\n      \"id\": \"1c051617-6cb7-4a59-b0a1-7779f404145b\",\n      \"title\": \"Real-time multi-cursor collaboration\"\n    }\n  ],\n  \"edges_removed\": 4,\n  \"count\": 1\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "delete_node"
+      ],
+      "source": "src/tools/nodes.ts:1062",
+      "symbol": "batchDeleteNodes",
+      "returns": "JSON: `{ deleted, edges_removed, count }`.",
+      "atomicity": "atomic. Validation pass rejects the entire batch before any\nmutation lands."
+    },
+    {
+      "name": "batch_update_nodes",
+      "description": "Update up to 50 entities atomically (all succeed or all fail). Unspecified fields preserved. Properties merge with existing.",
+      "domain": "nodes",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "updates": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "node_id": {
+                  "type": "string",
+                  "description": "The node ID to update"
+                },
+                "title": {
+                  "type": "string"
+                },
+                "description": {
+                  "type": "string"
+                },
+                "status": {
+                  "type": "string"
+                },
+                "tags": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "properties": {
+                  "type": "object",
+                  "description": "Merged with existing properties"
+                }
+              },
+              "required": [
+                "node_id"
+              ]
+            },
+            "description": "Array of updates to apply (max 50)"
+          }
+        },
+        "required": [
+          "updates"
+        ]
+      },
+      "throws": [
+        "Returns a textError when `updates` is missing/non-array, the array\nis empty, longer than 50, or any item references a missing node."
+      ],
+      "examples": [],
+      "warnings": [],
+      "see": [
+        "update_node"
+      ],
+      "source": "src/tools/nodes.ts:986",
+      "symbol": "batchUpdateNodes",
+      "returns": "JSON: `{ updated, count, warnings? }`. `warnings` carries\nlifecycle-phase hints aggregated across the batch.",
+      "atomicity": "atomic. Validation pass rejects the entire batch before any\nmutation lands."
+    },
+    {
+      "name": "create_node",
+      "description": "Create one entity, optionally with a parent edge. For 3+ entities, use `batch_create_nodes` instead of looping. Portfolio-scoped types (`portfolio`, `organization`, `product_area`) route to `.upg/portfolio.upg` rather than the active product's `nodes[]`.",
+      "domain": "nodes",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string",
+            "description": "UPG entity type (e.g. \"persona\", \"opportunity\"). Portfolio-scoped: \"portfolio\", \"organization\", \"product_area\"."
+          },
+          "title": {
+            "type": "string",
+            "description": "Entity title"
+          },
+          "description": {
+            "type": "string",
+            "description": "Optional description"
+          },
+          "tags": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Freeform tags"
+          },
+          "status": {
+            "type": "string",
+            "description": "Lifecycle status"
+          },
+          "properties": {
+            "type": "object",
+            "description": "Type-specific fields"
+          },
+          "parent_id": {
+            "type": "string",
+            "description": "Parent node ID. Creates an edge automatically. Ignored for portfolio-scoped types."
+          },
+          "overwrite_organization": {
+            "type": "boolean",
+            "description": "For type=\"organization\" only. When true, replaces the existing portfolio organisation instead of throwing."
+          }
+        },
+        "required": [
+          "type",
+          "title"
+        ]
+      },
+      "throws": [
+        "Returns a textError when `type` or `title` is missing, when the type\nis unknown (`UnknownEntityTypeError`), when `strict: true` and unknown\nproperties are present, or when the underlying store rejects the write."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"type\": \"person\",\n  \"title\": \"Example node\"\n}",
+          "output": "{\n  \"node\": {\n    \"id\": \"n_LSjd64yzUUdx5X9r\",\n    \"type\": \"person\",\n    \"title\": \"Example node\",\n    \"slug\": \"example-node\"\n  },\n  \"edge\": null\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "batch_create_nodes",
+        "update_node"
+      ],
+      "source": "src/tools/nodes.ts:702",
+      "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.",
+      "atomicity": "atomic-with-rollback. Schema validation runs before mutation."
+    },
+    {
+      "name": "deduplicate_nodes",
+      "description": "Find duplicate entities (same title + type) and return them grouped. `dry_run` previews; otherwise keeps one per group and redirects edges from the others.",
+      "domain": "nodes",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string",
+            "description": "Only check this entity type. Omit to check all types."
+          },
+          "dry_run": {
+            "type": "boolean",
+            "description": "Preview duplicates without merging (default true)"
+          },
+          "keep": {
+            "type": "string",
+            "description": "Which duplicate to keep when merging: \"newest\" (default) or \"oldest\"."
+          }
+        }
+      },
+      "throws": [
+        "Returns a textError when `keep` is provided but is not\n`\"newest\"` or `\"oldest\"`."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"duplicates\": [\n    {\n      \"title\": \"Cap AI inference cost at $0.18 / MAU / month\",\n      \"type\": \"decision\",\n      \"count\": 2,\n      \"ids\": [\n        \"e4078a2d-ff4f-4047-98e7-7d6556109eb0\",\n        \"afd2234f-3c50-487d-8507-95762895c7dd\"\n      ]\n    },\n    {\n      \"title\": \"AI Q&A acceptance rate ≥ 70%\",\n      \"type\": \"key_result\",\n      \"count\": 2,\n      \"ids\": [\n        \"6d6991c4-36f2-46d4-bd1a-cccc87313751\",\n        \"eee73bb6-52ac-47eb-b007-d578d17870cf\"\n      ]\n    },\n    {\n      \"title\": \"AI-native, not AI-bolted-on\",\n      \"type\": \"strategic_pillar\",\n      \"count\": 2,\n      \"ids\": [\n        \"620af368-90b8-4d26-8479-1359826af5e1\",\n        \"d8665db0-5210-4354-a4ab-391ae8a843a2\"\n      ]\n    },\n    {\n      \"title\": \"Notion Calendar\",\n      \"type\": \"product\",\n      \"count\": 2,\n      \"ids\": [\n        \"c355f3ea-1e9f-45a1-aedc-a7adf66050e1\",\n        \"4d5b21d6-66b1-4663-add8-2b24a10848ea\"\n      ]\n    },\n    {\n      \"title\": \"One workspace, every team\",\n      \"type\": \"strategic_pillar\",\n      \"count\": 2,\n      \"ids\": [\n        \"4c23a9dc-a4b3-4c80-83ee-10e35b839c26\",\n        \"4d1b0619-b5eb-4d5d-a465-b98bc164a203\"\n      ]\n    },\n    {\n      \"title\": \"react\",\n      \"type\": \"library_dependency\",\n      \"count\": 2,\n      \"ids\": [\n        \"abe04949-9bc9-48e7-8ff8-8023a6c87b11\",\n        \"4a04fd43-2451-4492-9647-c883545af3c2\"\n      ]\n    },\n    {\n      \"title\": \"AI-native vs\n… (truncated)"
+        }
+      ],
+      "warnings": [
+        "Default is `dry_run: true`. Pass `dry_run: false` to commit.\nIdempotent on retry: a second `dry_run: false` against an\nalready-deduplicated graph reports zero merges."
+      ],
+      "see": [
+        "search_nodes",
+        "list_nodes",
+        "batch_delete_nodes",
+        "validate_graph"
+      ],
+      "source": "src/tools/nodes.ts:1307",
+      "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 }`.",
+      "atomicity": "non-atomic. Merges are applied group-by-group; a mid-flight\nerror leaves earlier groups merged."
+    },
+    {
+      "name": "delete_node",
+      "description": "Remove one entity and all its connected edges. For 3+ entities, use `batch_delete_nodes`.",
+      "domain": "nodes",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "node_id": {
+            "type": "string",
+            "description": "The node ID to delete"
+          }
+        },
+        "required": [
+          "node_id"
+        ]
+      },
+      "throws": [
+        "Returns a textError when `node_id` is missing or the node does not\nexist."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"node_id\": \"ec3d5479-4947-4bd9-9e77-b5ee01beb851\"\n}",
+          "output": "{\n  \"deleted_node_id\": \"ec3d5479-4947-4bd9-9e77-b5ee01beb851\",\n  \"deleted_node_title\": \"Notion (SATURATED test graph)\",\n  \"deleted_edge_ids\": [\n    \"1d645a2e-391b-4bc7-b0de-e15691c8a7d6\",\n    \"b4a77a49-7d28-4926-831f-464574d927fe\",\n    \"1ee422bc-64c1-4da1-b797-62e4d206b79c\",\n    \"013ac760-b99a-423e-bb94-700acda058c0\",\n    \"e72fc432-9b4e-443d-b0c3-619b4a1cff62\",\n    \"1dd3f0dd-4185-43b0-bbf5-a4685099b22a\",\n    \"e1002543-96a9-4d6c-b708-b7c91055f391\",\n    \"f080a424-9da2-499e-98b0-b9219493690c\",\n    \"66237b58-5c5f-4ce1-9f69-13338b363d51\",\n    \"95795513-430f-408c-b4ab-ea08a7744939\",\n    \"5db91b8d-0d36-40fa-861d-d528ac22c1f5\",\n    \"f986bd5c-19a6-4c97-86b7-c07555c37495\",\n    \"2ace745e-05a9-4d2c-9683-343a52ae6e64\",\n    \"6e2abc91-7066-4310-9e17-3441d81c4e63\",\n    \"f0a45c02-54e4-4cd8-8752-d265fa1957bb\",\n    \"10dc7124-99e0-4851-9268-5c5896e4e365\",\n    \"02552438-55e4-4bac-957e-c2d451a70eee\",\n    \"16308874-0ebc-4303-a2ef-ea1e0a987a8f\",\n    \"9ece5292-9874-4b2e-a797-15f542e63467\",\n    \"372bf1ec-da83-4ce0-97d6-484374a74c67\",\n    \"0fe88c72-7bca-4b65-8f2e-46a7b17a5dde\",\n    \"3fc58a2e-79bf-476c-9092-3f658d03536b\",\n    \"e0172dc5-4d03-41d7-b615-1c18b6cbfff7\",\n    \"45920303-286d-467e-a7c4-5afdce1374ba\",\n    \"cfb6d93c-ad4c-4565-971b-df5d5d6da734\",\n    \"d3919111-98e7-409a-b212-0bf453aae0c4\",\n    \"e149cd50-8fc1-40cc-8a8e-5fab20daa8c9\",\n    \"b089a933-a5b7-4a5c-97f2-abfe73d91614\",\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "batch_delete_nodes"
+      ],
+      "source": "src/tools/nodes.ts:932",
+      "symbol": "deleteNode",
+      "returns": "JSON: `{ node, removed_edge_ids }`.",
+      "atomicity": "atomic. Node + cascading edges removed in one mutation."
+    },
+    {
+      "name": "get_node",
+      "description": "Get a single entity by ID, with full properties and all connected edges.",
+      "domain": "nodes",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "node_id": {
+            "type": "string",
+            "description": "The node ID"
+          },
+          "compact_edges": {
+            "type": "boolean",
+            "description": "Omit source_title/target_title from edges (saves ~30% on edge-heavy nodes)"
+          }
+        },
+        "required": [
+          "node_id"
+        ]
+      },
+      "throws": [
+        "Returns a textError when `node_id` is missing or the node does not\nexist."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"node_id\": \"ec3d5479-4947-4bd9-9e77-b5ee01beb851\"\n}",
+          "output": "{\n  \"node\": {\n    \"id\": \"ec3d5479-4947-4bd9-9e77-b5ee01beb851\",\n    \"type\": \"product\",\n    \"title\": \"Notion (SATURATED test graph)\",\n    \"slug\": \"notion-saturated-test-graph\",\n    \"description\": \"Canonical SATURATED test graph for UCS / GPE / .upg-loader / MCP test surfaces. Fictional Notion modelled as a thinly-disguised version of the real Notion. Built via parallel MCP-driven domain waves. Exported as `.upg/notion-saturated.upg` in `the-product-creator` repo at `mr-data/upg-saturated-graph` branch (PR #1532).\",\n    \"properties\": {\n      \"stage\": \"idea\",\n      \"health_status\": \"off_track\",\n      \"url\": \"url sample 10\",\n      \"logo_url\": \"logo url sample 69\",\n      \"launched_at\": \"2026-12-13T09:00:00Z\"\n    }\n  },\n  \"edges_out\": [\n    {\n      \"id\": \"1d645a2e-391b-4bc7-b0de-e15691c8a7d6\",\n      \"source\": \"ec3d5479-4947-4bd9-9e77-b5ee01beb851\",\n      \"target\": \"dce7a627-2ef4-4cb7-a63a-5044a8ad1802\",\n      \"type\": \"product_serves_account\",\n      \"target_title\": \"Acme Corp Enterprise Workspace\"\n    },\n    {\n      \"id\": \"b4a77a49-7d28-4926-831f-464574d927fe\",\n      \"source\": \"ec3d5479-4947-4bd9-9e77-b5ee01beb851\",\n      \"target\": \"2a3ab02e-4110-43f2-848b-a1ebeedb6fa9\",\n      \"type\": \"product_shares_metric_with_product\",\n      \"target_title\": \"Notion Mail (preview)\"\n    },\n    {\n      \"id\": \"1ee422bc-64c1-4da1-b797-62e4d206b79c\",\n      \"source\":\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "get_nodes"
+      ],
+      "source": "src/tools/nodes.ts:206",
+      "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).",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "get_nodes",
+      "description": "Batch-fetch up to 50 entities by ID. Returns each node with its edges. Use instead of looping `get_node`.",
+      "domain": "nodes",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Array of node IDs to fetch (max 50)"
+          },
+          "compact_edges": {
+            "type": "boolean",
+            "description": "Omit titles from edges"
+          }
+        },
+        "required": [
+          "ids"
+        ]
+      },
+      "throws": [
+        "Returns a textError when `ids` is missing/empty or longer than 50."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"ids\": [\n    \"ec3d5479-4947-4bd9-9e77-b5ee01beb851\",\n    \"1c051617-6cb7-4a59-b0a1-7779f404145b\"\n  ]\n}",
+          "output": "{\n  \"nodes\": [\n    {\n      \"node\": {\n        \"id\": \"ec3d5479-4947-4bd9-9e77-b5ee01beb851\",\n        \"type\": \"product\",\n        \"title\": \"Notion (SATURATED test graph)\",\n        \"slug\": \"notion-saturated-test-graph\"\n      },\n      \"edges_out\": [\n        {\n          \"id\": \"1d645a2e-391b-4bc7-b0de-e15691c8a7d6\",\n          \"type\": \"product_serves_account\",\n          \"source\": \"ec3d5479-4947-4bd9-9e77-b5ee01beb851\",\n          \"target\": \"dce7a627-2ef4-4cb7-a63a-5044a8ad1802\"\n        },\n        {\n          \"id\": \"b4a77a49-7d28-4926-831f-464574d927fe\",\n          \"type\": \"product_shares_metric_with_product\",\n          \"source\": \"ec3d5479-4947-4bd9-9e77-b5ee01beb851\",\n          \"target\": \"2a3ab02e-4110-43f2-848b-a1ebeedb6fa9\"\n        },\n        {\n          \"id\": \"1ee422bc-64c1-4da1-b797-62e4d206b79c\",\n          \"type\": \"product_ships_via_release\",\n          \"source\": \"ec3d5479-4947-4bd9-9e77-b5ee01beb851\",\n          \"target\": \"024aa3ef-d8e0-4791-8979-c8a9f2a69618\"\n        },\n        {\n          \"id\": \"013ac760-b99a-423e-bb94-700acda058c0\",\n          \"type\": \"product_sold_via_pipeline_sales\",\n          \"source\": \"ec3d5479-4947-4bd9-9e77-b5ee01beb851\",\n          \"target\": \"8737db50-a948-4225-9fa6-7a54ca4ca374\"\n        },\n        {\n          \"id\": \"e72fc432-9b4e-443d-b0c3-619b4a1cff62\",\n          \"type\": \"product_stored_in_code_repository\",\n          \"source\":\n… (truncated)"
+        }
+      ],
+      "warnings": [
+        "Pre-flight payload guardrail: refuses above\n`UPG_MCP_PAYLOAD_HARD_LIMIT` (default 150 KB), warns above\n`UPG_MCP_PAYLOAD_SOFT_LIMIT` (default 50 KB). 50 edge-heavy nodes can\nstill cross 50 KB. Pass `compact_edges:true` to halve edge size.",
+        "Auto-degrade: between soft and hard limits, the server\nmay drop edge titles, optional node fields, or truncate the result list.\nSurfaced as `degraded.applied[]` on the response."
+      ],
+      "see": [
+        "get_node"
+      ],
+      "source": "src/tools/nodes.ts:250",
+      "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.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "list_nodes",
+      "description": "List entities with filtering, edge inclusion, count-only mode, and pagination. For graph-wide edge enumeration, prefer `export_edges` (flat) or `query` (traversal). `list_nodes(include_edges:true)` is for entity-scoped reads.",
+      "domain": "nodes",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string",
+            "description": "Filter by entity type"
+          },
+          "status": {
+            "type": "string",
+            "description": "Filter by status value"
+          },
+          "tags": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Filter by tags (matches any)"
+          },
+          "parent_id": {
+            "type": "string",
+            "description": "Filter to children of this node (connected by outgoing edge from parent)"
+          },
+          "include_edges": {
+            "type": "boolean",
+            "description": "Include compact edge data (id, type, source, target) per node"
+          },
+          "count_only": {
+            "type": "boolean",
+            "description": "Return only the total count, no node data"
+          },
+          "offset": {
+            "type": "number",
+            "description": "Skip N results (default 0)"
+          },
+          "limit": {
+            "type": "number",
+            "description": "Max results (default 50, max 200)"
+          },
+          "if_changed_since": {
+            "type": "string",
+            "description": "Hash from a previous response. Returns { changed: false } if graph unchanged."
+          }
+        }
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"nodes\": [\n    {\n      \"id\": \"ec3d5479-4947-4bd9-9e77-b5ee01beb851\",\n      \"type\": \"product\",\n      \"title\": \"Notion (SATURATED test graph)\"\n    },\n    {\n      \"id\": \"1c051617-6cb7-4a59-b0a1-7779f404145b\",\n      \"type\": \"capability\",\n      \"title\": \"Real-time multi-cursor collaboration\"\n    },\n    {\n      \"id\": \"478852b7-ca46-4bdd-85fa-cd2334b9565d\",\n      \"type\": \"capability\",\n      \"title\": \"Block-based composable editing\"\n    },\n    {\n      \"id\": \"0904ef52-cc7e-4bcd-9c9d-0072beb28878\",\n      \"type\": \"capability\",\n      \"title\": \"Tree-inherited permissions\"\n    },\n    {\n      \"id\": \"f8ce72c1-af1a-48ba-945e-72e08c5aeeb5\",\n      \"type\": \"capability\",\n      \"title\": \"Permission-aware AI grounding\"\n    },\n    {\n      \"id\": \"4dffea49-4122-4599-858c-f3c2f0c3e5c4\",\n      \"type\": \"value_stream\",\n      \"title\": \"Personal → Team conversion stream\"\n    },\n    {\n      \"id\": \"9d03304e-8beb-4734-845b-1bc3c07ce20c\",\n      \"type\": \"decision\",\n      \"title\": \"Build Frankfurt region (not partner)\"\n    },\n    {\n      \"id\": \"6ea52729-4462-4fc0-b2a1-0c7e2c0362b2\",\n      \"type\": \"evidence\",\n      \"title\": \"Self-hostable waitlist: 1.2k signups, 0% paid intent\"\n    },\n    {\n      \"id\": \"3f1c1804-b33b-4b1f-9094-c91cc8957912\",\n      \"type\": \"assumption\",\n      \"title\": \"Teams prefer one tool over a stack of four\"\n    },\n    {\n      \"id\": \"6719fce7-61e7-44df-b6cf-92f7c7312554\",\n      \"type\":\n… (truncated)"
+        }
+      ],
+      "warnings": [
+        "Pre-flight payload guardrail: refuses with a steering\nerror when the estimated response exceeds `UPG_MCP_PAYLOAD_HARD_LIMIT`\n(default 150 KB), and attaches a `_warning` field above\n`UPG_MCP_PAYLOAD_SOFT_LIMIT` (default 50 KB). For graph-wide reads,\nprefer `query` with a tight projection.",
+        "Auto-degrade: between the soft and hard limits, the\nresponse is automatically truncated. Surfaced as\n`degraded.applied: ['truncate_at_count_auto']` on the response."
+      ],
+      "see": [
+        "search_nodes",
+        "query"
+      ],
+      "source": "src/tools/nodes.ts:106",
+      "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.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "migrate_properties",
+      "description": "Apply `UPG_PROPERTY_MIGRATIONS` graph-wide with no type rename or edge migration. Pure property pass: `drop_props`, `rename_top_level`, `lift_property_to_top_level`, `drop_when_self_referential`. Default `dry_run=true` previews the per-rule change set; pass `dry_run=false` to commit. Use when you want property cleanup standalone; `migrate_type` folds the same pass into its rename.",
+      "domain": "nodes",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "dry_run": {
+            "type": "boolean",
+            "description": "Preview changes without applying (default true). Pass false to commit."
+          }
+        }
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"top_level_renames\": [],\n  \"lifted_properties\": [\n    {\n      \"id\": \"ec3d5479-4947-4bd9-9e77-b5ee01beb851\",\n      \"from_property\": \"stage\",\n      \"to\": \"status\",\n      \"value_changed\": true\n    },\n    {\n      \"id\": \"3f1c1804-b33b-4b1f-9094-c91cc8957912\",\n      \"from_property\": \"validation_status\",\n      \"to\": \"status\",\n      \"value_changed\": false\n    },\n    {\n      \"id\": \"6719fce7-61e7-44df-b6cf-92f7c7312554\",\n      \"from_property\": \"validation_status\",\n      \"to\": \"status\",\n      \"value_changed\": false\n    },\n    {\n      \"id\": \"7b22f5f3-b344-4e49-8d5a-35cf9087dc6c\",\n      \"from_property\": \"validation_status\",\n      \"to\": \"status\",\n      \"value_changed\": false\n    },\n    {\n      \"id\": \"c969753e-8e7b-4c14-9c99-acba5b1862be\",\n      \"from_property\": \"validation_status\",\n      \"to\": \"status\",\n      \"value_changed\": false\n    },\n    {\n      \"id\": \"6bc0cfd3-29a2-47b5-8f2e-746ded26351f\",\n      \"from_property\": \"validation_status\",\n      \"to\": \"status\",\n      \"value_changed\": false\n    },\n    {\n      \"id\": \"2326222c-cfab-4793-bf58-818039939753\",\n      \"from_property\": \"bug_status\",\n      \"to\": \"status\",\n      \"value_changed\": false\n    },\n    {\n      \"id\": \"1373c0c9-4aba-49fc-8a26-bbc78661ca5a\",\n      \"from_property\": \"bug_status\",\n      \"to\": \"status\",\n      \"value_changed\": false\n    },\n    {\n      \"id\": \"655c81dc-f827-45e3-b871-d9c78e569076\",\n      \"from_property\":\n… (truncated)"
+        }
+      ],
+      "warnings": [
+        "Default is `dry_run: true`. Pass `dry_run: false` to commit.\nRe-running with `dry_run: true` after a successful commit reports zero\nchanges (idempotent on the canonical-properties shape)."
+      ],
+      "see": [
+        "migrate_type",
+        "validate_graph",
+        "list_type_migrations"
+      ],
+      "source": "src/tools/nodes.ts:1253",
+      "symbol": "migrateProperties",
+      "returns": "JSON: `{ top_level_renames, lifted_properties, dropped_props,\ndropped_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_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.",
+      "domain": "nodes",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "from_type": {
+            "type": "string",
+            "description": "The current entity type to migrate FROM"
+          },
+          "to_type": {
+            "type": "string",
+            "description": "The new entity type to migrate TO"
+          },
+          "dry_run": {
+            "type": "boolean",
+            "description": "Preview changes without applying (default false)"
+          }
+        },
+        "required": [
+          "from_type",
+          "to_type"
+        ]
+      },
+      "throws": [
+        "Returns a textError when `from_type` or `to_type` is missing."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"from_type\": \"jtbd\",\n  \"to_type\": \"job\",\n  \"dry_run\": true\n}",
+          "output": "{\n  \"migrated_nodes\": 0,\n  \"migrated_edges\": 0,\n  \"edge_renames\": [],\n  \"dropped_edges\": [],\n  \"unmapped_legacy_edges\": [],\n  \"defaults_applied\": null,\n  \"dry_run\": true\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "rename_edge_type",
+        "export_edges",
+        "update_node"
+      ],
+      "source": "src/tools/nodes.ts:1116",
+      "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).",
+      "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."
+    },
+    {
+      "name": "query",
+      "description": "Traverse the graph following typed edges. Returns a subgraph (nodes + edges) in a single call. Example: query({ from: \"persona\", traverse: [\"persona_pursues_job\", \"job_surfaces_need\"], depth: 2 })",
+      "domain": "nodes",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "from": {
+            "type": "string",
+            "description": "Start from all nodes of this type"
+          },
+          "from_id": {
+            "type": "string",
+            "description": "Start from a specific node ID (alternative to from)"
+          },
+          "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 (e.g. \"!product_builds_feature\")."
+          },
+          "depth": {
+            "type": "number",
+            "description": "Max traversal depth (default 3, max 10)"
+          },
+          "include": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Fields to include per node: \"title\", \"status\", \"tags\", \"description\", \"properties\" (default: title, status, type)"
+          },
+          "limit": {
+            "type": "number",
+            "description": "Max nodes to return (default 200, 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 (e.g. [\"severity\", \"importance\"])"
+          },
+          "diff_from": {
+            "type": "string",
+            "description": "Result ID from a previous query. Returns only added/removed nodes since that result."
+          }
+        }
+      },
+      "throws": [
+        "Returns a textError when neither `from` nor `from_id` is provided,\nor when `from_id` does not exist."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"from\": \"persona\",\n  \"traverse\": [\n    \"persona_pursues_job\"\n  ],\n  \"depth\": 1,\n  \"limit\": 5,\n  \"include\": [\n    \"title\"\n  ],\n  \"edge_include\": []\n}",
+          "output": "{\n  \"nodes\": [\n    {\n      \"id\": \"9cd363dc-b1be-4132-b1dc-043467866e57\",\n      \"type\": \"persona\",\n      \"title\": \"Akira the Admin\"\n    },\n    {\n      \"id\": \"65234b60-eb2b-4c41-be63-7b17b2bc6a38\",\n      \"type\": \"persona\",\n      \"title\": \"Theo the Consultant\"\n    },\n    {\n      \"id\": \"e956a8ef-288f-4ee2-b758-2a14b9d07206\",\n      \"type\": \"persona\",\n      \"title\": \"Lin the Thinker\"\n    },\n    {\n      \"id\": \"2e8dd86d-6085-4068-a804-38d3e891ea1b\",\n      \"type\": \"persona\",\n      \"title\": \"Maya the Maker\"\n    },\n    {\n      \"id\": \"7b2e7c5a-a73e-42c9-9416-e9e9ccfecc20\",\n      \"type\": \"job\",\n      \"title\": \"Build a team system that survives growth\"\n    }\n  ],\n  \"edges\": [],\n  \"total_nodes\": 5,\n  \"total_edges\": 0,\n  \"truncated\": true,\n  \"truncated_at_depth\": 0,\n  \"hint\": \"Limit of 5 nodes reached at depth 0. Increase limit to see deeper results.\",\n  \"_result_id\": \"qr_1\"\n}"
+        }
+      ],
+      "warnings": [
+        "Pre-flight payload guardrail: refuses above\n`UPG_MCP_PAYLOAD_HARD_LIMIT` (default 150 KB), warns above\n`UPG_MCP_PAYLOAD_SOFT_LIMIT` (default 50 KB). Tighten with `include`\n(e.g. `[\"title\"]`) or `edge_include: []` to drop edges from the wire."
+      ],
+      "see": [
+        "list_nodes",
+        "get_area_graph"
+      ],
+      "source": "src/tools/nodes.ts:405",
+      "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.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "search_nodes",
+      "description": "Search entities by text. Default fields: title (score 3) and description (score 1). Add `fields` to include tags (score 2) and properties (score 1). Results include `matched_field`.",
+      "domain": "nodes",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "query": {
+            "type": "string",
+            "description": "Search text (case-insensitive substring match)"
+          },
+          "type": {
+            "type": "string",
+            "description": "Optional type filter"
+          },
+          "fields": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Fields to search: \"title\", \"description\", \"tags\", \"properties\" (default: title + description)"
+          },
+          "limit": {
+            "type": "number",
+            "description": "Max results (default 20, max 100)"
+          }
+        },
+        "required": [
+          "query"
+        ]
+      },
+      "throws": [
+        "Returns a textError when `query` is missing."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"query\": \"Notion\"\n}",
+          "output": "{\n  \"results\": [\n    {\n      \"id\": \"ec3d5479-4947-4bd9-9e77-b5ee01beb851\",\n      \"type\": \"product\",\n      \"title\": \"Notion (SATURATED test graph)\",\n      \"match_field\": \"title\",\n      \"score\": 3\n    },\n    {\n      \"id\": \"7f5ae55d-68c5-4ca7-9e4c-b5e9d4dd32a5\",\n      \"type\": \"design_system\",\n      \"title\": \"Notion Design System · Block-primitive foundation\",\n      \"match_field\": \"title\",\n      \"score\": 3\n    },\n    {\n      \"id\": \"24b43d57-48a4-4499-bac7-e38f3eb7bae4\",\n      \"type\": \"design_system\",\n      \"title\": \"Notion Design System · Database views\",\n      \"match_field\": \"title\",\n      \"score\": 3\n    },\n    {\n      \"id\": \"6700fd68-27be-4b21-9186-82e490bebf33\",\n      \"type\": \"workspace\",\n      \"title\": \"Notion Internal · Architecture Decisions workspace\",\n      \"match_field\": \"title\",\n      \"score\": 3\n    },\n    {\n      \"id\": \"c355f3ea-1e9f-45a1-aedc-a7adf66050e1\",\n      \"type\": \"product\",\n      \"title\": \"Notion Calendar\",\n      \"match_field\": \"title\",\n      \"score\": 3\n    },\n    {\n      \"id\": \"2a3ab02e-4110-43f2-848b-a1ebeedb6fa9\",\n      \"type\": \"product\",\n      \"title\": \"Notion Mail (preview)\",\n      \"match_field\": \"title\",\n      \"score\": 3\n    },\n    {\n      \"id\": \"e83e8cec-8f00-4dd5-b36a-c5e143f7e911\",\n      \"type\": \"design_system\",\n      \"title\": \"Notion Design System · Mobile parity tokens\",\n      \"match_field\": \"title\",\n      \"score\": 3\n    },\n    {\n      \"id\":\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "list_nodes",
+        "query"
+      ],
+      "source": "src/tools/nodes.ts:354",
+      "symbol": "searchNodes",
+      "returns": "JSON: `{ results: Array<{ id, type, title, status, tags,\nmatch_field, score }>, total, searched_fields }`.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "update_node",
+      "description": "Update one entity. Unspecified fields are preserved. Passing `type` performs an atomic single-node migration: every incident edge is re-inferred against the catalog and rollback applies on failure. For 3+ entities, use `batch_update_nodes`.",
+      "domain": "nodes",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "node_id": {
+            "type": "string",
+            "description": "The node ID to update"
+          },
+          "type": {
+            "type": "string",
+            "description": "Change the entity type. Atomic single-node migration: validates against UPG_TYPES, rewrites incident edges to canonical types."
+          },
+          "title": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "tags": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "status": {
+            "type": "string"
+          },
+          "properties": {
+            "type": "object",
+            "description": "Merged with existing properties"
+          }
+        },
+        "required": [
+          "node_id"
+        ]
+      },
+      "throws": [
+        "Returns a textError when `node_id` is missing, the type migration\nfails, when `strict: true` and unknown properties are present, or when\nthe underlying store rejects the patch."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"node_id\": \"ec3d5479-4947-4bd9-9e77-b5ee01beb851\"\n}",
+          "output": "{\n  \"node\": {\n    \"id\": \"ec3d5479-4947-4bd9-9e77-b5ee01beb851\",\n    \"type\": \"product\",\n    \"title\": \"Notion (SATURATED test graph)\",\n    \"slug\": \"notion-saturated-test-graph\"\n  }\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "migrate_type",
+        "batch_update_nodes"
+      ],
+      "source": "src/tools/nodes.ts:841",
+      "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.",
+      "atomicity": "atomic-with-rollback (when `type` is changed); atomic for\nshallow-merge patches."
+    },
+    {
+      "name": "batch_create_edges",
+      "description": "Create up to 50 edges in one atomic call. Use this for 3+ edges instead of looping `create_edge`. Edge type auto-infers when omitted.",
+      "domain": "edges",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "edges": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "source_id": {
+                  "type": "string",
+                  "description": "Source node ID"
+                },
+                "target_id": {
+                  "type": "string",
+                  "description": "Target node ID"
+                },
+                "type": {
+                  "type": "string",
+                  "description": "Edge type. Auto-inferred if omitted."
+                }
+              },
+              "required": [
+                "source_id",
+                "target_id"
+              ]
+            },
+            "description": "Array of edges to create (max 50)"
+          }
+        },
+        "required": [
+          "edges"
+        ]
+      },
+      "throws": [
+        "Returns a textError when `edges` is missing/non-array, empty,\nlonger than 50, or any item references a missing endpoint or unresolvable\nedge type."
+      ],
+      "examples": [],
+      "warnings": [],
+      "see": [
+        "create_edge"
+      ],
+      "source": "src/tools/edges.ts:209",
+      "symbol": "batchCreateEdges",
+      "returns": "JSON: `{ created, count }`.",
+      "atomicity": "atomic. Full validation pass before any mutation lands."
+    },
+    {
+      "name": "batch_delete_edges",
+      "description": "Delete up to 50 edges in one atomic call (all succeed or all fail).",
+      "domain": "edges",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "edge_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Array of edge IDs to delete (max 50)"
+          }
+        },
+        "required": [
+          "edge_ids"
+        ]
+      },
+      "throws": [
+        "Returns a textError when `edge_ids` is missing/non-array, empty,\nlonger than 50, or any ID does not resolve."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"edge_ids\": [\n    \"8a3b23fd-172e-4151-8283-aee40eeb4c0d\"\n  ]\n}",
+          "output": "{\n  \"deleted\": [\n    {\n      \"id\": \"8a3b23fd-172e-4151-8283-aee40eeb4c0d\",\n      \"type\": \"opportunity_drives_solution\"\n    }\n  ],\n  \"count\": 1\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "delete_edge"
+      ],
+      "source": "src/tools/edges.ts:293",
+      "symbol": "batchDeleteEdges",
+      "returns": "JSON: `{ deleted, count }`.",
+      "atomicity": "atomic. Validation pass rejects the batch before any mutation\nlands."
+    },
+    {
+      "name": "batch_move_nodes",
+      "description": "Apply up to 50 atomic re-parents. All moves validate against the schema first; any failure rolls back the whole batch.",
+      "domain": "edges",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "moves": {
+            "type": "array",
+            "maxItems": 50,
+            "items": {
+              "type": "object",
+              "properties": {
+                "node_id": {
+                  "type": "string"
+                },
+                "new_parent_id": {
+                  "type": "string"
+                },
+                "new_edge_type": {
+                  "type": "string"
+                },
+                "old_edge_id": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "node_id",
+                "new_parent_id"
+              ]
+            }
+          }
+        },
+        "required": [
+          "moves"
+        ]
+      },
+      "throws": [
+        "Returns a textError when `moves` is missing/non-array or any move\nfails validation."
+      ],
+      "examples": [],
+      "warnings": [],
+      "see": [
+        "move_node"
+      ],
+      "source": "src/tools/edges.ts:177",
+      "symbol": "batchMoveNodes",
+      "returns": "JSON: `{ moves, warnings? }` mirroring the per-move result of\n`move_node`.",
+      "atomicity": "atomic-with-rollback."
+    },
+    {
+      "name": "create_edge",
+      "description": "Create one edge between two nodes. Edge type auto-infers when omitted. Target accepts an ID, or a title+type pair the server resolves. For 3+ edges, use `batch_create_edges`.",
+      "domain": "edges",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "source_id": {
+            "type": "string",
+            "description": "Source node ID"
+          },
+          "target_id": {
+            "type": "string",
+            "description": "Target node ID"
+          },
+          "target_title": {
+            "type": "string",
+            "description": "Target node title (alternative to target_id; requires target_type)."
+          },
+          "target_type": {
+            "type": "string",
+            "description": "Target node type (used with target_title for resolution)"
+          },
+          "type": {
+            "type": "string",
+            "description": "Edge type. Auto-inferred if omitted."
+          }
+        },
+        "required": [
+          "source_id"
+        ]
+      },
+      "throws": [
+        "Returns a textError when `source_id` is missing, the target cannot\nbe resolved, or the edge violates the catalog."
+      ],
+      "examples": [
+        "// Wire a persona to a job using the canonical edge type persona_pursues_job\n// Input:\n{ \"source_id\": \"persona_01\", \"target_id\": \"job_03\", \"type\": \"persona_pursues_job\" }\n// Output (truncated):\n{\n  \"edge\": { \"id\": \"edge_15\", \"type\": \"persona_pursues_job\", \"source\": \"persona_01\", \"target\": \"job_03\" },\n  \"inferred\": false\n}"
+      ],
+      "warnings": [],
+      "see": [
+        "batch_create_edges",
+        "resolve_edge_for_pair",
+        "list_edge_types",
+        "get_edge_type"
+      ],
+      "source": "src/tools/edges.ts:85",
+      "symbol": "createEdge",
+      "returns": "JSON: the created edge object plus optional resolution metadata.",
+      "atomicity": "atomic. Single store mutation."
+    },
+    {
+      "name": "delete_edge",
+      "description": "Remove one edge by ID.",
+      "domain": "edges",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "edge_id": {
+            "type": "string",
+            "description": "The edge ID to delete"
+          }
+        },
+        "required": [
+          "edge_id"
+        ]
+      },
+      "throws": [
+        "Returns a textError when `edge_id` is missing or does not resolve."
+      ],
+      "examples": [],
+      "warnings": [],
+      "see": [
+        "batch_delete_edges",
+        "export_edges",
+        "repair_dangling_edges"
+      ],
+      "source": "src/tools/edges.ts:122",
+      "symbol": "deleteEdge",
+      "returns": "JSON: the removed edge object.",
+      "atomicity": "atomic."
+    },
+    {
+      "name": "export_edges",
+      "description": "Flat edge enumeration. Returns every edge of the listed `types` (or all edges when `types` is omitted) as `{id, source, target, type}` with no parent-node payload. Right for migration and canonicalisation passes. Paginates via offset/limit.",
+      "domain": "edges",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "types": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Filter by exact edge-type match. Omit to enumerate every edge in the document."
+          },
+          "offset": {
+            "type": "number",
+            "description": "Skip N results (default 0)"
+          },
+          "limit": {
+            "type": "number",
+            "description": "Max results (default 500, max 2000)"
+          },
+          "if_changed_since": {
+            "type": "string",
+            "description": "Hash from a previous response. Returns { changed: false } if graph unchanged."
+          }
+        }
+      },
+      "throws": [
+        "Returns a textError when `types` is supplied but is not an array of\nstrings, or when the page would exceed the hard payload limit."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"edges\": [\n    {\n      \"id\": \"44012ce7-99d5-4a96-b930-c8f7b1d6b45f\",\n      \"source\": \"3197ef3e-4ffc-48cf-9903-59db8eed94f8\",\n      \"target\": \"a719b36e-97a9-4927-b27c-f95f0da05d8c\",\n      \"type\": \"opportunity_drives_solution\"\n    },\n    {\n      \"id\": \"d7aaba50-cf2e-4a46-ac1b-15e61aa49212\",\n      \"source\": \"d8c4bbfb-669d-4e29-b75e-fba353455255\",\n      \"target\": \"d272290a-7006-4372-b4f4-0deb59161d39\",\n      \"type\": \"opportunity_drives_solution\"\n    },\n    {\n      \"id\": \"4c3e592e-61f3-4d7d-a7c9-486fa3a5cb6d\",\n      \"source\": \"88766ab4-a3e7-40be-bffa-469882937e47\",\n      \"target\": \"d8b467ef-9b3f-4d52-994e-ada00327f73e\",\n      \"type\": \"opportunity_drives_solution\"\n    },\n    {\n      \"id\": \"676dcc0e-7fa6-46c0-b0d3-0c4cc0e10982\",\n      \"source\": \"b5df3308-dc29-4958-aae7-123bc616217d\",\n      \"target\": \"425b4721-6c79-4da7-9b94-a66f97d308ed\",\n      \"type\": \"opportunity_drives_solution\"\n    },\n    {\n      \"id\": \"6e4b2226-2d47-4e3a-ba14-4291a2e8896b\",\n      \"source\": \"3197ef3e-4ffc-48cf-9903-59db8eed94f8\",\n      \"target\": \"b17e4f0e-5ed2-4170-a754-b17cafb42b21\",\n      \"type\": \"opportunity_assessed_by_feasibility_study\"\n    },\n    {\n      \"id\": \"5101bf03-3d91-4da1-b3e8-33363a117227\",\n      \"source\": \"87d8086c-ac51-4021-882a-7728c394f6ab\",\n      \"target\": \"dade8cd7-ffae-4800-9f72-c8767520a21c\",\n      \"type\": \"opportunity_assessed_by_feasibility_study\"\n    },\n    {\n      \"id\":\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "query",
+        "list_nodes"
+      ],
+      "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? }`.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "move_node",
+      "description": "Atomic re-parent. Removes any existing hierarchy edge and creates a new one to `new_parent_id`. Validates against `UPG_EDGE_CATALOG` first; rolls back fully on failure.",
+      "domain": "edges",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "node_id": {
+            "type": "string",
+            "description": "The node to re-parent"
+          },
+          "new_parent_id": {
+            "type": "string",
+            "description": "The new parent node id"
+          },
+          "new_edge_type": {
+            "type": "string",
+            "description": "Optional override. Must be a key in UPG_EDGE_CATALOG. If omitted, the edge type is inferred from new_parent.type → node.type."
+          },
+          "old_edge_id": {
+            "type": "string",
+            "description": "Required when the node has more than one hierarchy edge. Picks which one to delete."
+          }
+        },
+        "required": [
+          "node_id",
+          "new_parent_id"
+        ]
+      },
+      "throws": [
+        "Returns a textError when `node_id` or `new_parent_id` is missing,\nwhen the inferred edge type is invalid, or when the node has multiple\nhierarchy edges and `old_edge_id` was not supplied."
+      ],
+      "examples": [],
+      "warnings": [],
+      "see": [
+        "batch_move_nodes"
+      ],
+      "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.",
+      "atomicity": "atomic-with-rollback. Pre-validates the new edge before\ntouching the old one."
+    },
+    {
+      "name": "rename_edge_type",
+      "description": "Exact-match rename of every edge of type `from` to type `to`, optionally flipping source/target. Single transactional pass. Defaults to `dry_run: true`; pass `dry_run: false` to commit. Low-level primitive: skips catalog validation. Use catalog-aware migration tools for validated renames.",
+      "domain": "edges",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "from": {
+            "type": "string",
+            "description": "Current edge type (exact match)"
+          },
+          "to": {
+            "type": "string",
+            "description": "New edge type to assign"
+          },
+          "flip": {
+            "type": "boolean",
+            "description": "When true, swap source/target on each renamed edge (default false)"
+          },
+          "dry_run": {
+            "type": "boolean",
+            "description": "Preview without mutating (default true)"
+          }
+        },
+        "required": [
+          "from",
+          "to"
+        ]
+      },
+      "throws": [
+        "Returns a textError when `from` or `to` is missing, when they are\nequal and `flip` is false (no-op), or when `from === to` with `flip: true`\non zero matches (still safe but the call is degenerate)."
+      ],
+      "examples": [],
+      "warnings": [],
+      "see": [
+        "migrate_type",
+        "export_edges"
+      ],
+      "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 }`.",
+      "atomicity": "atomic. Single-pass mutation; an empty match-set is a clean\nno-op rather than an error."
+    },
+    {
+      "name": "repair_dangling_edges",
+      "description": "Inspect or drop edges whose source or target node fails to resolve. Each is classified `expected` (cross-product, sibling not loaded; keep), `suspect` (cross-product, missing product-id annotation), or `corrupt` (broken endpoint on a non-cross edge). Defaults to `dry_run: true`. Pass `dry_run: false` plus `drop: [\"suspect\", \"corrupt\"]` to remove.",
+      "domain": "edges",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "dry_run": {
+            "type": "boolean",
+            "description": "When true (default), returns the classification report without mutating. When false, drops edges matching `drop`."
+          },
+          "drop": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "expected",
+                "suspect",
+                "corrupt"
+              ]
+            },
+            "description": "Classes of dangling edge to drop. Only honoured when dry_run is false. Omit to no-op."
+          }
+        }
+      },
+      "throws": [
+        "Returns a textError when `drop` is provided alongside\n`dry_run: true` (ambiguous), or when `drop` includes an unknown class."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"dry_run\": true,\n  \"report\": {\n    \"total\": 0,\n    \"by_class\": {\n      \"expected\": 0,\n      \"suspect\": 0,\n      \"corrupt\": 0\n    },\n    \"edges\": []\n  }\n}"
+        }
+      ],
+      "warnings": [
+        "Dropping `corrupt` edges is irreversible. The integrity stamp is\nre-computed on next save; a subsequent reload won't bring them back."
+      ],
+      "see": [],
+      "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.",
+      "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."
+    },
+    {
+      "name": "create_area",
+      "description": "Create a product area entity in the portfolio document (`.upg/portfolio.upg`). Product areas represent the organisational axis (who owns what). Supports nesting via `parent_area_id`. The portfolio document is created on demand.",
+      "domain": "areas",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "title": {
+            "type": "string",
+            "description": "Area name (e.g. \"Search\", \"Payments\")"
+          },
+          "description": {
+            "type": "string",
+            "description": "What this area covers"
+          },
+          "parent_area_id": {
+            "type": "string",
+            "description": "Parent area ID for creating a sub-area"
+          },
+          "strategic_priority": {
+            "type": "string",
+            "enum": [
+              "critical",
+              "high",
+              "medium",
+              "low"
+            ],
+            "description": "Strategic priority of this area"
+          },
+          "owner": {
+            "type": "string",
+            "description": "Person or team that owns this area"
+          }
+        },
+        "required": [
+          "title"
+        ]
+      },
+      "throws": [
+        "Returns a textError when `title` is missing or the portfolio write\nfails."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"title\": \"Example node\"\n}",
+          "output": "{\n  \"node\": {\n    \"id\": \"n_cyDWeH77JTYEF4t_\",\n    \"title\": \"Example node\"\n  },\n  \"portfolio_file\": \"/Users/FH/Documents/_Code/tpc-worktrees/wt-cli-section/packages/upg-mcp-server/.upg/portfolio.upg\",\n  \"written_to\": \"product_areas\"\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "list_product_areas"
+      ],
+      "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[]`.",
+      "atomicity": "atomic per write — the portfolio file is read, mutated, and\nflushed in one pass."
+    },
+    {
+      "name": "get_area_context",
+      "description": "Check whether the current working directory has a `.upg-area.json` that scopes work to a specific product area.",
+      "domain": "areas",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"has_area_context\": false\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [],
+      "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 }`.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "get_area_graph",
+      "description": "Return the sub-graph (entities and edges) scoped to a product area.",
+      "domain": "areas",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "area_id": {
+            "type": "string",
+            "description": "The product area node ID"
+          },
+          "depth": {
+            "type": "number",
+            "description": "How many levels deep to traverse (default 3, max 10)"
+          }
+        },
+        "required": [
+          "area_id"
+        ]
+      },
+      "throws": [
+        "Returns a textError when `area_id` is missing, the node does not\nexist, or the node is not a `product_area`."
+      ],
+      "examples": [],
+      "warnings": [
+        "Pre-flight payload guardrail: refuses above\n`UPG_MCP_PAYLOAD_HARD_LIMIT` (default 150 KB), warns above\n`UPG_MCP_PAYLOAD_SOFT_LIMIT` (default 50 KB). Reduce `depth` or use\n`query` with a tight projection if the area has many neighbours.",
+        "Auto-degrade: between soft and hard, the server may\ncompact edges, drop optional node fields, or truncate. Surfaced as\n`degraded.applied[]` on the response."
+      ],
+      "see": [
+        "list_product_areas"
+      ],
+      "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.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "get_changes",
+      "description": "Mutation log for this session. Verify what was created, updated, or deleted without re-fetching.",
+      "domain": "areas",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "since": {
+            "type": "string",
+            "description": "ISO 8601 timestamp. Only returns changes after this time (default: all session changes)."
+          }
+        }
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"changes\": [\n    {\n      \"action\": \"create\",\n      \"entity\": \"node\",\n      \"id\": \"n_LSjd64yzUUdx5X9r\",\n      \"type\": \"person\",\n      \"title\": \"Example node\",\n      \"timestamp\": \"2026-05-26T13:23:52.872Z\"\n    },\n    {\n      \"action\": \"update\",\n      \"entity\": \"node\",\n      \"id\": \"ec3d5479-4947-4bd9-9e77-b5ee01beb851\",\n      \"type\": \"product\",\n      \"title\": \"Notion (SATURATED test graph)\",\n      \"timestamp\": \"2026-05-26T13:23:52.873Z\"\n    },\n    {\n      \"action\": \"delete\",\n      \"entity\": \"node\",\n      \"id\": \"ec3d5479-4947-4bd9-9e77-b5ee01beb851\",\n      \"type\": \"product\",\n      \"title\": \"Notion (SATURATED test graph)\",\n      \"timestamp\": \"2026-05-26T13:23:52.874Z\"\n    },\n    {\n      \"action\": \"delete\",\n      \"entity\": \"edge\",\n      \"id\": \"1d645a2e-391b-4bc7-b0de-e15691c8a7d6\",\n      \"type\": \"cascade\",\n      \"timestamp\": \"2026-05-26T13:23:52.874Z\"\n    },\n    {\n      \"action\": \"delete\",\n      \"entity\": \"edge\",\n      \"id\": \"b4a77a49-7d28-4926-831f-464574d927fe\",\n      \"type\": \"cascade\",\n      \"timestamp\": \"2026-05-26T13:23:52.874Z\"\n    },\n    {\n      \"action\": \"delete\",\n      \"entity\": \"edge\",\n      \"id\": \"1ee422bc-64c1-4da1-b797-62e4d206b79c\",\n      \"type\": \"cascade\",\n      \"timestamp\": \"2026-05-26T13:23:52.874Z\"\n    },\n    {\n      \"action\": \"delete\",\n      \"entity\": \"edge\",\n      \"id\": \"013ac760-b99a-423e-bb94-700acda058c0\",\n      \"type\": \"cascade\",\n      \"timestamp\":\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [],
+      "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.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "list_product_areas",
+      "description": "List product areas from the portfolio document (`.upg/portfolio.upg`). Returns an empty list when no portfolio document exists yet.",
+      "domain": "areas",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"areas\": [],\n  \"total\": 0\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "create_area",
+        "get_area_graph"
+      ],
+      "source": "src/tools/areas.ts:33",
+      "symbol": "listProductAreas",
+      "returns": "JSON: `{ areas: Array<{ id, title, strategic_priority?,\nparent_area_id?, products? }>, total }`.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "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`.",
+      "domain": "workspace",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "source_id": {
+            "type": "string",
+            "description": "Source node ID"
+          },
+          "target_id": {
+            "type": "string",
+            "description": "Target node ID"
+          },
+          "type": {
+            "type": "string",
+            "enum": [
+              "shares_persona",
+              "shares_competitor",
+              "shares_metric",
+              "depends_on_product",
+              "cannibalises",
+              "succeeds"
+            ],
+            "description": "Cross-product relationship type"
+          },
+          "source_product_id": {
+            "type": "string",
+            "description": "Product ID of the source node"
+          },
+          "target_product_id": {
+            "type": "string",
+            "description": "Product ID of the target node"
+          }
+        },
+        "required": [
+          "source_id",
+          "target_id",
+          "type"
+        ]
+      },
+      "throws": [
+        "Returns a textError when parameters are missing or invalid, or\nwhen the workspace is not initialised."
+      ],
+      "examples": [],
+      "warnings": [],
+      "see": [
+        "list_portfolios",
+        "list_portfolio_cross_edges",
+        "migrate_cross_edges"
+      ],
+      "source": "src/tools/workspace.ts:395",
+      "symbol": "createCrossProductEdge",
+      "returns": "JSON: `{ edge, portfolio_file }`.",
+      "atomicity": "non-atomic. Portfolio file create (if new) + edge append are\nseparate filesystem operations."
+    },
+    {
+      "name": "create_product",
+      "description": "Create a sibling .upg product in the current workspace. Mints a canonical product id, writes the file, stamps integrity, registers in `workspace.json`. Pairs with `init_workspace` and `switch_product`.",
+      "domain": "workspace",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Product display title (required, non-empty)."
+          },
+          "slug": {
+            "type": "string",
+            "description": "Optional slug for the .upg filename. Defaults to a slug derived from `name`. Collisions append `-2`, `-3`, …"
+          },
+          "description": {
+            "type": "string",
+            "description": "Optional product description"
+          },
+          "stage": {
+            "type": "string",
+            "description": "Product lifecycle stage. See UPGProductStage in @unified-product-graph/core."
+          },
+          "portfolio_id": {
+            "type": "string",
+            "description": "Optional portfolio node id in the current store. When provided, a `portfolio_contains_product` edge is created in the current graph."
+          }
+        },
+        "required": [
+          "name"
+        ]
+      },
+      "throws": [
+        "Returns a textError when the workspace is uninitialised\n(`WorkspaceNotInitialisedError`) or the name is invalid\n(`InvalidProductNameError`)."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"name\": \"example\"\n}",
+          "output": "{\n  \"message\": \"Created product: example\",\n  \"id\": \"p_1IGfQKJJbvHp3zuo\",\n  \"file\": \"example.upg\",\n  \"slug\": \"example\",\n  \"title\": \"example\",\n  \"workspace_path\": \".upg/\",\n  \"portfolio_attached\": false\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "init_workspace"
+      ],
+      "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.",
+      "atomicity": "non-atomic. File write + workspace.json patch + optional\nportfolio edge are separate mutations."
+    },
+    {
+      "name": "get_organization",
+      "description": "Get the organisation that owns the current workspace's portfolio. Reads the singleton `portfolio.upg.organization`. Returns `{ organization: null }` when no portfolio document exists yet.",
+      "domain": "workspace",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"organization\": {\n    \"id\": \"org_1853eb2e\",\n    \"title\": \"Portfolio\"\n  },\n  \"portfolio_file\": \".upg/portfolio.upg\"\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "list_portfolios"
+      ],
+      "source": "src/tools/workspace.ts:344",
+      "symbol": "getOrganization",
+      "returns": "JSON: `{ organization: UPGOrganization | null, portfolio_file? }`.\nReturns `{ organization: null }` when no portfolio document exists yet.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "get_workspace_info",
+      "description": "Workspace info: which product is loaded, what other products are available, current workspace mode.",
+      "domain": "workspace",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"mode\": \"single-file\",\n  \"current_file\": \"../../../../../../../../var/folders/68/wlsstx1s23l9n5shd79wgw8r0000gp/T/upg-capture-cdOo0q/fixture.upg\",\n  \"products\": [\n    {\n      \"file\": \"../../../../../../../../var/folders/68/wlsstx1s23l9n5shd79wgw8r0000gp/T/upg-capture-cdOo0q/fixture.upg\",\n      \"title\": \"Notion (SATURATED test graph)\",\n      \"active\": true\n    }\n  ]\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "init_workspace"
+      ],
+      "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.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "init_workspace",
+      "description": "Initialise a UPG workspace. Creates `.upg/` and moves the current .upg file into it. Unlocks multi-product management.",
+      "domain": "workspace",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "move_existing": {
+            "type": "boolean",
+            "description": "Move existing .upg files into the workspace (default true)"
+          }
+        }
+      },
+      "throws": [
+        "Returns a textError when the workspace already exists\n(`WorkspaceAlreadyExistsError`) or another filesystem error occurs."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"message\": \"Workspace initialized\",\n  \"workspace_path\": \".upg/\",\n  \"default_product\": \"fixture.upg\",\n  \"products\": [\n    {\n      \"file\": \"fixture.upg\",\n      \"title\": \"Notion (SATURATED test graph)\"\n    }\n  ],\n  \"current_product\": {\n    \"title\": \"Notion (SATURATED test graph)\",\n    \"entities\": 2054\n  }\n}"
+        }
+      ],
+      "warnings": [
+        "One-time setup operation. Idempotent failure on retry: if the\nworkspace already exists, raises `WorkspaceAlreadyExistsError`. Pair\nwith `get_workspace_info` to check state before re-running."
+      ],
+      "see": [
+        "create_product",
+        "switch_product",
+        "get_workspace_info"
+      ],
+      "source": "src/tools/workspace.ts:239",
+      "symbol": "initWorkspaceTool",
+      "returns": "JSON: `{ message, ...result }`. `result` carries the workspace\npath and the moved file's new location.",
+      "atomicity": "non-atomic. The operation creates a directory and (optionally)\nmoves a file as separate filesystem mutations."
+    },
+    {
+      "name": "list_local_products",
+      "description": "Find every .upg file in the current directory and its immediate subdirectories.",
+      "domain": "workspace",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"products\": [\n    {\n      \"file\": \"test-fixtures/sample.upg\",\n      \"title\": \"Example Product Graph\",\n      \"stage\": \"mvp\",\n      \"nodes\": 8,\n      \"edges\": 6\n    }\n  ]\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "switch_product",
+        "get_workspace_info"
+      ],
+      "source": "src/tools/workspace.ts:40",
+      "symbol": "listLocalProducts",
+      "returns": "JSON: `{ products: Array<{ file, title, stage, nodes, edges }> }`.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "list_portfolio_cross_edges",
+      "description": "List all cross-product edges stored in the portfolio document (`.upg/portfolio.upg`). Empty list when the portfolio document is absent.",
+      "domain": "workspace",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      },
+      "throws": [],
+      "examples": [],
+      "warnings": [],
+      "see": [
+        "create_cross_product_edge"
+      ],
+      "source": "src/tools/workspace.ts:534",
+      "symbol": "listPortfolioCrossEdges",
+      "returns": "JSON: `{ cross_edges: UPGCrossEdge[], total, portfolio_file? }`.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "list_portfolios",
+      "description": "List portfolios from the portfolio document (`.upg/portfolio.upg`). Portfolios represent the strategic axis (where we invest). Returns an empty list when no portfolio document exists yet.",
+      "domain": "workspace",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"portfolios\": [],\n  \"total\": 0\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "create_cross_product_edge",
+        "get_organization"
+      ],
+      "source": "src/tools/workspace.ts:317",
+      "symbol": "listPortfolios",
+      "returns": "JSON: `{ portfolios: Array<{ id, title, description?,\nparent_portfolio_id?, hierarchy_model?, products? }>, total }`.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "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.",
+      "domain": "workspace",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "source_product_id": {
+            "type": "string",
+            "description": "Product ID that owns the current document's nodes. Used to build qualified source IDs ({product_id}/{node_id})."
+          },
+          "target_product_id": {
+            "type": "string",
+            "description": "Product ID that owns the target nodes, when the target node is not in the current product. Edges without a resolvable target product are skipped."
+          },
+          "dry_run": {
+            "type": "boolean",
+            "description": "When true (default), report what would be migrated without writing anything."
+          }
+        },
+        "required": [
+          "source_product_id"
+        ]
+      },
+      "throws": [
+        "Returns a textError when `source_product_id` is missing or when the\nworkspace is not initialised (in non-dry-run mode)."
+      ],
+      "examples": [],
+      "warnings": [
+        "Default is `dry_run: true`. Pass `dry_run: false` to commit. Idempotent\non retry: a second `dry_run: false` after a successful migration finds zero\ninline cross-edges and reports `migrated: []`."
+      ],
+      "see": [
+        "create_cross_product_edge",
+        "list_portfolio_cross_edges",
+        "list_cross_edge_types",
+        "init_workspace"
+      ],
+      "source": "src/tools/workspace.ts:603",
+      "symbol": "migrateCrossEdges",
+      "returns": "JSON: `{ migrated, skipped, dry_run, portfolio_file? }`.",
+      "atomicity": "non-atomic. Portfolio write + product file save are separate."
+    },
+    {
+      "name": "switch_product",
+      "description": "Switch to a different .upg file without restarting the server. In workspace mode, accepts just a filename (e.g. \"client-project\" or \"client-project.upg\").",
+      "domain": "workspace",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "file": {
+            "type": "string",
+            "description": "Path to the .upg file (relative, absolute, or a bare product name in workspace mode)."
+          }
+        },
+        "required": [
+          "file"
+        ]
+      },
+      "throws": [
+        "Returns a textError when the file cannot be resolved or the load\nfails (file watcher / parse error)."
+      ],
+      "examples": [],
+      "warnings": [
+        "Mutates server-side workspace state. After an MCP reconnect the\nserver reverts to the workspace default. Call `get_workspace_info`\nbefore any read/mutation to confirm the active product."
+      ],
+      "see": [
+        "get_workspace_info",
+        "list_local_products",
+        "init_workspace"
+      ],
+      "source": "src/tools/workspace.ts:108",
+      "symbol": "switchProduct",
+      "returns": "JSON: `{ message, file, product: { title, stage }, entities }`.",
+      "atomicity": "non-atomic. Flushes the current store, stops watching, and\nloads the new file as separate filesystem operations."
+    },
+    {
+      "name": "get_entity_schema",
+      "description": "Return expected properties, valid statuses, valid edge types, and domain for an entity type. Lets agents construct valid entities without skill prompts.",
+      "domain": "schema",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string",
+            "description": "Entity type (e.g. \"hypothesis\", \"persona\", \"opportunity\")"
+          }
+        },
+        "required": [
+          "type"
+        ]
+      },
+      "throws": [
+        "Returns a textError when `type` is missing or unknown."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"type\": \"person\"\n}",
+          "output": "{\n  \"type\": \"person\",\n  \"domain\": {\n    \"id\": \"team_org\",\n    \"label\": \"Team & Organisation\"\n  },\n  \"expected_properties\": {\n    \"email\": {\n      \"type\": \"string\",\n      \"description\": \"Primary contact email. Stable identifier for de-duplication.\"\n    },\n    \"role_title\": {\n      \"type\": \"string\",\n      \"description\": \"Free-text job title. Distinct from the structured `role` entity.\"\n    },\n    \"time_zone\": {\n      \"type\": \"string\",\n      \"description\": \"IANA time zone (e.g. \\\"Europe/Berlin\\\"). Useful for capacity / on-call planning.\"\n    }\n  },\n  \"edges_out\": [],\n  \"edges_in\": [\n    {\n      \"edge_type\": \"node_owned_by_person\",\n      \"source_type\": \"node\",\n      \"reverse_verb\": \"owns\"\n    }\n  ],\n  \"domain_guide\": {\n    \"anchor_entity\": \"team\",\n    \"creation_sequence\": [\n      \"team\",\n      \"role\",\n      \"stakeholder\",\n      \"person\",\n      \"team_okr\",\n      \"retrospective\",\n      \"dependency\",\n      \"department\",\n      \"skill\",\n      \"ceremony\",\n      \"capacity_plan\"\n    ],\n    \"position_in_sequence\": 3,\n    \"anti_patterns\": [\n      {\n        \"description\": \"Teams without OKRs — every team needs clear goals\"\n      },\n      {\n        \"description\": \"Dependencies without both teams linked — a dependency must connect blocker and blocked\"\n      },\n      {\n        \"description\": \"Retrospectives without action items — reflection without action is just venting\"\n      }\n    ]\n  }\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "get_entity_meta",
+        "list_entity_types",
+        "get_valid_children",
+        "get_lifecycle",
+        "get_domain_guide",
+        "list_edge_types",
+        "create_node"
+      ],
+      "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? }`.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "get_anti_pattern",
+      "description": "Return one curated anti-pattern by id (kebab-case slug, e.g. \"features-without-hypotheses\", \"personas-without-jobs\"). Includes structured condition, why-it-matters, remediation, applicable stages, severity, optional source citation. IDs are stable URL fragments.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Anti-pattern id (kebab-case slug)."
+          }
+        },
+        "required": [
+          "id"
+        ]
+      },
+      "throws": [
+        "textError when `id` is missing or unknown."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"id\": \"personas-without-jobs\"\n}",
+          "output": "{\n  \"id\": \"personas-without-jobs\",\n  \"name\": \"Personas without jobs\",\n  \"description\": \"The graph has persona entities, but none link into the user chain via any of the v0.2 chain edges (job, need, desired_outcome, or switching_cost). A persona without chain links is a demographic profile: who someone is, not what they are trying to get done.\",\n  \"structured_condition\": {\n    \"operator\": \"and\",\n    \"checks\": [\n      {\n        \"check\": {\n          \"type\": \"entity_count\",\n          \"entity_type\": \"persona\",\n          \"comparison\": \"nonzero\"\n        }\n      },\n      {\n        \"check\": {\n          \"type\": \"relationship\",\n          \"source_type\": \"persona\",\n          \"edge_type\": \"persona_pursues_job\",\n          \"target_type\": \"job\",\n          \"comparison\": \"not_exists\"\n        }\n      },\n      {\n        \"check\": {\n          \"type\": \"relationship\",\n          \"source_type\": \"persona\",\n          \"edge_type\": \"persona_experiences_need\",\n          \"target_type\": \"need\",\n          \"comparison\": \"not_exists\"\n        }\n      },\n      {\n        \"check\": {\n          \"type\": \"relationship\",\n          \"source_type\": \"persona\",\n          \"edge_type\": \"persona_aspires_to_desired_outcome\",\n          \"target_type\": \"desired_outcome\",\n          \"comparison\": \"not_exists\"\n        }\n      },\n      {\n        \"check\": {\n          \"type\": \"relationship\",\n          \"source_type\": \"persona\",\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "list_anti_patterns",
+        "get_anti_pattern_violations_for",
+        "inspect",
+        "validate_graph"
+      ],
+      "source": "src/tools/spec.ts:1425",
+      "symbol": "getAntiPattern",
+      "returns": "JSON: `UPGCuratedAntiPattern`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "get_approach",
+      "description": "Return one `UPGApproach` by id. Valid ids: `plan`, `inspect`, `prioritise`, `trace`, `reflect` (same names as the verb-led MCP tools).",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Approach id. One of: plan, inspect, prioritise, trace, reflect.",
+            "enum": [
+              "plan",
+              "inspect",
+              "prioritise",
+              "trace",
+              "reflect"
+            ]
+          }
+        },
+        "required": [
+          "id"
+        ]
+      },
+      "throws": [
+        "textError when `id` is missing or unknown."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"id\": \"plan\"\n}",
+          "output": "{\n  \"id\": \"plan\",\n  \"label\": \"Plan\",\n  \"description\": \"The path of arrival to \\\"what should I build next?\\\". Plan engages a region by surveying its entity coverage against canonical expectations and surfacing the missing scaffolding: the entities a healthy region carries that this graph does not. Cartographic sense: you are walking the coastline of a region and noting where the contour is incomplete, not deciding a strategy. Frameworks like Now/Next/Later, MoSCoW, and Wardley Mapping live within Plan as the named techniques for organising the gap-filling sequence.\",\n  \"question_answered\": \"what should I build next?\",\n  \"signature_hint\": \"({ region?: UPGRegionId }) → { missing_entities, coverage_score }\",\n  \"framework_id_examples\": [\n    \"now-next-later\",\n    \"moscow\",\n    \"wardley-map\",\n    \"okr-framework\",\n    \"three-horizons\"\n  ]\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "list_approaches",
+        "plan",
+        "inspect",
+        "prioritise",
+        "trace",
+        "reflect"
+      ],
+      "source": "src/tools/spec.ts:320",
+      "symbol": "getApproach",
+      "returns": "JSON: the full `UPGApproach` record.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "get_domain_guide",
+      "description": "Return the full `UPGDomainUsageGuide` for a domain: anchor entity, creation sequence, named patterns (entity + edge chains), required cross-domain bridges, anti-patterns.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "domain_id": {
+            "type": "string",
+            "description": "Canonical domain id (e.g. \"user\", \"market_intelligence\", \"growth\")."
+          }
+        },
+        "required": [
+          "domain_id"
+        ]
+      },
+      "throws": [
+        "textError when `domain_id` is missing or unknown."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"domain_id\": \"strategy\"\n}",
+          "output": "{\n  \"domain_id\": \"strategy\",\n  \"anchor_entity\": \"outcome\",\n  \"creation_sequence\": [\n    \"product\",\n    \"vision\",\n    \"mission\",\n    \"outcome\",\n    \"objective\",\n    \"key_result\",\n    \"metric\",\n    \"metric_quality_assessment\",\n    \"strategic_theme\",\n    \"strategic_pillar\",\n    \"initiative\",\n    \"capability\",\n    \"value_stream\",\n    \"assumption\",\n    \"decision\",\n    \"constraint\"\n  ],\n  \"patterns\": [\n    {\n      \"name\": \"Strategic Cascade\",\n      \"description\": \"Vision grounds mission, product pursues outcomes and targets objectives, objectives achieved through key results measured by metrics\",\n      \"entity_types\": [\n        \"vision\",\n        \"mission\",\n        \"outcome\",\n        \"objective\",\n        \"key_result\",\n        \"metric\"\n      ],\n      \"edge_chain\": [\n        \"product_guided_by_vision\",\n        \"product_fulfils_mission\",\n        \"vision_realised_through_mission\",\n        \"product_pursues_outcome\",\n        \"product_targets_objective\",\n        \"objective_achieved_through_key_result\",\n        \"outcome_measured_by_metric\"\n      ]\n    }\n  ],\n  \"required_bridges\": [\n    {\n      \"edge_type\": \"outcome_reveals_opportunity\",\n      \"target_domain\": \"discovery\",\n      \"when\": \"Outcomes should connect to the opportunities that deliver them\"\n    },\n    {\n      \"edge_type\": \"outcome_delivered_by_feature\",\n      \"target_domain\": \"product_spec\",\n      \"when\": \"Strategic outcomes should\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "list_domains",
+        "get_domain_ring",
+        "list_anti_patterns",
+        "get_playbook"
+      ],
+      "source": "src/tools/spec.ts:745",
+      "symbol": "getDomainGuide",
+      "returns": "JSON: the full `UPGDomainUsageGuide` record.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "get_domain_ring",
+      "description": "Return one `UPGDomainRing` by id (one of: `nucleus`, `understand`, `define`, `build`, `grow`, `operate`, `extend`). Returns a descriptive message (not an error) when the id is unknown.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Ring id. One of: nucleus, understand, define, build, grow, operate, extend."
+          }
+        },
+        "required": [
+          "id"
+        ]
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"id\": \"nucleus\"\n}",
+          "output": "{\n  \"id\": \"nucleus\",\n  \"label\": \"Product\",\n  \"description\": \"The seed\",\n  \"domain_ids\": [\n    \"portfolio\",\n    \"workspace\"\n  ]\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "list_domain_rings",
+        "list_domains",
+        "get_domain_guide"
+      ],
+      "source": "src/tools/spec.ts:1881",
+      "symbol": "getDomainRing",
+      "returns": "JSON: the full `UPGDomainRing` record.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "get_edge_type",
+      "description": "Return one edge catalogue entry by edge type key (e.g. \"persona_pursues_job\", \"feature_addresses_need\").",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string",
+            "description": "Edge type key from UPG_EDGE_CATALOG."
+          }
+        },
+        "required": [
+          "type"
+        ]
+      },
+      "throws": [
+        "textError when `type` is missing or unknown."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"type\": \"opportunity_drives_solution\"\n}",
+          "output": "{\n  \"type\": \"opportunity_drives_solution\",\n  \"forward_verb\": \"drives\",\n  \"reverse_verb\": \"addresses\",\n  \"classification\": \"causal\",\n  \"source_type\": \"opportunity\",\n  \"target_type\": \"solution\"\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "list_edge_types",
+        "resolve_edge_for_pair",
+        "list_edge_migrations",
+        "rename_edge_type"
+      ],
+      "source": "src/tools/spec.ts:877",
+      "symbol": "getEdgeType",
+      "returns": "JSON: `{ type, forward_verb, reverse_verb, classification, source_type, target_type }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "get_entity_meta",
+      "description": "Return one `EntityTypeMeta` record by entity type name, plus resolved `domain_id` (null when unmapped). One type's lifecycle metadata: maturity tier, since-version, replacement target if deprecated. Pass the canonical name (e.g. \"persona\", \"pain_point\"), not the immutable `type_id`.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Canonical entity type name."
+          }
+        },
+        "required": [
+          "name"
+        ]
+      },
+      "throws": [
+        "textError when `name` is missing or unknown."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"name\": \"person\"\n}",
+          "output": "{\n  \"name\": \"person\",\n  \"type_id\": \"ent_349\",\n  \"maturity\": \"stable\",\n  \"since\": \"0.5.0\",\n  \"domain_id\": \"team_org\"\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "list_entity_types",
+        "get_type_label",
+        "get_entity_schema",
+        "list_type_migrations"
+      ],
+      "source": "src/tools/spec.ts:1340",
+      "symbol": "getEntityMeta",
+      "returns": "JSON: `EntityTypeMeta & { domain_id: string | null }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "get_framework",
+      "description": "Return one `UPGFramework` by id (e.g. \"rice-scoring\", \"lean-canvas\"). Includes all four layers: data, structure, presentation, education.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Framework id (kebab-case)."
+          }
+        },
+        "required": [
+          "id"
+        ]
+      },
+      "throws": [
+        "textError when `id` is missing or unknown."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"id\": \"opportunity-solution-tree\"\n}",
+          "output": "{\n  \"id\": \"opportunity-solution-tree\",\n  \"approach_ids\": [\n    \"trace\"\n  ],\n  \"name\": \"Opportunity Solution Tree\",\n  \"version\": \"1.0.0\",\n  \"description\": \"Map desired outcomes to opportunities, then branch into solutions and experiments. Ensures every solution traces back to a real user need.\",\n  \"category\": \"discovery\",\n  \"origin\": {\n    \"type\": \"practitioner\",\n    \"attribution\": \"Teresa Torres\",\n    \"description\": \"Introduced in Continuous Discovery Habits. Maps outcomes to opportunities, solutions, and experiments.\",\n    \"url\": \"https://www.producttalk.org/opportunity-solution-tree/\",\n    \"year\": 2021,\n    \"license\": \"published_methodology\"\n  },\n  \"tags\": [\n    \"discovery\",\n    \"tree\"\n  ],\n  \"slots\": [\n    {\n      \"label\": \"Root Outcome\",\n      \"entityTypeId\": \"outcome\",\n      \"description\": \"The desired business or user outcome\"\n    },\n    {\n      \"label\": \"Opportunities\",\n      \"entityTypeId\": \"opportunity\",\n      \"description\": \"User needs, pain points, or desires\"\n    },\n    {\n      \"label\": \"Solutions\",\n      \"entityTypeId\": \"solution\",\n      \"description\": \"Ideas to address each opportunity\"\n    },\n    {\n      \"label\": \"Experiments\",\n      \"entityTypeId\": \"experiment_run\",\n      \"description\": \"Tests to validate each solution\"\n    }\n  ],\n  \"data\": {\n    \"entity_types\": [\n      {\n        \"type\": \"outcome\",\n        \"role\": \"root\"\n      },\n      {\n        \"type\":\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "list_frameworks",
+        "prioritise",
+        "get_playbook",
+        "get_approach"
+      ],
+      "source": "src/tools/spec.ts:814",
+      "symbol": "getFramework",
+      "returns": "JSON: the full `UPGFramework` record.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "get_lens",
+      "description": "Return the full `UPGLens` record by id (e.g. \"product\", \"ux_design\", \"engineering\", \"full\") plus the resolved entity types visible through that lens. Combines the lens record with `visible_types` in one response.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Lens id (e.g. \"product\", \"ux_design\", \"full\")."
+          }
+        },
+        "required": [
+          "id"
+        ]
+      },
+      "throws": [
+        "textError when `id` is missing or unknown."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"id\": \"product\"\n}",
+          "output": "{\n  \"id\": \"product\",\n  \"name\": \"Product\",\n  \"description\": \"Full graph, PM vocabulary, outcome-driven workflow\",\n  \"icon\": \"target\",\n  \"framework_id\": \"ost\",\n  \"label_overrides\": {\n    \"experiment\": \"Experiment\",\n    \"learning\": \"Validated Learning\"\n  },\n  \"visible_domains\": [],\n  \"benchmark_domains\": [\n    \"strategy\",\n    \"user\",\n    \"discovery\",\n    \"validation\",\n    \"market_intelligence\",\n    \"product_spec\",\n    \"growth\"\n  ],\n  \"intelligence_prompts\": [\n    {\n      \"condition\": \"outcomes.length === 0\",\n      \"structured_condition\": {\n        \"check\": {\n          \"type\": \"entity_count\",\n          \"entity_type\": \"outcome\",\n          \"comparison\": \"zero\"\n        }\n      },\n      \"message\": \"No outcomes defined yet. Start with what success looks like — what measurable result should this product drive?\"\n    },\n    {\n      \"condition\": \"hypotheses.untested.length > 3\",\n      \"structured_condition\": {\n        \"check\": {\n          \"type\": \"entity_count\",\n          \"entity_type\": \"hypothesis\",\n          \"filter\": {\n            \"status\": \"untested\"\n          },\n          \"comparison\": \"gt\",\n          \"threshold\": 3\n        }\n      },\n      \"message\": \"You have untested hypotheses stacking up. Pick the riskiest one and design an experiment before adding more.\"\n    },\n    {\n      \"condition\": \"features.length > 0 && hypotheses.length === 0\",\n      \"structured_condition\": {\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "list_lenses",
+        "get_playbook",
+        "get_framework",
+        "list_entity_types"
+      ],
+      "source": "src/tools/spec.ts:1134",
+      "symbol": "getLensTool",
+      "returns": "JSON: `{ ...UPGLens, visible_types: string[] }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "get_lifecycle",
+      "description": "Return the full `UPGLifecycle` definition for one entity type: initial phase, terminal phases, ordered phases with transitions and core states. Returns a descriptive message (not an error) when the type has no lifecycle.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "entity_type": {
+            "type": "string",
+            "description": "Canonical entity type name (e.g. \"feature\", \"hypothesis\", \"opportunity\")."
+          }
+        },
+        "required": [
+          "entity_type"
+        ]
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"entity_type\": \"hypothesis\"\n}",
+          "output": "{\n  \"entity_type\": \"hypothesis\",\n  \"initial_phase\": \"drafted\",\n  \"terminal_phases\": [\n    \"validated\",\n    \"invalidated\",\n    \"archived\"\n  ],\n  \"phases\": [\n    {\n      \"id\": \"drafted\",\n      \"label\": \"Drafted\",\n      \"description\": \"The claim is being written. We_believe / will_result_in / we_know_when may not yet be complete. Not yet committed for testing.\",\n      \"transitions_to\": [\n        \"active\",\n        \"archived\"\n      ]\n    },\n    {\n      \"id\": \"active\",\n      \"label\": \"Active\",\n      \"description\": \"The claim is committed and being tested. Experiments may be running; evidence may be accruing via supports/refutes edges. current_confidence updates as evidence weight shifts.\",\n      \"transitions_to\": [\n        \"validated\",\n        \"invalidated\",\n        \"archived\"\n      ]\n    },\n    {\n      \"id\": \"validated\",\n      \"label\": \"Validated\",\n      \"description\": \"Evidence sufficiently supports the claim. The belief held. Reopens to `active` if new evidence materially changes the picture.\",\n      \"transitions_to\": [\n        \"active\"\n      ]\n    },\n    {\n      \"id\": \"invalidated\",\n      \"label\": \"Invalidated\",\n      \"description\": \"Evidence sufficiently refutes the claim. The belief did not hold. Reopens to `active` if new evidence materially changes the picture.\",\n      \"transitions_to\": [\n        \"active\"\n      ]\n    },\n    {\n      \"id\": \"archived\",\n      \"label\":\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "list_lifecycles",
+        "get_entity_meta",
+        "get_entity_schema"
+      ],
+      "source": "src/tools/spec.ts:1751",
+      "symbol": "getLifecycle",
+      "returns": "JSON: the full `UPGLifecycle` record, or a descriptive message.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "get_playbook",
+      "description": "Return one `UPGPlaybook` by id (e.g. \"playbook:strategy-outcomes\", \"playbook:business-model-bmc\"). Includes the ordered `creation_sequence` with step kinds and prompts. IDs are namespace-prefixed `playbook:*`. For approaches, use `get_approach`.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Playbook id (namespace-prefixed: playbook:*)."
+          }
+        },
+        "required": [
+          "id"
+        ]
+      },
+      "throws": [
+        "textError when `id` is missing or unknown."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"id\": \"playbook:strategy-outcomes\"\n}",
+          "output": "{\n  \"id\": \"playbook:strategy-outcomes\",\n  \"name\": \"Strategy & Outcomes\",\n  \"version\": \"0.2.0\",\n  \"description\": \"Cascade vision through themes, outcomes, objectives, key results — and the bets you are making to get there.\",\n  \"region\": \"strategy_outcomes\",\n  \"is_canonical\": true,\n  \"target_anchor_entity\": \"objective\",\n  \"creation_sequence\": [\n    {\n      \"kind\": \"entity_sequence\",\n      \"order\": 1,\n      \"phase\": \"Vision & Mission\",\n      \"name\": \"Vision & Mission\",\n      \"prompt_hint\": \"Name what you are building toward and how you will get there. Vision is the destination; mission is the orientation. One of each — more is dilution.\",\n      \"entity_types\": [\n        \"vision\",\n        \"mission\"\n      ]\n    },\n    {\n      \"kind\": \"entity_sequence\",\n      \"order\": 2,\n      \"phase\": \"Themes\",\n      \"name\": \"Themes\",\n      \"prompt_hint\": \"Choose 2–4 strategic themes that focus the work. Past four, you have lost focus, not gained coverage.\",\n      \"entity_types\": [\n        \"strategic_theme\",\n        \"strategic_pillar\"\n      ]\n    },\n    {\n      \"kind\": \"entity_sequence\",\n      \"order\": 3,\n      \"phase\": \"Outcomes\",\n      \"name\": \"Outcomes\",\n      \"prompt_hint\": \"Frame the changes in the world the product is trying to cause — shifts in behavior, perception, or position. Not features shipped.\",\n      \"entity_types\": [\n        \"outcome\"\n      ]\n    },\n    {\n      \"kind\":\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "list_playbooks",
+        "get_approach",
+        "get_framework",
+        "get_region"
+      ],
+      "source": "src/tools/spec.ts:252",
+      "symbol": "getPlaybook",
+      "returns": "JSON: the full `UPGPlaybook` record.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "get_region",
+      "description": "Return the full `UPGRegion` record by id: anchor entity (with rationale and inbound/outbound cross-edge counts), entity memberships with structural roles, intra-domain edge keys, boundary edges to other regions, shape archetype, atomic-domain composition.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Region id (e.g. \"strategy_outcomes\", \"users_needs\", \"product_delivery\"). See UPG_REGIONS for the full list of 10."
+          }
+        },
+        "required": [
+          "id"
+        ]
+      },
+      "throws": [
+        "textError when `id` is missing or unknown."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"id\": \"strategy_outcomes\"\n}",
+          "output": "{\n  \"id\": \"strategy_outcomes\",\n  \"label\": \"Strategy & Outcomes\",\n  \"order\": 1,\n  \"shape\": \"cascade\",\n  \"mental_model\": \"Aspiration → direction → bet → measurable → proof.\",\n  \"operators\": [\n    \"CEO\",\n    \"PM\",\n    \"leadership\",\n    \"strategy team\"\n  ],\n  \"composes_atomic_domains\": [\n    \"strategy\"\n  ],\n  \"entities\": [\n    {\n      \"type\": \"vision\",\n      \"role\": \"root\"\n    },\n    {\n      \"type\": \"mission\",\n      \"role\": \"container\"\n    },\n    {\n      \"type\": \"strategic_pillar\",\n      \"role\": \"hub\"\n    },\n    {\n      \"type\": \"strategic_theme\",\n      \"role\": \"container\"\n    },\n    {\n      \"type\": \"initiative\",\n      \"role\": \"container\"\n    },\n    {\n      \"type\": \"capability\",\n      \"role\": \"leaf\"\n    },\n    {\n      \"type\": \"value_stream\",\n      \"role\": \"container\"\n    },\n    {\n      \"type\": \"objective\",\n      \"role\": \"anchor\"\n    },\n    {\n      \"type\": \"key_result\",\n      \"role\": \"hub\"\n    },\n    {\n      \"type\": \"metric\",\n      \"role\": \"leaf\",\n      \"notes\": \"shared with Analytics\"\n    },\n    {\n      \"type\": \"decision\",\n      \"role\": \"hub\",\n      \"notes\": \"polymorphic across domains\"\n    },\n    {\n      \"type\": \"assumption\",\n      \"role\": \"leaf\"\n    },\n    {\n      \"type\": \"outcome\",\n      \"role\": \"hub\"\n    }\n  ],\n  \"anchor\": {\n    \"type\": \"objective\",\n    \"rationale\": \"The single entity where P5 language meets P3 measurement. The accountability question of strategy flows through\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "list_regions",
+        "get_region_for_entity_type",
+        "get_playbook",
+        "list_lenses"
+      ],
+      "source": "src/tools/spec.ts:936",
+      "symbol": "getRegion",
+      "returns": "JSON: the full `UPGRegion` record.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "get_region_for_entity_type",
+      "description": "Resolve which super-domain region contains a given entity type. Wraps `getRegionForEntityType`; returns the full `UPGRegion` record. Use for adapters and copilots that route or render an entity by its super-domain.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "entity_type": {
+            "type": "string",
+            "description": "Canonical entity type (e.g. \"persona\", \"feature\", \"metric\")."
+          }
+        },
+        "required": [
+          "entity_type"
+        ]
+      },
+      "throws": [
+        "textError when `entity_type` is missing or no region contains it."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"entity_type\": \"outcome\"\n}",
+          "output": "{\n  \"id\": \"strategy_outcomes\",\n  \"label\": \"Strategy & Outcomes\",\n  \"order\": 1,\n  \"shape\": \"cascade\",\n  \"mental_model\": \"Aspiration → direction → bet → measurable → proof.\",\n  \"operators\": [\n    \"CEO\",\n    \"PM\",\n    \"leadership\",\n    \"strategy team\"\n  ],\n  \"composes_atomic_domains\": [\n    \"strategy\"\n  ],\n  \"entities\": [\n    {\n      \"type\": \"vision\",\n      \"role\": \"root\"\n    },\n    {\n      \"type\": \"mission\",\n      \"role\": \"container\"\n    },\n    {\n      \"type\": \"strategic_pillar\",\n      \"role\": \"hub\"\n    },\n    {\n      \"type\": \"strategic_theme\",\n      \"role\": \"container\"\n    },\n    {\n      \"type\": \"initiative\",\n      \"role\": \"container\"\n    },\n    {\n      \"type\": \"capability\",\n      \"role\": \"leaf\"\n    },\n    {\n      \"type\": \"value_stream\",\n      \"role\": \"container\"\n    },\n    {\n      \"type\": \"objective\",\n      \"role\": \"anchor\"\n    },\n    {\n      \"type\": \"key_result\",\n      \"role\": \"hub\"\n    },\n    {\n      \"type\": \"metric\",\n      \"role\": \"leaf\",\n      \"notes\": \"shared with Analytics\"\n    },\n    {\n      \"type\": \"decision\",\n      \"role\": \"hub\",\n      \"notes\": \"polymorphic across domains\"\n    },\n    {\n      \"type\": \"assumption\",\n      \"role\": \"leaf\"\n    },\n    {\n      \"type\": \"outcome\",\n      \"role\": \"hub\"\n    }\n  ],\n  \"anchor\": {\n    \"type\": \"objective\",\n    \"rationale\": \"The single entity where P5 language meets P3 measurement. The accountability question of strategy flows through\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "get_region",
+        "list_regions",
+        "get_entity_meta",
+        "list_entity_types"
+      ],
+      "source": "src/tools/spec.ts:958",
+      "symbol": "getRegionForEntity",
+      "returns": "JSON: the full `UPGRegion` record.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "get_scale",
+      "description": "Return one spec-defined assessment scale by id (e.g. \"reach_5\", \"severity_5\", \"confidence_binary\"). Includes the full point array. Returns a descriptive message (not an error) when the id is unknown.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Scale id (e.g. \"reach_5\", \"frequency_5\", \"severity_5\", \"importance_5\", \"confidence_binary\")."
+          }
+        },
+        "required": [
+          "id"
+        ]
+      },
+      "throws": [],
+      "examples": [],
+      "warnings": [],
+      "see": [
+        "list_scales",
+        "get_entity_schema"
+      ],
+      "source": "src/tools/spec.ts:1797",
+      "symbol": "getScale",
+      "returns": "JSON: the full `UPGScaleDefinition` record including all points.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "get_spec_version",
+      "description": "Spec-level metadata for compatibility checks: `upg_version`, `markdown_format_version`, and canonical counts (entity types, edge types, atomic domains, super-domain regions). Pin against the version pair; counts are informational.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"upg_version\": \"0.5.8\",\n  \"markdown_format_version\": \"0.1\",\n  \"entity_count\": 312,\n  \"edge_count\": 938,\n  \"domain_count\": 36,\n  \"region_count\": 10\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "get_workspace_info",
+        "list_entity_types",
+        "list_edge_types",
+        "list_regions"
+      ],
+      "source": "src/tools/spec.ts:986",
+      "symbol": "getSpecVersion",
+      "returns": "JSON: `{ upg_version, markdown_format_version, entity_count, edge_count, domain_count, region_count }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "get_type_label",
+      "description": "Return one `UPGTypeLabel` by entity type, plus a resolved display label for an optional `framework_id` and/or `designation` (wraps `resolveLabel`). Lookup is exact-match against `UPG_TYPE_LABELS_MAP`.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "entity_type": {
+            "type": "string",
+            "description": "Canonical entity type id."
+          },
+          "framework_id": {
+            "type": "string",
+            "description": "Optional framework id (e.g. \"lean_canvas\", \"ost\", \"design_thinking\"). When set, resolved_label uses the framework-specific label."
+          },
+          "designation": {
+            "type": "string",
+            "description": "Optional designation key (e.g. \"pain\", \"gap\", \"desire\") for types that use the designation pattern."
+          }
+        },
+        "required": [
+          "entity_type"
+        ]
+      },
+      "throws": [
+        "textError when `entity_type` is missing or unknown."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"entity_type\": \"person\"\n}",
+          "output": "{\n  \"id\": \"person\",\n  \"canonical_label\": \"Person\",\n  \"alt_labels\": [],\n  \"framework_labels\": {},\n  \"resolved_label\": \"Person\"\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "list_type_labels",
+        "get_entity_meta",
+        "list_frameworks"
+      ],
+      "source": "src/tools/spec.ts:1202",
+      "symbol": "getTypeLabel",
+      "returns": "JSON: `{ ...UPGTypeLabel, resolved_label: string }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "get_valid_children",
+      "description": "Return valid direct-child entity types for a parent type. Wraps `getValidChildren` / `UPG_VALID_CHILDREN`. Empty array when none registered. Answers \"what can I create under this?\". Pairs with `get_entity_schema`.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "parent_type": {
+            "type": "string",
+            "description": "Canonical parent entity type."
+          }
+        },
+        "required": [
+          "parent_type"
+        ]
+      },
+      "throws": [
+        "textError when `parent_type` is missing."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"parent_type\": \"example\"\n}",
+          "output": "{\n  \"parent_type\": \"example\",\n  \"valid_children\": []\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "get_entity_schema",
+        "list_entity_types",
+        "get_entity_meta",
+        "create_node"
+      ],
+      "source": "src/tools/spec.ts:1232",
+      "symbol": "getValidChildrenTool",
+      "returns": "JSON: `{ parent_type, valid_children: string[] }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "inspect",
+      "description": "[LLM-mediated] This tool returns a routing envelope, not computed results. For user-facing inspection, invoke the /upg-inspect skill instead of calling this tool directly. — Inspect approach: path of arrival to \"what's broken?\". Returns the Inspect record + invocation params in the family-resemblance envelope. The LLM consumes `signature_hint` and emits `{ violations: [{ severity, kind, entity_id, description, fix_hint }] }` against `UPG_ANTI_PATTERNS` + the live graph. Optional `region` or `entities[]` scope the audit.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "region": {
+            "type": "string",
+            "description": "Optional UPGRegionId. Narrows inspection scope to a single region."
+          },
+          "entities": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Optional entity_id[]. Narrows inspection scope to a specific candidate set. Composable with region."
+          }
+        }
+      },
+      "throws": [],
+      "examples": [],
+      "warnings": [],
+      "see": [
+        "get_approach",
+        "list_anti_patterns",
+        "get_anti_pattern",
+        "get_anti_pattern_violations_for",
+        "validate_graph",
+        "plan",
+        "reflect"
+      ],
+      "source": "src/tools/spec.ts:458",
+      "symbol": "inspect",
+      "returns": "JSON envelope: `{ approach_id, scope, generated_at, approach,\nparams, violations, summary, execution_mode: \"execution_v0_4_0\" }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "list_anti_patterns",
+      "description": "List curated cross-domain anti-patterns from `UPG_ANTI_PATTERNS`. Each row pairs a memorable name with a machine-evaluable `IntelligenceCondition`, applicable stages, severity, and remediation. Graph-health patterns evaluated whole-graph (distinct from per-domain anti-patterns via `get_domain_guide`). Paginated (default 50, max 200). Filters AND together: `severity` (`high` / `medium` / `low`), `stage` (keeps patterns whose `stages[]` includes the given `UPGProductStage`).",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "severity": {
+            "type": "string",
+            "enum": [
+              "high",
+              "medium",
+              "low"
+            ],
+            "description": "Exact-match UPGAntiPatternSeverity."
+          },
+          "stage": {
+            "type": "string",
+            "enum": [
+              "concept",
+              "validation",
+              "build",
+              "beta",
+              "launch",
+              "growth",
+              "mature",
+              "maintenance",
+              "sunset"
+            ],
+            "description": "Keeps anti-patterns whose stages[] includes the given UPGProductStage."
+          },
+          "limit": {
+            "type": "number",
+            "description": "Page size (default 50, max 200)."
+          },
+          "cursor": {
+            "type": "string",
+            "description": "Opaque pagination cursor. Pass next_cursor from a previous response."
+          }
+        }
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"total\": 12,\n  \"count\": 12,\n  \"anti_patterns\": [\n    {\n      \"id\": \"personas-without-jobs\",\n      \"name\": \"Personas without jobs\",\n      \"description\": \"The graph has persona entities, but none link into the user chain via any of the v0.2 chain edges (job, need, desired_outcome, or switching_cost). A persona without chain links is a demographic profile: who someone is, not what they are trying to get done.\",\n      \"structured_condition\": {\n        \"operator\": \"and\",\n        \"checks\": [\n          {\n            \"check\": {\n              \"type\": \"entity_count\",\n              \"entity_type\": \"persona\",\n              \"comparison\": \"nonzero\"\n            }\n          },\n          {\n            \"check\": {\n              \"type\": \"relationship\",\n              \"source_type\": \"persona\",\n              \"edge_type\": \"persona_pursues_job\",\n              \"target_type\": \"job\",\n              \"comparison\": \"not_exists\"\n            }\n          },\n          {\n            \"check\": {\n              \"type\": \"relationship\",\n              \"source_type\": \"persona\",\n              \"edge_type\": \"persona_experiences_need\",\n              \"target_type\": \"need\",\n              \"comparison\": \"not_exists\"\n            }\n          },\n          {\n            \"check\": {\n              \"type\": \"relationship\",\n              \"source_type\": \"persona\",\n              \"edge_type\": \"persona_aspires_to_desired_outcome\",\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "get_anti_pattern",
+        "get_anti_pattern_violations_for",
+        "validate_graph",
+        "inspect",
+        "get_domain_guide"
+      ],
+      "source": "src/tools/spec.ts:1383",
+      "symbol": "listAntiPatterns",
+      "returns": "JSON: `{ total, count, next_cursor?, anti_patterns: UPGCuratedAntiPattern[] }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "list_approaches",
+      "description": "List the 5 canonical `UPGApproach` records: Plan, Inspect, Prioritise, Trace, Reflect. An approach is the path of arrival to a region of the graph (final approach to an airport, coastline approach). Each record carries id, label, description, `question_answered`, `signature_hint`, `framework_id_examples`. Optional `framework_id` narrows to approaches whose `framework_id_examples` include it.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "framework_id": {
+            "type": "string",
+            "description": "Exact-match framework id. Narrows to approaches whose framework_id_examples include it (discoverability surface; full reverse lookup is on UPGFramework.approach_ids)."
+          }
+        }
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"count\": 5,\n  \"approaches\": [\n    {\n      \"id\": \"plan\",\n      \"label\": \"Plan\",\n      \"description\": \"The path of arrival to \\\"what should I build next?\\\". Plan engages a region by surveying its entity coverage against canonical expectations and surfacing the missing scaffolding: the entities a healthy region carries that this graph does not. Cartographic sense: you are walking the coastline of a region and noting where the contour is incomplete, not deciding a strategy. Frameworks like Now/Next/Later, MoSCoW, and Wardley Mapping live within Plan as the named techniques for organising the gap-filling sequence.\",\n      \"question_answered\": \"what should I build next?\",\n      \"signature_hint\": \"({ region?: UPGRegionId }) → { missing_entities, coverage_score }\",\n      \"framework_id_examples\": [\n        \"now-next-later\",\n        \"moscow\",\n        \"wardley-map\",\n        \"okr-framework\",\n        \"three-horizons\"\n      ]\n    },\n    {\n      \"id\": \"inspect\",\n      \"label\": \"Inspect\",\n      \"description\": \"The path of arrival to \\\"what's broken?\\\". Inspect engages a region or a set of entities by running canonical health checks (anti-pattern audits, drift reports, lint passes) and emitting a structured violation list with severity, kind, target entity, description, and fix hint. Cartographic sense: you are surveying the coastline for hazards before approach; the violations are the\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "get_approach",
+        "plan",
+        "inspect",
+        "prioritise",
+        "trace",
+        "reflect",
+        "list_playbooks"
+      ],
+      "source": "src/tools/spec.ts:292",
+      "symbol": "listApproaches",
+      "returns": "JSON: `{ count, approaches: UPGApproach[] }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "list_benchmarks",
+      "description": "Return one of four canonical benchmark catalogs (the data behind `get_graph_digest` health logic). Required `kind` selects the source: `count` → `UPG_COUNT_BENCHMARKS` (per-entity-type ranges across the 9-stage journey); `relationship` → `UPG_RELATIONSHIP_BENCHMARKS` (parent → child minimum counts per stage); `ratio` → `UPG_RATIO_BENCHMARKS` (expected ratios between entity-type counts); `domain_activation` → `UPG_DOMAIN_ACTIVATION` (when each atomic domain is expected to activate). Optional filters AND together: `stage` (`UPGProductStage`), `domain` (atomic-domain id). Non-paginated.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": [
+              "count",
+              "relationship",
+              "ratio",
+              "domain_activation"
+            ],
+            "description": "Required. Which benchmark catalog to return."
+          },
+          "stage": {
+            "type": "string",
+            "enum": [
+              "concept",
+              "validation",
+              "build",
+              "beta",
+              "launch",
+              "growth",
+              "mature",
+              "maintenance",
+              "sunset"
+            ],
+            "description": "Optional UPGProductStage filter. Semantics depend on kind (see tool description)."
+          },
+          "domain": {
+            "type": "string",
+            "description": "Optional atomic-domain id filter. Semantics depend on kind (see tool description)."
+          }
+        },
+        "required": [
+          "kind"
+        ]
+      },
+      "throws": [
+        "textError when `kind` is missing or not one of the four supported values."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"kind\": \"count\"\n}",
+          "output": "{\n  \"kind\": \"count\",\n  \"total\": 47,\n  \"count\": 47,\n  \"benchmarks\": [\n    {\n      \"type\": \"product\",\n      \"domain\": \"strategy\",\n      \"concept\": {\n        \"min\": 1,\n        \"max\": 1\n      },\n      \"validation\": {\n        \"min\": 1,\n        \"max\": 1\n      },\n      \"build\": {\n        \"min\": 1,\n        \"max\": 1\n      },\n      \"beta\": {\n        \"min\": 1,\n        \"max\": 1\n      },\n      \"launch\": {\n        \"min\": 1,\n        \"max\": 1\n      },\n      \"growth\": {\n        \"min\": 1,\n        \"max\": 1\n      },\n      \"mature\": {\n        \"min\": 1,\n        \"max\": 3\n      },\n      \"maintenance\": {\n        \"min\": 1,\n        \"max\": 3\n      },\n      \"sunset\": {\n        \"min\": 1,\n        \"max\": 1\n      },\n      \"source\": {\n        \"kind\": \"fundamental\"\n      },\n      \"rationale\": \"Every graph needs exactly one product (or one per product area at scale).\"\n    },\n    {\n      \"type\": \"outcome\",\n      \"domain\": \"strategy\",\n      \"concept\": {\n        \"min\": 1,\n        \"max\": 3\n      },\n      \"validation\": {\n        \"min\": 2,\n        \"max\": 4\n      },\n      \"build\": {\n        \"min\": 2,\n        \"max\": 5\n      },\n      \"beta\": {\n        \"min\": 3,\n        \"max\": 7\n      },\n      \"launch\": {\n        \"min\": 2,\n        \"max\": 5\n      },\n      \"growth\": {\n        \"min\": 3,\n        \"max\": 8\n      },\n      \"mature\": {\n        \"min\": 5,\n        \"max\": 15\n      },\n      \"maintenance\": {\n        \"min\": 5,\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "get_graph_digest",
+        "list_product_stages",
+        "list_domains",
+        "list_anti_patterns"
+      ],
+      "source": "src/tools/spec.ts:1472",
+      "symbol": "listBenchmarks",
+      "returns": "JSON: `{ kind, total, count, benchmarks: ... }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "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`. Portfolio-level relationships across products. Distinct from the within-product `UPG_EDGE_CATALOG`.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"count\": 6,\n  \"types\": [\n    \"shares_persona\",\n    \"shares_competitor\",\n    \"shares_metric\",\n    \"depends_on_product\",\n    \"cannibalises\",\n    \"succeeds\"\n  ]\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "list_edge_types",
+        "list_portfolio_cross_edges",
+        "migrate_cross_edges"
+      ],
+      "source": "src/tools/spec.ts:1072",
+      "symbol": "listCrossEdgeTypes",
+      "returns": "JSON: `{ count, types: readonly UPGCrossEdgeType[] }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "list_domain_rings",
+      "description": "List every `UPGDomainRing` from `UPG_DOMAIN_RINGS` in canonical order: Nucleus → Understand → Define → Build → Grow → Operate → Extend. Rings are the 7 concentric groupings of the 36 UPG atomic domains. Each ring: `{ id, label, description, domain_ids }`. Non-paginated.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"rings\": [\n    {\n      \"id\": \"nucleus\",\n      \"label\": \"Product\",\n      \"description\": \"The seed\",\n      \"domain_ids\": [\n        \"portfolio\",\n        \"workspace\"\n      ]\n    },\n    {\n      \"id\": \"understand\",\n      \"label\": \"Understand\",\n      \"description\": \"Who are we building for?\",\n      \"domain_ids\": [\n        \"user\",\n        \"user_research\",\n        \"market_intelligence\",\n        \"discovery\",\n        \"validation\",\n        \"feedback\"\n      ]\n    },\n    {\n      \"id\": \"define\",\n      \"label\": \"Define\",\n      \"description\": \"What are we building?\",\n      \"domain_ids\": [\n        \"strategy\",\n        \"product_spec\",\n        \"legal\",\n        \"ux_design\",\n        \"design_system\",\n        \"brand\"\n      ]\n    },\n    {\n      \"id\": \"build\",\n      \"label\": \"Build\",\n      \"description\": \"How do we construct it?\",\n      \"domain_ids\": [\n        \"engineering\",\n        \"devops\",\n        \"testing\",\n        \"security\",\n        \"accessibility\",\n        \"data_analytics\",\n        \"ai\",\n        \"automation\"\n      ]\n    },\n    {\n      \"id\": \"grow\",\n      \"label\": \"Grow\",\n      \"description\": \"How do we make money?\",\n      \"domain_ids\": [\n        \"business_model\",\n        \"growth\",\n        \"go_to_market\",\n        \"pricing\",\n        \"sales\",\n        \"marketing\"\n      ]\n    },\n    {\n      \"id\": \"operate\",\n      \"label\": \"Operate\",\n      \"description\": \"How do we serve?\",\n      \"domain_ids\": [\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "get_domain_ring",
+        "list_domains",
+        "get_domain_guide"
+      ],
+      "source": "src/tools/spec.ts:1860",
+      "symbol": "listDomainRings",
+      "returns": "JSON: `{ rings: UPGDomainRing[], total: number }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "list_domains",
+      "description": "List domains. Default (`with_guide_only: true`) returns every domain with a canonical usage guide: id + `anchor_entity` + `creation_sequence`. Pass `with_guide_only: false` to enumerate every atomic domain from `UPG_DOMAINS`: id + label + description + types + `has_guide`. The two shapes are disjoint by the boolean.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "with_guide_only": {
+            "type": "boolean",
+            "description": "Default true. Returns only domains with a canonical usage guide (compact id + anchor_entity + creation_sequence). Pass false to return every atomic domain (id + label + description + types + has_guide)."
+          }
+        }
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"count\": 36,\n  \"domains\": [\n    {\n      \"domain_id\": \"portfolio\",\n      \"anchor_entity\": \"organization\",\n      \"creation_sequence\": [\n        \"organization\",\n        \"portfolio\",\n        \"product_area\"\n      ]\n    },\n    {\n      \"domain_id\": \"workspace\",\n      \"anchor_entity\": \"workspace\",\n      \"creation_sequence\": [\n        \"workspace\"\n      ]\n    },\n    {\n      \"domain_id\": \"user\",\n      \"anchor_entity\": \"persona\",\n      \"creation_sequence\": [\n        \"persona\",\n        \"job\",\n        \"need\",\n        \"desired_outcome\",\n        \"job_step\",\n        \"switching_cost\"\n      ]\n    },\n    {\n      \"domain_id\": \"user_research\",\n      \"anchor_entity\": \"research_study\",\n      \"creation_sequence\": [\n        \"research_study\",\n        \"research_question\",\n        \"interview_guide\",\n        \"participant\",\n        \"observation\",\n        \"quote\",\n        \"survey_response\",\n        \"affinity_cluster\",\n        \"insight\"\n      ]\n    },\n    {\n      \"domain_id\": \"market_intelligence\",\n      \"anchor_entity\": \"competitive_analysis\",\n      \"creation_sequence\": [\n        \"competitive_analysis\",\n        \"competitor\",\n        \"competitor_feature\",\n        \"market_trend\",\n        \"market_segment\",\n        \"classification_axis\",\n        \"classification_value\"\n      ]\n    },\n    {\n      \"domain_id\": \"discovery\",\n      \"anchor_entity\": \"opportunity\",\n      \"creation_sequence\": [\n        \"opportunity\",\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "get_domain_guide",
+        "list_domain_rings",
+        "get_domain_ring",
+        "list_regions",
+        "list_entity_types"
+      ],
+      "source": "src/tools/spec.ts:710",
+      "symbol": "listDomains",
+      "returns": "JSON: `{ count, domains: Array<{ domain_id, anchor_entity, creation_sequence } | { domain_id, label, description, types, has_guide }> }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "list_edge_migrations",
+      "description": "List every edge-key migration from `UPG_EDGE_MIGRATIONS` (renamed or dropped canonical edge keys, e.g. `persona_has_jtbd` → `persona_pursues_job`). Each row: `{ kind, from, to?, since }` where `kind` is `rename` or `drop`. Optional `from_edge` exact-matches `from`.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "from_edge": {
+            "type": "string",
+            "description": "Exact-match filter on the deprecated edge key (e.g. \"persona_has_jtbd\")."
+          }
+        }
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"migrations\": [\n    {\n      \"kind\": \"rename\",\n      \"from\": \"solution_proposes_hypothesis_claim\",\n      \"to\": \"solution_proposes_hypothesis\",\n      \"since\": \"0.4.0\"\n    },\n    {\n      \"kind\": \"rename\",\n      \"from\": \"hypothesis_claim_requires_experiment_plan\",\n      \"to\": \"hypothesis_requires_experiment_plan\",\n      \"since\": \"0.4.0\"\n    },\n    {\n      \"kind\": \"rename\",\n      \"from\": \"hypothesis_claim_planned_via_test_plan\",\n      \"to\": \"hypothesis_planned_via_test_plan\",\n      \"since\": \"0.4.0\"\n    },\n    {\n      \"kind\": \"rename\",\n      \"from\": \"hypothesis_claim_investigated_via_research_plan\",\n      \"to\": \"hypothesis_investigated_via_research_plan\",\n      \"since\": \"0.4.0\"\n    },\n    {\n      \"kind\": \"rename\",\n      \"from\": \"learning_updates_hypothesis_claim\",\n      \"to\": \"learning_updates_hypothesis\",\n      \"since\": \"0.4.0\"\n    },\n    {\n      \"kind\": \"rename\",\n      \"from\": \"learning_refines_hypothesis_claim\",\n      \"to\": \"learning_refines_hypothesis\",\n      \"since\": \"0.4.0\"\n    },\n    {\n      \"kind\": \"rename\",\n      \"from\": \"assumption_becomes_hypothesis_claim\",\n      \"to\": \"assumption_becomes_hypothesis\",\n      \"since\": \"0.4.0\"\n    },\n    {\n      \"kind\": \"rename\",\n      \"from\": \"experiment_run_validates_hypothesis_claim\",\n      \"to\": \"experiment_run_validates_hypothesis\",\n      \"since\": \"0.4.0\"\n    },\n    {\n      \"kind\": \"rename\",\n      \"from\":\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "list_type_migrations",
+        "list_split_migrations",
+        "rename_edge_type",
+        "list_edge_types",
+        "validate_graph"
+      ],
+      "source": "src/tools/spec.ts:1644",
+      "symbol": "listEdgeMigrations",
+      "returns": "JSON: `{ migrations: [{ kind, from, to?, since }], total: number }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "list_edge_types",
+      "description": "List every canonical edge type from `UPG_EDGE_CATALOG`, optionally narrowed by `source_type` and/or `target_type`. Each entry carries the edge key (`type`), forward/reverse verbs, classification, and endpoint types. The polymorphic wildcard `\"node\"` is preserved on polymorphic edges.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "source_type": {
+            "type": "string",
+            "description": "Exact-match filter on UPGEdgeDefinition.source_type. Pass \"node\" to find polymorphic edges with a wildcard source."
+          },
+          "target_type": {
+            "type": "string",
+            "description": "Exact-match filter on UPGEdgeDefinition.target_type."
+          }
+        }
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"count\": 938,\n  \"edges\": [\n    {\n      \"type\": \"product_targets_persona\",\n      \"forward_verb\": \"targets\",\n      \"reverse_verb\": \"targeted_by\",\n      \"classification\": \"semantic\",\n      \"source_type\": \"product\",\n      \"target_type\": \"persona\"\n    },\n    {\n      \"type\": \"persona_pursues_job\",\n      \"forward_verb\": \"pursues\",\n      \"reverse_verb\": \"pursued_by\",\n      \"classification\": \"semantic\",\n      \"source_type\": \"persona\",\n      \"target_type\": \"job\"\n    },\n    {\n      \"type\": \"persona_experiences_need\",\n      \"forward_verb\": \"experiences\",\n      \"reverse_verb\": \"experienced_by\",\n      \"classification\": \"semantic\",\n      \"source_type\": \"persona\",\n      \"target_type\": \"need\"\n    },\n    {\n      \"type\": \"persona_aspires_to_desired_outcome\",\n      \"forward_verb\": \"aspires_to\",\n      \"reverse_verb\": \"aspirational_for\",\n      \"classification\": \"hierarchy\",\n      \"source_type\": \"persona\",\n      \"target_type\": \"desired_outcome\"\n    },\n    {\n      \"type\": \"persona_incurs_switching_cost\",\n      \"forward_verb\": \"incurs\",\n      \"reverse_verb\": \"incurred_by\",\n      \"classification\": \"hierarchy\",\n      \"source_type\": \"persona\",\n      \"target_type\": \"switching_cost\"\n    },\n    {\n      \"type\": \"job_surfaces_need\",\n      \"forward_verb\": \"surfaces\",\n      \"reverse_verb\": \"surfaces_from\",\n      \"classification\": \"causal\",\n      \"source_type\": \"job\",\n      \"target_type\": \"need\"\n    },\n    {\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "get_edge_type",
+        "resolve_edge_for_pair",
+        "list_cross_edge_types",
+        "list_edge_migrations",
+        "create_edge"
+      ],
+      "source": "src/tools/spec.ts:858",
+      "symbol": "listEdgeTypes",
+      "returns": "JSON: `{ count, edges: Array<{ type, forward_verb, reverse_verb, classification, source_type, target_type }> }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "list_entity_types",
+      "description": "List canonical entity types from `UPG_ENTITY_META` (source of truth for ontology evolution). Every active, deprecated, or removed type with its immutable `type_id`, maturity tier, and version metadata. Paginated (default 50, max 200). Filters AND together and apply before pagination: `domain` (atomic-domain id), `maturity` (`draft` / `proposed` / `stable` / `deprecated` / `removed`), `deprecated` (boolean shortcut). Each row carries the full `EntityTypeMeta` plus resolved `domain_id` (null if no atomic-domain mapping).",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "domain": {
+            "type": "string",
+            "description": "Exact-match atomic-domain id (e.g. \"user\", \"market_intelligence\")."
+          },
+          "maturity": {
+            "type": "string",
+            "enum": [
+              "draft",
+              "proposed",
+              "stable",
+              "deprecated",
+              "removed"
+            ],
+            "description": "Exact-match UPGEntityTypeMaturity."
+          },
+          "deprecated": {
+            "type": "boolean",
+            "description": "true → only deprecated types; false → exclude deprecated and removed types (the active set). Composes with maturity via AND."
+          },
+          "limit": {
+            "type": "number",
+            "description": "Page size (default 50, max 200)."
+          },
+          "cursor": {
+            "type": "string",
+            "description": "Opaque pagination cursor. Pass next_cursor from a previous response."
+          }
+        }
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"total\": 349,\n  \"count\": 50,\n  \"types\": [\n    {\n      \"name\": \"product\",\n      \"type_id\": \"ent_001\",\n      \"maturity\": \"stable\",\n      \"since\": \"0.1.0\",\n      \"domain_id\": \"strategy\"\n    },\n    {\n      \"name\": \"outcome\",\n      \"type_id\": \"ent_002\",\n      \"maturity\": \"stable\",\n      \"since\": \"0.1.0\",\n      \"domain_id\": \"strategy\"\n    },\n    {\n      \"name\": \"kpi\",\n      \"type_id\": \"ent_003\",\n      \"maturity\": \"deprecated\",\n      \"since\": \"0.1.0\",\n      \"deprecated_in\": \"0.1.0\",\n      \"replacement\": \"metric\",\n      \"domain_id\": null\n    },\n    {\n      \"name\": \"objective\",\n      \"type_id\": \"ent_004\",\n      \"maturity\": \"stable\",\n      \"since\": \"0.1.0\",\n      \"domain_id\": \"strategy\"\n    },\n    {\n      \"name\": \"key_result\",\n      \"type_id\": \"ent_005\",\n      \"maturity\": \"stable\",\n      \"since\": \"0.1.0\",\n      \"domain_id\": \"strategy\"\n    },\n    {\n      \"name\": \"metric\",\n      \"type_id\": \"ent_006\",\n      \"maturity\": \"stable\",\n      \"since\": \"0.1.0\",\n      \"domain_id\": \"strategy\"\n    },\n    {\n      \"name\": \"metric_quality_assessment\",\n      \"type_id\": \"ent_339\",\n      \"maturity\": \"proposed\",\n      \"since\": \"0.2.2\",\n      \"domain_id\": \"strategy\"\n    },\n    {\n      \"name\": \"vision\",\n      \"type_id\": \"ent_007\",\n      \"maturity\": \"stable\",\n      \"since\": \"0.1.0\",\n      \"domain_id\": \"strategy\"\n    },\n    {\n      \"name\": \"mission\",\n      \"type_id\": \"ent_008\",\n      \"maturity\": \"stable\",\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "get_entity_meta",
+        "get_entity_schema",
+        "list_type_labels",
+        "list_type_migrations",
+        "list_domains"
+      ],
+      "source": "src/tools/spec.ts:1284",
+      "symbol": "listEntityTypes",
+      "returns": "JSON: `{ total, count, next_cursor?, types: Array<EntityTypeMeta & { domain_id: string | null }> }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "list_framework_categories",
+      "description": "List valid framework category values from `UPG_FRAMEWORK_CATEGORIES` (e.g. \"strategy\", \"prioritization\", \"discovery\", \"growth\", \"engineering\"). Use as valid values for the `category` filter on `list_frameworks` / `get_framework`.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"categories\": [\n    \"prioritization\",\n    \"strategy\",\n    \"discovery\",\n    \"business_model\",\n    \"metrics\",\n    \"validation\",\n    \"planning\",\n    \"competitive\",\n    \"design\",\n    \"ux_research\",\n    \"user_understanding\",\n    \"research\",\n    \"accessibility\",\n    \"feedback_voc\",\n    \"engineering\",\n    \"devops\",\n    \"security\",\n    \"qa_testing\",\n    \"ai_ml\",\n    \"agentic\",\n    \"growth\",\n    \"marketing\",\n    \"go_to_market\",\n    \"sales\",\n    \"pricing\",\n    \"data_analytics\",\n    \"legal_compliance\",\n    \"customer_success\",\n    \"team_process\",\n    \"program_mgmt\",\n    \"content\",\n    \"education\",\n    \"partnerships\",\n    \"localisation\",\n    \"portfolio\"\n  ],\n  \"total\": 35\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "list_frameworks",
+        "list_framework_structure_patterns"
+      ],
+      "source": "src/tools/spec.ts:1816",
+      "symbol": "listFrameworkCategories",
+      "returns": "JSON: `{ categories: string[], total: number }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "list_framework_structure_patterns",
+      "description": "List valid framework structure-pattern values from `UPG_STRUCTURE_PATTERNS`. Visual topological shapes: tree, table, matrix, funnel, collection, quadrant, flow. Mirrors `UPGFramework.structure.pattern`.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"patterns\": [\n    \"tree\",\n    \"table\",\n    \"matrix\",\n    \"funnel\",\n    \"collection\",\n    \"quadrant\",\n    \"flow\"\n  ],\n  \"total\": 7\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "list_frameworks",
+        "list_framework_categories",
+        "get_framework"
+      ],
+      "source": "src/tools/spec.ts:1837",
+      "symbol": "listFrameworkStructurePatterns",
+      "returns": "JSON: `{ patterns: string[], total: number }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "list_frameworks",
+      "description": "List canonical `UPGFramework` definitions (several hundred records 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.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "category": {
+            "type": "string",
+            "description": "Exact-match filter on UPGFramework.category (e.g. \"strategy\", \"prioritization\")."
+          },
+          "limit": {
+            "type": "number",
+            "description": "Page size (default 50, max 200)."
+          },
+          "cursor": {
+            "type": "string",
+            "description": "Opaque pagination cursor. Pass next_cursor from a previous response."
+          }
+        }
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"total\": 216,\n  \"count\": 50,\n  \"frameworks\": [\n    {\n      \"id\": \"rice-scoring\",\n      \"approach_ids\": [\n        \"prioritise\"\n      ],\n      \"name\": \"RICE Scoring\",\n      \"version\": \"1.0.0\",\n      \"description\": \"Score features and opportunities by Reach, Impact, Confidence, and Effort to produce a ranked priority list.\",\n      \"category\": \"prioritization\",\n      \"origin\": {\n        \"type\": \"practitioner\",\n        \"attribution\": \"Intercom (Sean McBride)\",\n        \"description\": \"Developed at Intercom as a way to quantify feature prioritisation. Published as a blog post that became an industry standard.\",\n        \"url\": \"https://www.intercom.com/blog/rice-simple-prioritization-for-product-managers/\",\n        \"year\": 2014,\n        \"license\": \"open_attribution\"\n      },\n      \"tags\": [\n        \"prioritization\",\n        \"table\"\n      ],\n      \"slots\": [\n        {\n          \"label\": \"Items to score\",\n          \"entityTypeId\": \"feature\",\n          \"description\": \"Features, opportunities, or solutions being evaluated\"\n        },\n        {\n          \"label\": \"Reach\",\n          \"entityTypeId\": \"feature\",\n          \"description\": \"How many users does this affect per quarter?\"\n        },\n        {\n          \"label\": \"Impact\",\n          \"entityTypeId\": \"feature\",\n          \"description\": \"How much does this move the target outcome?\"\n        },\n        {\n          \"label\":\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "get_framework",
+        "list_framework_categories",
+        "list_framework_structure_patterns",
+        "prioritise",
+        "list_approaches"
+      ],
+      "source": "src/tools/spec.ts:778",
+      "symbol": "listFrameworks",
+      "returns": "JSON: `{ total, count, next_cursor?, frameworks: UPGFramework[] }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "list_lenses",
+      "description": "List every canonical `UPGLens` from `@unified-product-graph/core`: Product, Design, Engineering, Growth, Business, Research, Marketing, Full. Returns a compact summary per lens: id, name, description, icon, audience, perspective, `framework_id`, `playbook_id`, `visible_domain_count`, `intelligence_prompt_count`. Use `get_lens` for the full record.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"count\": 8,\n  \"lenses\": [\n    {\n      \"id\": \"product\",\n      \"name\": \"Product\",\n      \"description\": \"Full graph, PM vocabulary, outcome-driven workflow\",\n      \"icon\": \"target\",\n      \"audience\": \"Product managers, founders making strategic decisions, and anyone thinking about what to build and why\",\n      \"perspective\": \"Sees the product as a system of outcomes, opportunities, and validated bets. Outcome-driven, evidence-aware, strategically oriented.\",\n      \"framework_id\": \"ost\",\n      \"visible_domain_count\": 0,\n      \"intelligence_prompt_count\": 5\n    },\n    {\n      \"id\": \"ux_design\",\n      \"name\": \"Design\",\n      \"description\": \"User-centric view with design vocabulary, journey-first workflow\",\n      \"icon\": \"pen-tool\",\n      \"audience\": \"Designers, UX researchers, and anyone focused on the user experience\",\n      \"perspective\": \"Sees the product through the eyes of the people using it. Journey-first, evidence-based, obsessed with friction and delight.\",\n      \"framework_id\": \"design_thinking\",\n      \"playbook_id\": \"playbook:experience-design-brand\",\n      \"visible_domain_count\": 7,\n      \"intelligence_prompt_count\": 5\n    },\n    {\n      \"id\": \"engineering\",\n      \"name\": \"Engineering\",\n      \"description\": \"Architecture-first view of the product as a technical system\",\n      \"icon\": \"cpu\",\n      \"audience\": \"Developers, CTOs, and anyone building the technical\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "get_lens",
+        "list_regions",
+        "list_playbooks",
+        "list_frameworks"
+      ],
+      "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 }> }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "list_lifecycles",
+      "description": "List lifecycle definitions from `UPG_LIFECYCLES`. Response includes `free_types` (`UPG_LIFECYCLE_FREE_TYPES`: static types with no phase progression) and `planned_types` (`UPG_LIFECYCLE_PLANNED_TYPES`: lifecycle planned but not yet authored). Filters: `entity_type` (exact-match), `lifecycle_only` (when true, omits the free/planned lists).",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "entity_type": {
+            "type": "string",
+            "description": "Exact-match entity type name (e.g. \"feature\", \"hypothesis\"). Returns at most one lifecycle."
+          },
+          "lifecycle_only": {
+            "type": "boolean",
+            "description": "When true, omit free_types and planned_types from response."
+          }
+        }
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"total\": 189,\n  \"lifecycles\": [\n    {\n      \"entity_type\": \"product\",\n      \"initial_phase\": \"concept\",\n      \"terminal_phases\": [\n        \"sunset\"\n      ],\n      \"phases\": [\n        {\n          \"id\": \"concept\",\n          \"label\": \"Concept\",\n          \"description\": \"Napkin idea. Problem shape and solution sketch, pre-validation.\",\n          \"transitions_to\": [\n            \"validation\",\n            \"build\",\n            \"beta\",\n            \"launch\",\n            \"growth\",\n            \"mature\",\n            \"sunset\"\n          ]\n        },\n        {\n          \"id\": \"validation\",\n          \"label\": \"Validation\",\n          \"description\": \"Testing demand. User conversations and experiments pressure-test assumptions before build commits.\",\n          \"transitions_to\": [\n            \"build\",\n            \"beta\",\n            \"launch\",\n            \"growth\",\n            \"mature\",\n            \"sunset\"\n          ]\n        },\n        {\n          \"id\": \"build\",\n          \"label\": \"Build\",\n          \"description\": \"Actively developing v1. Core functionality is being authored, pre-user.\",\n          \"transitions_to\": [\n            \"beta\",\n            \"launch\",\n            \"growth\",\n            \"mature\",\n            \"sunset\"\n          ]\n        },\n        {\n          \"id\": \"beta\",\n          \"label\": \"Beta\",\n          \"description\": \"Early users, iterating. Feature-complete enough to learn from,\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "get_lifecycle",
+        "list_entity_types",
+        "get_entity_meta"
+      ],
+      "source": "src/tools/spec.ts:1709",
+      "symbol": "listLifecycles",
+      "returns": "JSON: `{ lifecycles, total, free_types: string[], planned_types: string[] }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "list_playbooks",
+      "description": "List canonical UPG playbooks from `@unified-product-graph/core`. Each playbook bootstraps a region; its `creation_sequence` answers \"what to create when populating this region\". Filters: `region`, `canonical_only`, `framework_id`. The catalog spans 10 regions: one canonical playbook per region, plus specialised playbooks (three carry a `framework_id`: BMC, AARRR, build-measure-learn).",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "region": {
+            "type": "string",
+            "description": "Exact-match UPGRegionId (e.g. \"users_needs\", \"business_gtm_growth\")."
+          },
+          "canonical_only": {
+            "type": "boolean",
+            "description": "When true, return only the canonical playbook per region (W1 invariant restated)."
+          },
+          "framework_id": {
+            "type": "string",
+            "description": "Exact-match UPGFramework.id (e.g. \"business-model-canvas\", \"pirate-metrics-aarrr\")."
+          }
+        }
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"count\": 23,\n  \"playbooks\": [\n    {\n      \"id\": \"playbook:strategy-outcomes\",\n      \"name\": \"Strategy & Outcomes\",\n      \"version\": \"0.2.0\",\n      \"description\": \"Cascade vision through themes, outcomes, objectives, key results — and the bets you are making to get there.\",\n      \"region\": \"strategy_outcomes\",\n      \"is_canonical\": true,\n      \"target_anchor_entity\": \"objective\",\n      \"creation_sequence\": [\n        {\n          \"kind\": \"entity_sequence\",\n          \"order\": 1,\n          \"phase\": \"Vision & Mission\",\n          \"name\": \"Vision & Mission\",\n          \"prompt_hint\": \"Name what you are building toward and how you will get there. Vision is the destination; mission is the orientation. One of each — more is dilution.\",\n          \"entity_types\": [\n            \"vision\",\n            \"mission\"\n          ]\n        },\n        {\n          \"kind\": \"entity_sequence\",\n          \"order\": 2,\n          \"phase\": \"Themes\",\n          \"name\": \"Themes\",\n          \"prompt_hint\": \"Choose 2–4 strategic themes that focus the work. Past four, you have lost focus, not gained coverage.\",\n          \"entity_types\": [\n            \"strategic_theme\",\n            \"strategic_pillar\"\n          ]\n        },\n        {\n          \"kind\": \"entity_sequence\",\n          \"order\": 3,\n          \"phase\": \"Outcomes\",\n          \"name\": \"Outcomes\",\n          \"prompt_hint\": \"Frame the changes in the world the\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "get_playbook",
+        "list_regions",
+        "list_approaches",
+        "list_frameworks"
+      ],
+      "source": "src/tools/spec.ts:204",
+      "symbol": "listPlaybooks",
+      "returns": "JSON: `{ count, playbooks: UPGPlaybook[] }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "list_product_stages",
+      "description": "Return the canonical 9-stage product journey from `UPG_PRODUCT_STAGES` in order: concept → validation → build → beta → launch → growth → mature → maintenance → sunset. The closed enum used by `create_product`, `get_graph_digest` health logic, benchmark stage scoping, and anti-pattern stage filters.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"count\": 9,\n  \"stages\": [\n    \"concept\",\n    \"validation\",\n    \"build\",\n    \"beta\",\n    \"launch\",\n    \"growth\",\n    \"mature\",\n    \"maintenance\",\n    \"sunset\"\n  ]\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "list_benchmarks",
+        "list_anti_patterns",
+        "list_domain_rings",
+        "create_product"
+      ],
+      "source": "src/tools/spec.ts:1580",
+      "symbol": "listProductStages",
+      "returns": "JSON: `{ count, stages: readonly UPGProductStage[] }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "list_regions",
+      "description": "List the 10 canonical UPG super-domain regions from `UPG_REGIONS`. Returns a compact summary per region: id, label, order, shape, `mental_model`, `anchor_type`, `composes_atomic_domains`, `entity_count`, `intra_edge_count`, `boundary_edge_count`. Fixed list, non-paginated.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"count\": 10,\n  \"regions\": [\n    {\n      \"id\": \"strategy_outcomes\",\n      \"label\": \"Strategy & Outcomes\",\n      \"order\": 1,\n      \"shape\": \"cascade\",\n      \"mental_model\": \"Aspiration → direction → bet → measurable → proof.\",\n      \"anchor_type\": \"objective\",\n      \"composes_atomic_domains\": [\n        \"strategy\"\n      ],\n      \"entity_count\": 13,\n      \"intra_edge_count\": 19,\n      \"boundary_edge_count\": 7\n    },\n    {\n      \"id\": \"users_needs\",\n      \"label\": \"Users & Needs\",\n      \"order\": 2,\n      \"shape\": \"convergent\",\n      \"mental_model\": \"Who → what they want to do → what is in their way → what they would accept as done.\",\n      \"anchor_type\": \"persona\",\n      \"composes_atomic_domains\": [\n        \"user\"\n      ],\n      \"entity_count\": 7,\n      \"intra_edge_count\": 5,\n      \"boundary_edge_count\": 22\n    },\n    {\n      \"id\": \"discovery_research_validation\",\n      \"label\": \"Discovery, Research & Validation\",\n      \"order\": 3,\n      \"shape\": \"directed-cyclic\",\n      \"mental_model\": \"Question → hypothesis → test → evidence → decision → loop back.\",\n      \"anchor_type\": \"opportunity\",\n      \"composes_atomic_domains\": [\n        \"discovery\",\n        \"validation\",\n        \"user_research\"\n      ],\n      \"entity_count\": 19,\n      \"intra_edge_count\": 13,\n      \"boundary_edge_count\": 11\n    },\n    {\n      \"id\": \"market_competitive\",\n      \"label\": \"Market & Competitive\",\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "get_region",
+        "get_region_for_entity_type",
+        "list_domains",
+        "list_playbooks"
+      ],
+      "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 }> }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "list_scales",
+      "description": "List every spec-defined assessment scale from `UPG_SCALES` (canonical vocabulary for `UPGAssessment` values). Each scale carries id, label, description, min, max, steps, and per-point labels + descriptions. Non-paginated. External `scale_extensions` are graph-instance–scoped and excluded here.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"scales\": [\n    {\n      \"id\": \"reach_5\",\n      \"label\": \"Reach (5-point)\",\n      \"description\": \"How many users experience this problem or benefit from this feature\",\n      \"min\": 1,\n      \"max\": 5,\n      \"steps\": 5,\n      \"points\": [\n        {\n          \"value\": 1,\n          \"label\": \"Almost no one\",\n          \"description\": \"Affects <5% of users\"\n        },\n        {\n          \"value\": 2,\n          \"label\": \"A few\",\n          \"description\": \"Affects 5-20% of users\"\n        },\n        {\n          \"value\": 3,\n          \"label\": \"Some\",\n          \"description\": \"Affects 20-50% of users\"\n        },\n        {\n          \"value\": 4,\n          \"label\": \"Most\",\n          \"description\": \"Affects 50-80% of users\"\n        },\n        {\n          \"value\": 5,\n          \"label\": \"Nearly everyone\",\n          \"description\": \"Affects >80% of users\"\n        }\n      ]\n    },\n    {\n      \"id\": \"frequency_5\",\n      \"label\": \"Frequency (5-point)\",\n      \"description\": \"How often the problem or situation occurs\",\n      \"min\": 1,\n      \"max\": 5,\n      \"steps\": 5,\n      \"points\": [\n        {\n          \"value\": 1,\n          \"label\": \"Rarely\",\n          \"description\": \"Less than once a month\"\n        },\n        {\n          \"value\": 2,\n          \"label\": \"Occasionally\",\n          \"description\": \"A few times a month\"\n        },\n        {\n          \"value\": 3,\n          \"label\": \"Sometimes\",\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "get_scale",
+        "get_entity_schema"
+      ],
+      "source": "src/tools/spec.ts:1782",
+      "symbol": "listScales",
+      "returns": "JSON: `{ scales: UPGScaleDefinition[], total: number }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "list_split_migrations",
+      "description": "List every 1→N split migration from `UPG_SPLIT_MIGRATIONS` (\"one type became multiple types\" rules, e.g. `experiment` → `experiment_plan` + `experiment_run`; `hypothesis` → `hypothesis_claim` + `hypothesis_evidence`). Each row: the full `UPGSplitMigration` record plus `since`. Non-paginated.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"splits\": [\n    {\n      \"kind\": \"status_routed\",\n      \"from\": \"experiment\",\n      \"status_property\": \"status\",\n      \"produces\": [\n        {\n          \"ref\": \"plan\",\n          \"type\": \"experiment_plan\",\n          \"keep_props\": [\n            \"__id\",\n            \"method\",\n            \"sample_size\",\n            \"expected_lift\",\n            \"expected_lift_unit\"\n          ],\n          \"defaults\": {}\n        },\n        {\n          \"ref\": \"run\",\n          \"type\": \"experiment_run\",\n          \"keep_props\": [\n            \"actual_lift\",\n            \"start_date\",\n            \"end_date\"\n          ],\n          \"defaults\": {}\n        }\n      ],\n      \"routing\": {\n        \"draft\": {\n          \"spawn\": [\n            \"plan\"\n          ],\n          \"plan\": {\n            \"defaults\": {\n              \"status\": \"drafted\"\n            }\n          }\n        },\n        \"planned\": {\n          \"spawn\": [\n            \"plan\"\n          ],\n          \"plan\": {\n            \"defaults\": {\n              \"status\": \"scheduled\"\n            }\n          }\n        },\n        \"cancelled\": {\n          \"spawn\": [\n            \"plan\"\n          ],\n          \"plan\": {\n            \"defaults\": {\n              \"status\": \"cancelled\"\n            }\n          }\n        },\n        \"running\": {\n          \"spawn\": [\n            \"plan\",\n            \"run\"\n          ],\n          \"plan\": {\n            \"defaults\": {\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "list_type_migrations",
+        "list_edge_migrations",
+        "migrate_type",
+        "validate_graph"
+      ],
+      "source": "src/tools/spec.ts:1681",
+      "symbol": "listSplitMigrations",
+      "returns": "JSON: `{ splits: [...], total: number }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "list_type_labels",
+      "description": "List canonical `UPGTypeLabel` entries: each entity type's display label, alt-labels (synonyms), per-framework labels, and designation labels where applicable. Paginated (default 100, max 500). Cursor is opaque base64 (`offset:N`), same convention as `list_frameworks`. External MCP apps need labels for rendering.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "limit": {
+            "type": "number",
+            "description": "Page size (default 100, max 500)."
+          },
+          "cursor": {
+            "type": "string",
+            "description": "Opaque pagination cursor. Pass next_cursor from a previous response."
+          }
+        }
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"total\": 312,\n  \"count\": 100,\n  \"labels\": [\n    {\n      \"id\": \"product\",\n      \"canonical_label\": \"Product\",\n      \"alt_labels\": [\n        \"offering\",\n        \"app\",\n        \"service\",\n        \"platform\",\n        \"product\"\n      ],\n      \"framework_labels\": {\n        \"three-horizons\": \"Product\",\n        \"marketing-mix-4ps\": \"Product\"\n      }\n    },\n    {\n      \"id\": \"outcome\",\n      \"canonical_label\": \"Outcome\",\n      \"alt_labels\": [\n        \"desired outcome\",\n        \"product outcome\",\n        \"business outcome\",\n        \"target outcome\",\n        \"root outcome\",\n        \"consequences\",\n        \"what went well\",\n        \"outcome\"\n      ],\n      \"framework_labels\": {\n        \"opportunity-solution-tree\": \"Root Outcome\",\n        \"adr-log\": \"Consequences\",\n        \"retrospective\": \"What Went Well\",\n        \"metrics-tree\": \"Outcome\",\n        \"ost\": \"Desired Outcome\",\n        \"okr_tree\": \"Outcome\"\n      }\n    },\n    {\n      \"id\": \"objective\",\n      \"canonical_label\": \"Objective\",\n      \"alt_labels\": [\n        \"goal\",\n        \"strategic goal\",\n        \"team goal\",\n        \"objective\"\n      ],\n      \"framework_labels\": {\n        \"okr-framework\": \"Objective\",\n        \"okr_tree\": \"Objective\"\n      }\n    },\n    {\n      \"id\": \"key_result\",\n      \"canonical_label\": \"Key Result\",\n      \"alt_labels\": [\n        \"kr\",\n        \"measurable result\",\n        \"target\",\n        \"key result 1\",\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "get_type_label",
+        "list_entity_types",
+        "get_entity_meta"
+      ],
+      "source": "src/tools/spec.ts:1167",
+      "symbol": "listTypeLabels",
+      "returns": "JSON: `{ total, count, next_cursor?, labels: UPGTypeLabel[] }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "list_type_migrations",
+      "description": "List every type-rename migration from `UPG_MIGRATIONS` (version-scoped registry of deprecated `from` → canonical `to` renames, e.g. `pain_point` → `need`, `hypothesis` → `hypothesis_claim`). Each row: `{ from, to, since }` where `since` is the spec version that introduced it. Optional `from_type` exact-matches `from`.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "from_type": {
+            "type": "string",
+            "description": "Exact-match filter on the deprecated type name (e.g. \"pain_point\", \"hypothesis\")."
+          }
+        }
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"migrations\": [\n    {\n      \"from\": \"hypothesis_claim\",\n      \"to\": \"hypothesis\",\n      \"since\": \"0.4.0\"\n    },\n    {\n      \"from\": \"hypothesis_evidence\",\n      \"to\": \"evidence\",\n      \"since\": \"0.4.0\"\n    },\n    {\n      \"from\": \"story_task\",\n      \"to\": \"task\",\n      \"since\": \"0.4.0\"\n    },\n    {\n      \"from\": \"hypothesis\",\n      \"to\": \"hypothesis_claim\",\n      \"since\": \"0.2.8\"\n    },\n    {\n      \"from\": \"pain_point\",\n      \"to\": \"need\",\n      \"since\": \"0.1.0\"\n    },\n    {\n      \"from\": \"user_need\",\n      \"to\": \"need\",\n      \"since\": \"0.1.0\"\n    },\n    {\n      \"from\": \"research_insight\",\n      \"to\": \"insight\",\n      \"since\": \"0.1.0\"\n    },\n    {\n      \"from\": \"finding\",\n      \"to\": \"insight\",\n      \"since\": \"0.1.0\"\n    },\n    {\n      \"from\": \"ux_insight\",\n      \"to\": \"insight\",\n      \"since\": \"0.1.0\"\n    },\n    {\n      \"from\": \"highlight\",\n      \"to\": \"observation\",\n      \"since\": \"0.1.0\"\n    },\n    {\n      \"from\": \"kpi\",\n      \"to\": \"metric\",\n      \"since\": \"0.1.0\"\n    },\n    {\n      \"from\": \"north_star_metric\",\n      \"to\": \"metric\",\n      \"since\": \"0.1.0\"\n    },\n    {\n      \"from\": \"input_metric\",\n      \"to\": \"metric\",\n      \"since\": \"0.1.0\"\n    },\n    {\n      \"from\": \"metric_definition\",\n      \"to\": \"metric\",\n      \"since\": \"0.1.0\"\n    },\n    {\n      \"from\": \"ab_test\",\n      \"to\": \"experiment_run\",\n      \"since\": \"0.1.0\"\n    },\n    {\n      \"from\": \"growth_experiment\",\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "list_edge_migrations",
+        "list_split_migrations",
+        "migrate_type",
+        "migrate_properties",
+        "validate_graph",
+        "list_entity_types"
+      ],
+      "source": "src/tools/spec.ts:1613",
+      "symbol": "listTypeMigrations",
+      "returns": "JSON: `{ migrations: [{ from, to, since }], total: number }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "plan",
+      "description": "Plan approach: path of arrival to \"what should I build next?\". Returns the Plan record + invocation params wrapped in `{ approach_id, scope, generated_at, approach, params }`. The LLM consumes `signature_hint` and synthesises `{ missing_entities, coverage_score }` against the live graph. Optional `region` narrows scope.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "region": {
+            "type": "string",
+            "description": "Optional UPGRegionId. Narrows planning scope to a single region (e.g. \"users_needs\", \"business_gtm_growth\"). Omit for whole-graph planning."
+          }
+        }
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"approach_id\": \"plan\",\n  \"scope\": null,\n  \"generated_at\": \"2026-05-26T13:23:53.077Z\",\n  \"approach\": {\n    \"id\": \"plan\",\n    \"label\": \"Plan\",\n    \"description\": \"The path of arrival to \\\"what should I build next?\\\". Plan engages a region by surveying its entity coverage against canonical expectations and surfacing the missing scaffolding: the entities a healthy region carries that this graph does not. Cartographic sense: you are walking the coastline of a region and noting where the contour is incomplete, not deciding a strategy. Frameworks like Now/Next/Later, MoSCoW, and Wardley Mapping live within Plan as the named techniques for organising the gap-filling sequence.\",\n    \"question_answered\": \"what should I build next?\",\n    \"signature_hint\": \"({ region?: UPGRegionId }) → { missing_entities, coverage_score }\",\n    \"framework_id_examples\": [\n      \"now-next-later\",\n      \"moscow\",\n      \"wardley-map\",\n      \"okr-framework\",\n      \"three-horizons\"\n    ]\n  },\n  \"params\": {\n    \"region\": null\n  },\n  \"region\": null,\n  \"missing_entities\": [],\n  \"coverage_score\": 1,\n  \"expected_count\": 312,\n  \"covered_count\": 312,\n  \"execution_mode\": \"execution_v0_4_0\"\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "get_approach",
+        "list_playbooks",
+        "get_region",
+        "inspect",
+        "prioritise"
+      ],
+      "source": "src/tools/spec.ts:418",
+      "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\" }`.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "prioritise",
+      "description": "[LLM-mediated] This tool returns a routing envelope, not computed results. For user-facing prioritisation, invoke the /upg-prioritise skill instead of calling this tool directly. — Prioritise approach: path of arrival to \"what's most important?\". Returns the Prioritise record + invocation params + framework metadata in the family-resemblance envelope. Both `candidates` and `framework_id` are required. The LLM looks up the framework via `get_framework`, reads its scoring spec, and emits `{ ranked: [{ entity_id, score, rationale }], framework_used }`.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "candidates": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Required. entity_id[] to rank."
+          },
+          "framework_id": {
+            "type": "string",
+            "description": "Required. UPGFramework.id of the scoring lens (e.g. \"rice-scoring\", \"ice-scoring\", \"kano-model\", \"cost-of-delay\", \"wsjf\")."
+          }
+        },
+        "required": [
+          "candidates",
+          "framework_id"
+        ]
+      },
+      "throws": [
+        "textError when `candidates` or `framework_id` are missing/empty,\nor when `framework_id` is not in `UPG_FRAMEWORKS`."
+      ],
+      "examples": [],
+      "warnings": [],
+      "see": [
+        "get_approach",
+        "list_frameworks",
+        "get_framework",
+        "plan",
+        "trace"
+      ],
+      "source": "src/tools/spec.ts:517",
+      "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.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "reflect",
+      "description": "[LLM-mediated] This tool returns a routing envelope, not computed results. For user-facing reflection, invoke the /upg-reflect skill instead of calling this tool directly. — Reflect approach: path of arrival to \"what should I be questioning?\". Returns the Reflect record + invocation params in the family-resemblance envelope. The LLM consumes `mode` + `scope` + `signature_hint` and emits `{ prompts: [{ kind, question, target_entities? }] }`. `mode` is one of: `assumptions`, `alternatives`, `blind-spots`, `load-bearing`; omit for open reflection. `scope` accepts a region id, entity id, or `null` for whole-graph.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "scope": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Optional. Region id, entity id, or null for whole-graph."
+          },
+          "mode": {
+            "type": "string",
+            "description": "Optional. One of: assumptions, alternatives, blind-spots, load-bearing. Omit for open reflection.",
+            "enum": [
+              "assumptions",
+              "alternatives",
+              "blind-spots",
+              "load-bearing"
+            ]
+          }
+        }
+      },
+      "throws": [
+        "textError when `mode` is provided but not one of the 4 canonical\nnouns."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"approach_id\": \"reflect\",\n  \"scope\": null,\n  \"generated_at\": \"2026-05-26T13:23:53.082Z\",\n  \"approach\": {\n    \"id\": \"reflect\",\n    \"label\": \"Reflect\",\n    \"description\": \"The path of arrival to \\\"what should I be questioning?\\\". Reflect engages an optional scope (region, entity, or `null` for the whole graph) and emits structured prompts a thinker should consider: assumptions to test, alternatives to weigh, blind-spots to surface, load-bearing claims to verify. Mode is optional; absence is open reflection. Cartographic sense: before approaching the coastline, you are asking which features of your chart you have not actually verified; the prompts mark the parts of the map that may be conjecture. Five Whys, Pre-mortem, Red Team, and Devil's Advocate are the named techniques inside this approach.\",\n    \"question_answered\": \"what should I be questioning?\",\n    \"signature_hint\": \"({ scope?: UPGRegionId | entity_id | null, mode?: 'assumptions' | 'alternatives' | 'blind-spots' | 'load-bearing' }) → { prompts: [{ kind, question, target_entities? }] }\",\n    \"framework_id_examples\": [\n      \"five-whys\",\n      \"pre-mortem\",\n      \"red-team\",\n      \"devils-advocate\",\n      \"second-order-thinking\",\n      \"retrospective\",\n      \"four-forces-of-progress\",\n      \"assumption-canvas\",\n      \"win-loss-analysis\"\n    ]\n  },\n  \"params\": {\n    \"scope\": null,\n    \"mode\": null\n  },\n  \"prompts\": [\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "get_approach",
+        "inspect",
+        "plan",
+        "get_anti_pattern"
+      ],
+      "source": "src/tools/spec.ts:660",
+      "symbol": "reflect",
+      "returns": "JSON envelope: `{ approach_id, scope, generated_at, approach,\nparams, prompts, execution_mode: \"execution_v0_4_0\" }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "resolve_edge_for_pair",
+      "description": "Resolve the canonical `UPGEdgeType` for a `source_type` → `target_type` containment pair. Wraps `resolveContainmentEdge` / `UPG_EDGE_PAIR_MAP`. Adapter-critical: every import adapter (Markdown, Notion, Linear, GitHub) uses it to look up the right `_contains_` edge before falling back to a polymorphic edge. Returns `{ edge_type: null }` when the pair is uncatalogued.",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "source_type": {
+            "type": "string",
+            "description": "Parent / source entity type."
+          },
+          "target_type": {
+            "type": "string",
+            "description": "Child / target entity type."
+          }
+        },
+        "required": [
+          "source_type",
+          "target_type"
+        ]
+      },
+      "throws": [
+        "textError when `source_type` or `target_type` is missing."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"source_type\": \"example\",\n  \"target_type\": \"example\"\n}",
+          "output": "{\n  \"source_type\": \"example\",\n  \"target_type\": \"example\",\n  \"edge_type\": null\n}"
+        }
+      ],
+      "warnings": [
+        "Returns `edge_type: null` when no canonical pair is registered.\nAdapters MUST fall back to a polymorphic edge or skip the relationship,\nnot synthesise a non-canonical key."
+      ],
+      "see": [
+        "list_edge_types",
+        "get_edge_type",
+        "create_edge",
+        "trace"
+      ],
+      "source": "src/tools/spec.ts:1040",
+      "symbol": "resolveEdgeForPair",
+      "returns": "JSON: `{ source_type, target_type, edge_type: string | null,\nanchor_hint?, alternate_anchors?, adjacent_edges? }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "trace",
+      "description": "[LLM-mediated] This tool returns a routing envelope, not computed results. For user-facing tracing, invoke the /upg-trace skill instead of calling this tool directly. — Trace approach: path of arrival to \"walk a meaningful path through existing graph\". Returns the Trace record + invocation params in the family-resemblance envelope. The LLM uses `anchor` + `path` to compose `query()` calls and emits `{ trail: [{ depth, entity_id, edge_type_in }], reached: entity_id[] }`. `path` is type-shorthand: `[\"persona\",\"job\",\"feature\"]` walks persona→job→feature using the canonical edge per pair (via `resolve_edge_for_pair`). Optional `edges_override` selects non-canonical edges per hop; `null` per element means \"use canonical\".",
+      "domain": "spec",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "anchor": {
+            "type": "string",
+            "description": "Required. entity_id where the traversal starts."
+          },
+          "path": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Required. UPGEntityType[] type-shorthand path. Each step walks via the canonical edge for the source→target pair."
+          },
+          "edges_override": {
+            "type": "array",
+            "items": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "description": "Optional. Per-hop edge override array. Length must match path length; element null means \"use canonical edge for this pair\"."
+          }
+        },
+        "required": [
+          "anchor",
+          "path"
+        ]
+      },
+      "throws": [
+        "textError when `anchor` or `path` are missing/invalid."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"anchor\": \"ec3d5479-4947-4bd9-9e77-b5ee01beb851\",\n  \"path\": [\n    \"opportunity_drives_solution\"\n  ]\n}",
+          "output": "{\n  \"approach_id\": \"trace\",\n  \"scope\": \"ec3d5479-4947-4bd9-9e77-b5ee01beb851\",\n  \"generated_at\": \"2026-05-26T13:23:53.077Z\",\n  \"approach\": {\n    \"id\": \"trace\",\n    \"label\": \"Trace\",\n    \"description\": \"The path of arrival to \\\"walk a meaningful path through existing graph\\\". Trace engages an anchor entity and follows a path expressed as a UPGEntityType[] shorthand. Example: `[\\\"persona\\\", \\\"job\\\", \\\"feature\\\"]` walks persona→job→feature using the canonical edge for each pair (resolved via `resolve_edge_for_pair`). An optional `edges_override` array selects non-canonical edges per hop when a pair has multiple resolutions. Cartographic sense: you are tracing a route across charted terrain; anchor is the departure, path is the heading sequence, the canonical edges are the roads. No DSL invented; the shorthand IS the path expression.\",\n    \"question_answered\": \"walk a meaningful path through existing graph\",\n    \"signature_hint\": \"({ anchor: entity_id, path: UPGEntityType[], edges_override?: (string | null)[] }) → { trail: [{ depth, entity_id, edge_type_in }], reached: entity_id[] }\",\n    \"framework_id_examples\": [\n      \"opportunity-solution-tree\",\n      \"strategic-cascade\",\n      \"metrics-tree\",\n      \"user-journey-map\",\n      \"impact-map\",\n      \"dependency-map\"\n    ]\n  },\n  \"params\": {\n    \"anchor\": \"ec3d5479-4947-4bd9-9e77-b5ee01beb851\",\n    \"path\": [\n… (truncated)"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "get_approach",
+        "resolve_edge_for_pair",
+        "query",
+        "get_node",
+        "plan",
+        "prioritise"
+      ],
+      "source": "src/tools/spec.ts:597",
+      "symbol": "trace",
+      "returns": "JSON envelope: `{ approach_id, scope, generated_at, approach,\nparams, trail, reached, error?, halted_at_depth?,\nexecution_mode: \"execution_v0_4_0\" }`",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "apply_pull_changeset",
+      "description": "Apply cloud changes to the local `.upg` file. Takes cloud nodes and edges (from `export_upg_document` on the cloud server), computes the diff, merges into the local graph, and updates `.upg-sync` with new mappings. `strategy`: `cloud_wins` (default), `local_wins`, or `merge` (reports conflicts without resolving).",
+      "domain": "sync",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "cloud_nodes": {
+            "type": "array",
+            "description": "All cloud nodes (from export_upg_document)",
+            "items": {
+              "type": "object"
+            }
+          },
+          "cloud_edges": {
+            "type": "array",
+            "description": "All cloud edges (from export_upg_document)",
+            "items": {
+              "type": "object"
+            }
+          },
+          "cloud_product_id": {
+            "type": "string",
+            "description": "Cloud product ID"
+          },
+          "cloud_endpoint": {
+            "type": "string",
+            "description": "Cloud endpoint URL (e.g. https://cloud.unifiedproductgraph.org)"
+          },
+          "strategy": {
+            "type": "string",
+            "enum": [
+              "cloud_wins",
+              "local_wins",
+              "merge"
+            ],
+            "description": "Conflict resolution: cloud_wins (default), local_wins, or merge (report conflicts without resolving)"
+          }
+        },
+        "required": [
+          "cloud_nodes",
+          "cloud_edges",
+          "cloud_product_id"
+        ]
+      },
+      "throws": [
+        "Returns a textError when `cloud_nodes`, `cloud_edges`, or\n`cloud_product_id` is missing, or when sync-state I/O fails."
+      ],
+      "examples": [],
+      "warnings": [
+        "Mutates the active product. Always call `get_workspace_info`\nfirst to confirm the right product is loaded; otherwise cloud changes\nland in the wrong file. `merge` strategy returns conflicts without\napplying them; the caller must re-run with `cloud_wins`/`local_wins`\nto commit."
+      ],
+      "see": [
+        "push_to_cloud",
+        "get_sync_state",
+        "get_workspace_info",
+        "get_changes"
+      ],
+      "source": "src/tools/sync.ts:80",
+      "symbol": "applyPullChangeset",
+      "returns": "JSON: `{ nodes_created, nodes_updated, nodes_deleted,\nedges_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."
+    },
+    {
+      "name": "get_sync_state",
+      "description": "Read the `.upg-sync` file for the active product. Returns cloud product ID, ID mappings, last sync timestamp. Returns null when the product has never been pushed.",
+      "domain": "sync",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      },
+      "throws": [],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"synced\": false,\n  \"message\": \"No .upg-sync file found. This product has never been pushed to the cloud.\"\n}"
+        }
+      ],
+      "warnings": [],
+      "see": [
+        "push_to_cloud",
+        "apply_pull_changeset",
+        "get_workspace_info",
+        "get_changes"
+      ],
+      "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 }`.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "name": "push_to_cloud",
+      "description": "Push the current local graph to the cloud in one call. Reads the in-memory graph, POSTs to the cloud import endpoint, and creates or updates the `.upg-sync` file with ID mappings. Auto-discovers `cloud_endpoint` and `api_key` from a `upg-cloud` entry in `.mcp.json`. Recommended push path from Claude Code (zero context cost).",
+      "domain": "sync",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "cloud_endpoint": {
+            "type": "string",
+            "description": "Cloud base URL. Auto-discovered from .mcp.json upg-cloud entry if omitted."
+          },
+          "api_key": {
+            "type": "string",
+            "description": "UPG Cloud API key. Auto-discovered from .mcp.json upg-cloud entry if omitted."
+          },
+          "strategy": {
+            "type": "string",
+            "enum": [
+              "create_new",
+              "merge",
+              "replace"
+            ],
+            "description": "Import strategy. Default: create_new"
+          },
+          "product_id": {
+            "type": "string",
+            "description": "Optional. Push to an existing cloud product instead of creating new."
+          }
+        },
+        "required": []
+      },
+      "throws": [
+        "Returns a textError when credentials cannot be resolved, the cloud\nreturns a non-2xx response, or the sync file write fails."
+      ],
+      "examples": [],
+      "warnings": [
+        "Pushes the **currently-loaded** product. Call\n`get_workspace_info` first to confirm. Auto-discovers credentials\nfrom `.mcp.json`'s `upg-cloud` server entry; falls back to explicit\n`cloud_endpoint` + `api_key` arguments. Default `strategy: 'create_new'`\ncreates a fresh cloud product on every call; pass `product_id` to\ntarget an existing one."
+      ],
+      "see": [
+        "apply_pull_changeset",
+        "get_sync_state",
+        "get_workspace_info"
+      ],
+      "source": "src/tools/sync.ts:264",
+      "symbol": "pushToCloud",
+      "returns": "JSON: `{ success, product_id, nodes_created, edges_created,\nerrors, 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."
+    },
+    {
+      "name": "get_anti_pattern_violations_for",
+      "description": "Reverse lookup: given an entity id, return anti-pattern violations whose `target_entities` include the entity's type. Use after `validate_graph` to drill into one entity's implicated patterns. Matches by entity type today; tightens to specific ids in a future revision. Underpins the Inspect approach.",
+      "domain": "validation",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "entity_id": {
+            "type": "string",
+            "description": "Node id to look up."
+          }
+        },
+        "required": [
+          "entity_id"
+        ]
+      },
+      "throws": [
+        "textError when `entity_id` is missing or unknown."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{\n  \"entity_id\": \"ec3d5479-4947-4bd9-9e77-b5ee01beb851\"\n}",
+          "output": "{\n  \"entity_id\": \"ec3d5479-4947-4bd9-9e77-b5ee01beb851\",\n  \"type\": \"product\",\n  \"violations\": []\n}"
+        }
+      ],
+      "warnings": [
+        "Phase 1 matches by entity TYPE, not specific id. Every entity of\nthe same type shares the same violation set. Phase 1.x will tighten to\nper-id matching once `target_entities` carries ids."
+      ],
+      "see": [
+        "validate_graph",
+        "list_anti_patterns",
+        "get_anti_pattern",
+        "inspect"
+      ],
+      "source": "src/tools/validation.ts:880",
+      "symbol": "getAntiPatternViolationsFor",
+      "returns": "JSON: `{ entity_id, type, violations: [...] }`.",
+      "atomicity": "atomic (read-only)"
+    },
+    {
+      "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`.",
+      "domain": "validation",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "scope": {
+            "type": "string",
+            "enum": [
+              "all",
+              "entity_drift",
+              "edge_drift",
+              "property_drift",
+              "top_level_drift",
+              "lifecycle_drift",
+              "self_referential"
+            ],
+            "description": "Which drift class(es) to include in the response (default \"all\"). Counts in `summary` are always returned for every class."
+          },
+          "limit": {
+            "type": "number",
+            "description": "Max entries per class (default 100, max 1000)"
+          },
+          "severity": {
+            "type": "string",
+            "enum": [
+              "high",
+              "medium",
+              "low"
+            ],
+            "description": "Filter anti-pattern violations to one severity tier."
+          },
+          "anti_pattern_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Restrict anti-pattern evaluation to a subset of catalog ids (e.g. [\"features-without-hypotheses\"])."
+          },
+          "skip_drift": {
+            "type": "boolean",
+            "description": "Skip the schema-drift block. Only returns anti-pattern violations."
+          },
+          "skip_anti_patterns": {
+            "type": "boolean",
+            "description": "Skip anti-pattern evaluation. Only returns schema drift."
+          },
+          "if_changed_since": {
+            "type": "string",
+            "description": "Hash from a previous response. Returns { changed: false } if graph unchanged."
+          },
+          "include_polymorphic_upgrades": {
+            "type": "boolean",
+            "description": "When true, include a `polymorphic_with_typed_alternative` array listing polymorphic edges (e.g. node_owned_by_person, node_constrains_node) that have a more-specific typed alternative for their actual source/target pair. Opt-in only — omitted by default to avoid cluttering routine validation output. Does not affect `valid`; these are advisory suggestions."
+          }
+        }
+      },
+      "throws": [
+        "Returns a textError when `scope` or `severity` is not one of the\nrecognised values."
+      ],
+      "examples": [
+        {
+          "description": "Live call against the Notion example graph.",
+          "input": "{}",
+          "output": "{\n  \"valid\": false,\n  \"summary\": {\n    \"entity_drift\": 0,\n    \"edge_drift\": 0,\n    \"top_level_drift\": 0,\n    \"lifecycle_drift\": 0,\n    \"self_referential\": 0,\n    \"property_drift\": 164,\n    \"total_nodes\": 2054,\n    \"total_edges\": 3120,\n    \"spec_version\": \"0.5.8\",\n    \"scope\": \"all\",\n    \"limit\": 100,\n    \"anti_pattern_violations_high\": 0,\n    \"anti_pattern_violations_medium\": 1,\n    \"anti_pattern_violations_low\": 0,\n    \"edge_type_pair_drift\": 100,\n    \"graph_topology_self_loops\": 0,\n    \"property_type_drift\": 100\n  },\n  \"_hash\": \"592a8d0ae65f17ac\",\n  \"entity_drift\": [],\n  \"edge_drift\": [],\n  \"top_level_drift\": [],\n  \"lifecycle_drift\": [],\n  \"self_referential\": [],\n  \"property_drift\": [\n    {\n      \"id\": \"ec3d5479-4947-4bd9-9e77-b5ee01beb851\",\n      \"type\": \"product\",\n      \"property\": \"stage\",\n      \"via\": \"UPG_PROPERTY_MIGRATIONS['0.2.13']\"\n    },\n    {\n      \"id\": \"3f1c1804-b33b-4b1f-9094-c91cc8957912\",\n      \"type\": \"assumption\",\n      \"property\": \"validation_status\",\n      \"via\": \"UPG_PROPERTY_MIGRATIONS['0.5.0']\"\n    },\n    {\n      \"id\": \"6719fce7-61e7-44df-b6cf-92f7c7312554\",\n      \"type\": \"assumption\",\n      \"property\": \"validation_status\",\n      \"via\": \"UPG_PROPERTY_MIGRATIONS['0.5.0']\"\n    },\n    {\n      \"id\": \"7b22f5f3-b344-4e49-8d5a-35cf9087dc6c\",\n      \"type\": \"assumption\",\n      \"property\": \"validation_status\",\n      \"via\": \"UPG_PROPERTY_MIGRATIONS['0.5.0']\"\n… (truncated)"
+        }
+      ],
+      "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."
+      ],
+      "see": [
+        "migrate_type",
+        "migrate_properties",
+        "rename_edge_type",
+        "get_anti_pattern_violations_for",
+        "list_anti_patterns",
+        "list_type_migrations",
+        "list_edge_migrations",
+        "inspect"
+      ],
+      "source": "src/tools/validation.ts:231",
+      "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}"
+        }
+      ],
+      "warnings": [],
+      "see": [],
+      "source": "src/tools/skills.ts:191",
+      "symbol": "skillAudit",
+      "returns": "`{ skills: SkillAuditRecord[] }`",
+      "atomicity": "atomic (read-only filesystem stat + read)"
+    }
+  ]
+}