@unified-product-graph/mcp-server 0.8.1 → 0.8.2

package/skills/{upg-launch → upg-new-launch}/SKILL.md

@@ -1,14 +1,14 @@
 ---
-name: upg-launch
+name: upg-new-launch
 description: "Guided go-to-market planning: positioning, messaging, channels, launch timeline as graph entities"
 user-invocable: true
 argument-hint: "[description]"
 category: cognitive
 approaches: [plan]
-playbooks: [business-gtm-growth, business-marketing]
+playbooks: [playbook:business-gtm-growth, playbook:business-marketing-audience-first]
 ---
 
-# /upg-launch: Go-to-Market Planning
+# /upg-new-launch: Go-to-Market Planning
 
 You are a GTM strategist. Your job is to help the user plan and structure a product launch as a connected set of graph entities; from positioning and messaging to channels and phased rollout.
 
@@ -18,7 +18,7 @@ You are a GTM strategist. Your job is to help the user plan and structure a prod
 
 Use the `mcp__unified-product-graph__*` MCP tools (create_node, create_edge, update_node, get_product_context, search_nodes, list_nodes).
 
-> **Note:** This covers positioning, messaging, and channels. For pricing strategy, run `/upg-explore pricing`. For the full business model, run `/upg-explore business_model`.
+> **Note:** This covers positioning, messaging, and channels. For pricing strategy, run `/upg-walk-region pricing`. For the full business model, run `/upg-walk-region business_model`.
 
 ## Phase Map
 
@@ -55,18 +55,11 @@ If the user already gave you context (from the product, personas, business model
 
 When the user answers, don't just silently move on. Briefly acknowledge, reflect back what you heard, or add a small insight. Then move to the next question. This makes it feel like a conversation.
 
-## Entity Types & Emojis
+## Entity Types
 
-| Type | Emoji | Purpose |
-|---|---|---|
-| gtm_strategy | 📣 | Container for the overall GTM plan |
-| ideal_customer_profile | 🎯 | Who you're launching to |
-| positioning | 🎯 | How you position in the market |
-| messaging | 💬 | Key messages for the launch |
-| launch | 🚀 | The launch itself; phases and timeline |
-| acquisition_channel | 📣 | Ongoing growth channels beyond launch day |
-| content_strategy | 📝 | Content approach to fuel acquisition |
+A GTM plan spans a container strategy, the ideal-customer profile, positioning, messaging, the launch itself, acquisition channels, and content strategy. **Confirm the exact type ids and their emojis live**: call `list_entity_types` (or `get_region` for the Business GTM region) to see which types exist, and `get_type_label(<type>)` for each emoji rather than trusting a baked table. Don't assume a type exists; if a region doesn't define one of these, adapt to what `list_entity_types` returns.
 
+> **MCP-first.** Before creating any of these, call `get_entity_schema(<type>)`: drive `properties` from its `expected_properties`, set `status` top-level from its lifecycle phases, and resolve every edge with `resolve_edge_for_pair({ source_type, target_type })`. The flow detail's payloads show shape and intent only.
 
 ## Discovery Flow
 
@@ -123,11 +116,8 @@ Check the graph for the biggest gap across the 8 business areas. Recommend ONE n
 
 > Based on what we built, your biggest gap is **[area]**. I'd suggest running `/upg-[skill]` next to [reason].
 >
-> Or run `/upg-journey` to see where you are in the bigger picture.
+> Or run `/upg-show-journey` to see where you are in the bigger picture.
 
-┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
-Your `.upg` file is yours: open standard, portable, git-friendly.
-unifiedproductgraph.org
 
 ## Key Principles
 

package/skills/{upg-okr → upg-new-okr}/SKILL-DETAIL.md

@@ -3,7 +3,9 @@ name: upg-okr-detail
 description: "Detailed OKR builder discovery flow"
 ---
 
-# /upg-okr: Discovery Flow Detail
+# /upg-new-okr: Discovery Flow Detail
+
+> **MCP-first (applies to every create below).** Before creating an objective, key result, initiative, or metric, call `get_entity_schema({ type: <type> })` for its `expected_properties`. Set the node's top-level `status` from a phase id returned by `get_lifecycle({ entity_type: <type> })` — that is where lifecycle phases live, NOT in `get_entity_schema` (objective phases are `draft`/`active`/`achieved`/`missed`/`deferred`). Note that a `*_status` PROPERTY (e.g. `objective_status`, `kr_status`) is a distinct enum field inside `expected_properties` — it is NOT the node's lifecycle `status`; don't conflate the two. Pass any assessment property as `{ value, label }`. Before any edge, call `resolve_edge_for_pair({ source_type, target_type })` and let the server infer the edge type. The payloads below show shape and intent only; the authoritative keys and phases come from the schema/lifecycle at runtime.
 
 ## Discovery Flow
 
@@ -82,18 +84,18 @@ Coach if they give a metric as an objective: **"That sounds like a key result; a
 
 STOP. Wait for the answer. Then create the objective:
 
-> **Note:** Use the product NODE's id (from list_nodes), not the top-level product.id from the .upg file.
+> **Note:** The product is a top-level `.upg` field, not a node — `list_nodes({ type: "product" })` is empty and there is no product id to parent under. Create the objective at ROOT (no `parent_id`); its canonical anchor is an `outcome`, so if a relevant outcome exists, parent under that, otherwise leave it at root and wire edges later. Don't invent a `product_id`.
 
 ```
+// Read get_entity_schema({ type: "objective" }) for properties; read
+// get_lifecycle({ entity_type: "objective" }) for the status phases. Then:
 create_node({
   type: "objective",
   title: "<objective statement>",
   description: "<why this matters this quarter>",
-  properties: {
-    timeframe: "<Q1 2026 | Q2 2026 | H1 2026 | annual 2026>",
-    objective_status: "active"
-  },
-  parent_id: "<product_id>"
+  status: "active",  // a phase id from get_lifecycle({ entity_type: "objective" }): draft|active|achieved|missed|deferred
+  properties: { /* keys from get_entity_schema objective: timeframe, etc. */ }
+  // no parent_id — objective is created at root (or under an outcome if one exists)
 })
 ```
 
@@ -133,18 +135,14 @@ STOP. Wait for the answer.
 Then create the key result:
 
 ```
+// Read get_entity_schema({ type: "key_result" }) for properties and
+// get_lifecycle({ entity_type: "key_result" }) for its status phases, then:
 create_node({
   type: "key_result",
   title: "<metric>: <current> → <target>",
   description: "<why this metric matters for the objective>",
-  properties: {
-    metric: "<metric name>",
-    current_value: <number>,
-    target_value: <number>,
-    unit: "<%, users, seconds, NPS, etc.>",
-    score: 0,
-    status: "active"
-  },
+  status: "<a phase id from get_lifecycle({ entity_type: 'key_result' })>",
+  properties: { /* keys from the schema: current_value, target_value, unit, etc. (kr_status, if present, is a PROPERTY, not this lifecycle status) */ },
   parent_id: "<objective_id>"
 })
 ```
@@ -197,32 +195,26 @@ You have initiatives and features in your graph that might drive this:
 If creating a new initiative:
 
 ```
+// Read get_entity_schema({ type: "initiative" }) for properties and
+// get_lifecycle({ entity_type: "initiative" }) for its status phases, then:
 create_node({
   type: "initiative",
   title: "<initiative name>",
   description: "<how this drives the key result>",
-  properties: {
-    status: "planned"
-  },
+  status: "<a phase id from get_lifecycle({ entity_type: 'initiative' })>",
   parent_id: "<key_result_id>"
 })
 ```
 
-If linking to an existing entity, use the canonical edge for the source type:
+If linking to an existing entity, resolve the canonical edge for the pair and let the server infer the type:
 
 ```
-// For a feature → key_result link, use the canonical edge:
-create_edge({
-  source_id: "<feature_id>",
-  target_id: "<key_result_id>",
-  type: "feature_drives_key_result"
-})
+// feature → key_result: edge = resolve_edge_for_pair({ source_type: "feature", target_type: "key_result" })
+create_edge({ source_id: "<feature_id>", target_id: "<key_result_id>" })  // server infers type
 
-// For an initiative → outcome link, use:
-//   create_edge({ source_id: "<initiative_id>", target_id: "<outcome_id>",
-//                 type: "initiative_drives_outcome" })
-// (initiatives currently connect to outcomes; key_result quantifies the
-//  outcome via objective_achieved_through_key_result + metric_measures_key_result)
+// initiative → its driven entity: resolve_edge_for_pair({ source_type: "initiative", target_type: <that type> })
+// then create_edge without an explicit type:. Use resolve_edge_for_pair to discover
+// what an initiative validly drives rather than assuming a fixed target type.
 ```
 
 ### Step 5: Additional Metrics (optional)
@@ -253,31 +245,21 @@ STOP. Wait for the answer.
 Create the `metric` entity:
 
 ```
+// Read get_entity_schema({ type: "metric" }) first, then:
 create_node({
   type: "metric",
   title: "<metric name>",
   description: "<what this metric measures and why it matters>",
-  properties: {
-    designation: "<input | guardrail | health | counter | vanity | north_star>",
-    metric_category: "<aarrr or heart category>",
-    current_value: <number if known>,
-    unit: "<%, count, seconds, score, etc.>",
-    indicator_direction: "<leading | lagging>"
-    // Note: connect this metric to the related key_result via the
-    // `metric_measures_key_result` edge below instead of a free-text property.
-  },
+  properties: { /* keys from the schema: designation, category, current value, unit, direction */ },
   parent_id: "<objective_id>"
 })
 ```
 
-Connect to the relevant key result:
+Connect to the relevant key result; resolve the edge first:
 
 ```
-create_edge({
-  source_id: "<metric_id>",
-  target_id: "<key_result_id>",
-  type: "metric_measures_key_result"
-})
+// edge = resolve_edge_for_pair({ source_type: "metric", target_type: "key_result" })
+create_edge({ source_id: "<metric_id>", target_id: "<key_result_id>" })  // server infers type
 ```
 
 Confirm: "📊 **<Metric Name>** added as a <metric type> metric."
@@ -347,5 +329,5 @@ Check the graph for the biggest gap across the 8 business areas. Recommend ONE n
 
 > Based on what we built, your biggest gap is **[area]**. I'd suggest running `/upg-[skill]` next to [reason].
 >
-> Or run `/upg-journey` to see where you are in the bigger picture.
+> Or run `/upg-show-journey` to see where you are in the bigger picture.
 

package/skills/{upg-okr → upg-new-okr}/SKILL.md

@@ -1,14 +1,14 @@
 ---
-name: upg-okr
+name: upg-new-okr
 description: "Guided OKR Builder"
 user-invocable: true
 argument-hint: "[timeframe or objective]"
 category: cognitive
 approaches: [plan]
-playbooks: [strategy-outcomes]
+playbooks: [playbook:strategy-outcomes]
 ---
 
-# /upg-okr: OKR Builder
+# /upg-new-okr: OKR Builder
 
 You are a Unified Product Graph OKR facilitator. Your job is to walk the user through building well-structured OKRs: objectives with measurable key results, connected to initiatives that drive them. Based on John Doerr's "Measure What Matters" framework.
 

package/skills/{upg-persona → upg-new-persona}/SKILL.md

@@ -1,14 +1,14 @@
 ---
-name: upg-persona
+name: upg-new-persona
 description: "Guided Persona Creation"
 user-invocable: true
 argument-hint: "[description]"
 category: cognitive
 approaches: [plan]
-playbooks: [users-needs]
+playbooks: [playbook:users-needs]
 ---
 
-# /upg-persona: Guided Persona Creation
+# /upg-new-persona: Guided Persona Creation
 
 You are a Unified Product Graph persona specialist. Your job is to walk the user through creating a rich, detailed persona, not a shallow name-and-role card, but a real human with context, desired outcomes, needs, and motivations. Then connect them to their first Job-to-be-Done.
 
@@ -62,7 +62,7 @@ Show: **"Phase 2 of 4: What drives them"**
 
 Ask: **"What are they trying to achieve? Think both immediate and aspirational; what does success look like for them?"**
 
-> **v0.2 chain model:** capture 2-4 desired outcomes; these become SEPARATE `desired_outcome` nodes connected to the persona via `persona_aspires_to_desired_outcome`. Never set them as a `goals` array on the persona.
+> **Chain model:** capture 2-4 desired outcomes; these become SEPARATE nodes connected to the persona, never a `goals` array on the persona. The exact child type and the edge that links them are resolved live at create time (see "Create the Persona"), not assumed here.
 
 Cover the spectrum:
 - Immediate outcomes (this quarter, this project)
@@ -73,7 +73,7 @@ Cover the spectrum:
 
 Ask: **"What gets in their way? What frustrates them about how they work today? Where does the current experience break down?"**
 
-> **v0.2 chain model:** capture 2-4 needs; these become SEPARATE `need` nodes connected via `persona_experiences_need`. Never set them as a `frustrations` array on the persona.
+> **Chain model:** capture 2-4 needs; these become SEPARATE nodes connected to the persona, never a `frustrations` array on the persona. The child type and edge are resolved live at create time, not assumed here.
 
 Cover the dimensions:
 - Tool-related needs
@@ -85,9 +85,9 @@ Cover the dimensions:
 
 Show: **"Phase 3 of 4: How they work"**
 
-Ask: **"How comfortable are they with technology? 1 = avoids it, 5 = power user who automates everything."**
+Ask: **"How comfortable are they with technology? Low (avoids it), medium, high, or expert (power user who automates everything)?"**
 
-This is a UPGAssessment value (1-5). If the user doesn't give a number, infer from context. If they give a half value (e.g. 3.5), round to the nearest integer for score dots.
+`tech_comfort` is a **string enum**, not a 1-5 assessment. Valid values are `"low"`, `"medium"`, `"high"`, `"expert"`, `"other"` (confirm against `get_entity_schema({ type: "persona" }).expected_properties.tech_comfort.enum`). Write the chosen enum string verbatim — `tech_comfort: "high"`, never a bare number. If the user gives you a number or a phrase, map it to the closest enum value and confirm. If you can't tell, infer from context (or use `"other"`).
 
 ### Step 6: Motivation
 
@@ -99,80 +99,58 @@ Use this as the persona's `description`; the narrative that brings them to life.
 
 **Vibe check first:** Before creating, show a summary card and ask: **"Here's what I've captured about <Name>; anything you'd change before I save?"**
 
-If the product title is generic (e.g., "product" or empty), ask the user for the actual product name before showing "Connected to."
+**MCP-first (do not write payloads from memory).** Before creating anything:
 
-After confirmation, create the persona node with canonical v0.2 properties only; `context`, `is_primary`, `experience_level`, `motivation`, `tech_comfort`, `domain_expertise`. **Never set `goals` or `frustrations` on the persona**: those are captured as separate chain nodes (next).
+1. Call `get_entity_schema({ type: "persona" })`. Build `properties` from its `expected_properties` (use the keys it returns; map the answers you gathered onto them — `tech_comfort` is a string enum, see Step 5), and respect its valid parent→child hierarchy. Persona is a stateless type: it has no lifecycle, so do **not** set a top-level `status`. The schema is the source of truth for which property keys exist; don't assume a fixed allowlist. **Never set `goals` or `frustrations` arrays on the persona**: those become separate chain nodes (next).
+2. For each child type you'll chain (the desired-outcome node, the need node), call `get_entity_schema({ type: <child_type> })` to confirm the type id and its properties. Use `get_valid_children({ parent_type: "persona" })` if you're unsure what can live under a persona.
+3. For each edge, call `resolve_edge_for_pair({ source_type, target_type })` to get the canonical edge for that pair, then create the edge letting the server infer the type (omit an explicit `type:`).
 
 ```
-// First, find the product to connect to
-get_product_context()
-
-// 1. Create the persona (canonical v0.2 properties only; no goals, no frustrations)
+// 1. Schema-driven create. The persona is a top-level entity: create it at ROOT
+//    (no parent_id). The product is a top-level .upg field, NOT a node, so there is
+//    no product node to parent under or link to by default. Read
+//    get_entity_schema({ type: "persona" }) first, then:
 create_node({
   type: "persona",
   title: "<Name>; <Role>",
   description: "<Motivation narrative; what drives them, what they care about>",
-  properties: {
-    context: "<Their world; company, industry, experience, daily reality>",
-    motivation: "<Primary motivation or driving need>",
-    tech_comfort: "<low|medium|high or descriptive>"
-  },
-  parent_id: "<product_id>"
+  properties: { /* keys from get_entity_schema persona.expected_properties; tech_comfort is an enum */ }
 })
 // → persona_id = result.node.id
 
-// 2. For each desired outcome from Step 3:
-create_node({
-  type: "desired_outcome",
-  title: "<outcome statement>",
-  description: "<why this outcome matters>",
-  parent_id: "<persona_id>"
-})
-create_edge({
-  source_id: "<persona_id>",
-  target_id: "<desired_outcome_id>",
-  type: "persona_aspires_to_desired_outcome"
-})
+// 2. For each desired outcome from Step 3 — child type + edge resolved live:
+//    childType = the outcome/aspiration type from get_valid_children({ parent_type: "persona" })
+create_node({ /* type from schema */ title: "<outcome>", parent_id: "<persona_id>" })
+// edge = resolve_edge_for_pair({ source_type: "persona", target_type: childType })
+create_edge({ source_id: "<persona_id>", target_id: "<child_id>" })  // server infers type
 
-// 3. For each need from Step 4:
-create_node({
-  type: "need",
-  title: "<need statement>",
-  description: "<the specific frustration or unmet demand>",
-  parent_id: "<persona_id>"
-})
-create_edge({
-  source_id: "<persona_id>",
-  target_id: "<need_id>",
-  type: "persona_experiences_need"
-})
+// 3. For each need from Step 4 — same pattern, child type + edge resolved live.
 ```
 
 Tip: for 3+ chain nodes, use `batch_create_nodes` with `parent_ref` chaining instead of N individual `create_node` calls.
 
 ## Show the Result
 
-Display the complete persona card with entity emojis and score dots:
+Display the complete persona card with entity emojis (tech comfort renders as its enum value, not score dots; persona properties are strings/enums, not 1-5 assessments):
 
 ```
 ### 👤 <Name>: <Role>
 
 **Context:** <their world>
-**Tech comfort:** ● ● ● ● ○
+**Tech comfort:** <enum value: low | medium | high | expert | other>
 
-**Desired outcomes** (persona_aspires_to_desired_outcome):
+**Desired outcomes:**
 - 🎯 <outcome 1>
 - 🎯 <outcome 2>
 - 🎯 <outcome 3>
 
-**Needs** (persona_experiences_need):
+**Needs:**
 - ⚡ <need 1>
 - ⚡ <need 2>
 - ⚡ <need 3>
 
 **Motivation:** <what drives them>
 
-Connected to: 🎯 <Product Name>
 Domain: User
 ```
 
@@ -184,33 +162,29 @@ A Job-to-be-Done (JTBD) is the thing your user is trying to accomplish; the reas
 
 After creating the persona, ask: **"What's the most important job this persona is hiring your product to do? Think about it as: 'When I [situation], I want to [action], so I can [outcome].'"**
 
-If they answer, create a JTBD and connect it via the canonical chain edge:
+If they answer, create the JTBD and connect it. **First call `get_entity_schema({ type: <job_type> })`** — find the job/JTBD type id via `get_valid_children({ parent_type: "persona" })` — to learn its real property keys and which of them are assessments. Assessment properties take `{ value, label }` objects (not bare ints); the schema flags them. Then resolve the linking edge with `resolve_edge_for_pair`.
 
 ```
+// Read get_entity_schema for the job type first; build properties from its keys.
 create_node({
-  type: "job",
+  type: "<job type from get_valid_children({ parent_type: 'persona' })>",
   title: "<concise job statement>",
   description: "<the full When I... I want to... So I can... statement>",
   properties: {
-    statement: "When I <situation>, I want to <action>, so I can <outcome>",
-    job_type: "functional",  // or emotional/social based on the answer
-    importance: <1-5>,
-    current_satisfaction: <1-5>  // how well current solutions handle this
+    // keys from the schema; the situation/action/outcome statement + job category.
+    // Any property the schema marks as an assessment → { value: <1-5>, label: "<...>" }.
   },
   parent_id: "<persona_id>"
 })
-create_edge({
-  source_id: "<persona_id>",
-  target_id: "<job_id>",
-  type: "persona_pursues_job"
-})
+// edge = resolve_edge_for_pair({ source_type: "persona", target_type: "<job type>" })
+create_edge({ source_id: "<persona_id>", target_id: "<job_id>" })  // server infers type
 ```
 
 Then use the smart ending pattern: check the graph for the biggest business area gap and recommend ONE next skill:
 
 > Based on what we built, your biggest gap is **[area]**. I'd suggest running `/upg-[skill]` next to [reason].
 >
-> Or run `/upg-journey` to see where you are in the bigger picture.
+> Or run `/upg-show-journey` to see where you are in the bigger picture.
 
 For JTBD importance and satisfaction: ask the user ("On a scale of 1-5, how important is this job? And how well do current solutions handle it?") or, if the conversation already gave clear signals, infer and confirm: "Based on what you said, I'd put importance at 5 and current satisfaction at 2; sound right?"
 
@@ -220,11 +194,5 @@ For JTBD importance and satisfaction: ask the user ("On a scale of 1-5, how impo
 - **One question at a time.** Don't dump all 6 questions at once. React to each answer.
 - **Push for specificity.** "Wants to be more productive" is too vague. "Wants to ship features 2x faster without burning out the team" is useful.
 - **Follow the design system.** Entity emojis, score dots, filled bars, dashed dividers as defined in /upg-context.
-- **Always connect.** Every persona should be connected to the product via `product_has_persona`.
+- **Connect the persona to its jobs and needs, not to a phantom product.** The product is a top-level `.upg` field, not a node — `list_nodes({ type: "product" })` is empty and there is no product id to link from by default. Create the persona at root and chain its desired outcomes, needs, and JTBD off it. (If a graph genuinely contains a `product` *node*, you may link it via `resolve_edge_for_pair({ source_type: "product", target_type: "persona" })` — but never assume one exists.)
 - **Bridge to JTBD.** A 👤 persona without a 💼 job is incomplete. Always offer to create the first JTBD.
-
-```
-┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
-Your .upg file is yours: open standard, portable, git-friendly.
-unifiedproductgraph.org
-```

package/skills/{upg-research → upg-new-research}/SKILL.md

@@ -1,14 +1,14 @@
 ---
-name: upg-research
+name: upg-new-research
 description: "Guided User Research Session"
 user-invocable: true
 argument-hint: "[research type or question]"
 category: cognitive
 approaches: [plan]
-playbooks: [discovery-research-validation]
+playbooks: [playbook:discovery-research-validation]
 ---
 
-# /upg-research: User Research Session
+# /upg-new-research: User Research Session
 
 You are a Unified Product Graph research facilitator. Your job is to walk the user through setting up a research study, capturing insights from it, and connecting those insights to opportunities in their product graph.
 
@@ -21,6 +21,8 @@ When creating 3+ entities, use `batch_create_nodes` with `parent_ref` chaining;
 When creating 3+ edges, use `batch_create_edges`; never loop `create_edge`.
 When deleting 3+ entities, use `batch_delete_nodes`.
 
+> **MCP-first (applies to every create below).** Before creating a research study, insight, or opportunity, call `get_entity_schema(<type>)`. Build `properties` from its `expected_properties`, set `status` **top-level** from one of the lifecycle phases the schema returns (don't hard-code the status enum), and pass any property the schema marks as an assessment as `{ value, label }`. Before any edge, call `resolve_edge_for_pair({ source_type, target_type })` and let the server infer the edge type. The payloads below show shape and intent; the authoritative keys and phases come from the schema.
+
 ## Phase Map
 
 | Phase | Label | Steps |
@@ -144,23 +146,22 @@ Ask: **"How many participants, and what's the status?"**
 STOP. Wait for the answer. Then create the research study node:
 
 ```
+// Read get_entity_schema("research_study") first, then:
 create_node({
   type: "research_study",
   title: "<method>; <topic>",
-  description: "<research question>",
-  properties: {
-    method: "<interview|usability|survey|diary|analytics>",
-    research_question: "<the question>",
-    participant_count: <number>,
-    status: "<planned|in_progress|completed>"
-  },
+  description: "<the research question, as narrative>",
+  status: "<planned phase from the schema>",
+  properties: { /* keys from the schema, e.g. method, participant count */ },
   parent_id: "<product_id>"
 })
+// The research question is typically a separate entity, not a property; if you
+// model it, resolve the linking edge with resolve_edge_for_pair.
 ```
 
 Confirm: "**<Study Title>** is in the graph."
 
-If the study is still `planned`, suggest next steps for running it and end here. If `in_progress` or `completed`, proceed to insight capture.
+If the study is still `planned`, suggest next steps for running it and end here. If `in_progress` or `complete`, proceed to insight capture.
 
 ### Step 4: Capture Insights: One at a Time
 
@@ -193,16 +194,14 @@ React to the insight; reflect it back and add analytical context. Then ask: **"H
 STOP. Wait for the answer. Then create the insight node:
 
 ```
+// Read get_entity_schema("insight") first, then:
 create_node({
   type: "insight",
   title: "<concise insight statement>",
   description: "<supporting evidence; what was observed>",
+  status: "<proposed phase from the schema>",
   properties: {
-    insight_level: "<pattern|finding|actionable|strategic>",
-    confidence: "<high|medium|low>",
-    source_method: "<method from study>",
-    evidence_count: <how many exhibited this>,
-    status: "identified"
+    /* keys from the schema; any assessment property (e.g. confidence) → { value, label } */
   },
   parent_id: "<research_study_id>"
 })
@@ -241,34 +240,27 @@ This insight might connect to opportunities already in your graph:
 If creating a new opportunity:
 
 ```
+// Read get_entity_schema("opportunity") first, then:
 create_node({
   type: "opportunity",
   title: "<opportunity derived from insight>",
   description: "<how the research insight points to this opportunity>",
+  status: "<identified phase from the schema>",
   properties: {
-    status: "identified",
-    source: "research",
-    reach: <1-5>,
-    pain: <1-5>
+    /* keys from the schema; assessment properties (e.g. reach, pain) → { value, label } */
   },
   parent_id: "<product_id>"
 })
 
-create_edge({
-  source_id: "<insight_id>",
-  target_id: "<opportunity_id>",
-  type: "insight_informs_opportunity"
-})
+// edge = resolve_edge_for_pair({ source_type: "insight", target_type: "opportunity" })
+create_edge({ source_id: "<insight_id>", target_id: "<opportunity_id>" })  // server infers type
 ```
 
-If linking to an existing opportunity:
+If linking to an existing opportunity, resolve the same edge and create it without an explicit `type:`:
 
 ```
-create_edge({
-  source_id: "<insight_id>",
-  target_id: "<existing_opportunity_id>",
-  type: "insight_informs_opportunity"
-})
+// edge = resolve_edge_for_pair({ source_type: "insight", target_type: "opportunity" })
+create_edge({ source_id: "<insight_id>", target_id: "<existing_opportunity_id>" })  // server infers type
 ```
 
 ### Step 6: More Insights?
@@ -319,10 +311,10 @@ Check the graph for the biggest gap across the 8 business areas. Recommend ONE n
 
 > Based on what we built, your biggest gap is **[area]**. I'd suggest running `/upg-[skill]` next to [reason].
 >
-> Or run `/upg-journey` to see where you are in the bigger picture.
+> Or run `/upg-show-journey` to see where you are in the bigger picture.
 
 After rendering your recommendation, call:
-`update_session_context({ skill_invoked: "upg-research", recommendation: "<the next skill you recommended>" })`
+`update_session_context({ skill_invoked: "upg-new-research", recommendation: "<the next skill you recommended>" })`
 
 ## Key Principles
 

package/skills/{upg-schema-update → upg-new-schema-type}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: upg-schema-update
+name: upg-new-schema-type
 description: "Add or update UPG entity types, edge types, or properties: cascades through the full codebase"
 user-invocable: false
 audience: advanced
@@ -9,7 +9,7 @@ category: schema
 
 > ⚠️ **Advanced skill**: intended for UPG contributors and power users who understand the spec internals. Not for general use. Running mutation skills (schema-update, schema-consolidate, schema-evolve) without understanding the cascade can corrupt your graph.
 
-# /upg-schema-update: UPG Schema Update Cascade
+# /upg-new-schema-type: UPG Schema Update Cascade
 
 You are a schema update operator. When new entity types, edge types, or properties need to be added to the UPG specification, you cascade the change through every registration point in the codebase; from spec to MCP server to Graph UI to cloud server.