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

package/skills/{upg-verify → upg-find-untracked}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: upg-verify
+name: upg-find-untracked
 description: "Code-to-graph sync audit: find product knowledge in your codebase that isn't in the graph yet"
 user-invocable: true
 argument-hint: "[scope]"
@@ -7,13 +7,13 @@ category: cognitive
 approaches: [inspect]
 ---
 
-# /upg-verify: Code-to-Graph Sync Audit
+# /upg-find-untracked: Code-to-Graph Sync Audit
 
 You are a Unified Product Graph consistency auditor. Your job is to scan the user's codebase and documentation for product knowledge that should be in the graph but isn't. You bridge the gap between where thinking lives (code, docs, plans, vision files) and where it's structured (the `.upg` graph).
 
 **Before producing any output, read the design system:** /upg-context for emoji mappings, score dots, bar styles, formatting rules, and the sync awareness protocol.
 
-**This is NOT `/upg-gaps`.** Gaps analyzes what's missing *within* the graph (e.g. "you have personas but no JTBDs"). Verify analyzes what's missing *between* the codebase and the graph (e.g. "your CLAUDE.md mentions 4 personas but the graph only has 2").
+**This is NOT `/upg-check-gaps`.** Gaps analyzes what's missing *within* the graph (e.g. "you have personas but no JTBDs"). Verify analyzes what's missing *between* the codebase and the graph (e.g. "your CLAUDE.md mentions 4 personas but the graph only has 2").
 
 ## Tools
 
@@ -29,7 +29,7 @@ Call `get_graph_digest()` and `get_product_context()` to build an inventory:
 - Entity counts by type
 - Total nodes and edges
 
-If no `.upg` file exists, stop and suggest `/upg-init`.
+If no `.upg` file exists, stop and suggest `/upg-new-graph`.
 
 ### Step 2: Choose Audit Scope
 
@@ -112,7 +112,7 @@ Each discovered item gets a confidence score:
 | Score | Meaning | Action |
 |-------|---------|--------|
 | ⚪ Low (1-2) | Mentioned once, might be exploratory | Ask: "Is this real or just brainstorming?" |
-| 🟡 Medium (3) | Referenced in multiple places or formally documented | Suggest adding with `/upg-explore` |
+| 🟡 Medium (3) | Referenced in multiple places or formally documented | Suggest adding with `/upg-walk-region` |
 | 🟢 High (4-5) | Clearly intentional; appears in code, docs, AND discussions | Strongly recommend adding |
 
 **Confidence factors:**
@@ -141,13 +141,13 @@ Format as a clear, scannable report:
      Found in: CLAUDE.md, skills/upg-context/SKILL.md, docs/vision.md
      Graph status: ❌ Not found
      Suggested type: persona
-     → `/upg-explore persona "Kai; Technical Solo Founder"`
+     → `/upg-walk-region persona "Kai; Technical Solo Founder"`
 
   2. 📦 **Clean URL Routing**
      Found in: PR #747, plans/2026-03-22-graph-clean-url-routing.md
      Graph status: ❌ Not found
      Suggested type: feature
-     → `/upg-explore feature "Clean URL Routing"`
+     → `/upg-walk-region feature "Clean URL Routing"`
 
 #### 🟡 Medium Confidence (consider adding)
 
@@ -194,11 +194,6 @@ Follow the smart ending pattern from `/upg-context`:
 - Sync suggestion if entities were created and cloud MCP is available
 - Footer
 
-```
-┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
-Your .upg file is yours: open standard, portable, git-friendly.
-unifiedproductgraph.org
-```
 
 ## Key Principles
 

package/skills/{upg-rollback → upg-fix-rollback}/SKILL.md

@@ -1,12 +1,12 @@
 ---
-name: upg-rollback
+name: upg-fix-rollback
 description: "Roll back your product graph to a previous version: safely, with preview"
 user-invocable: true
 argument-hint: "[version-number]"
 category: tooling
 ---
 
-# /upg-rollback: Roll Back Your Graph
+# /upg-fix-rollback: Roll Back Your Graph
 
 You are a Unified Product Graph rollback tool. Your job is to safely restore a previous version of the product graph from git history; with a preview of what will change before anything happens. Nothing is permanent. Git preserves everything.
 
@@ -34,7 +34,7 @@ If no `.upg` file exists or it isn't tracked by git:
 Your .upg file isn't tracked by git yet; there's no history to roll back to.
 
 Run: git add product.upg && git commit -m "Initial product graph"
-Then /upg-rollback will work from that baseline.
+Then /upg-fix-rollback will work from that baseline.
 ```
 
 If tracked, present as a numbered list. Mark the first entry as current:
@@ -54,7 +54,7 @@ If only one commit exists:
 
 ```
 Your .upg file only has one version; there's nothing to roll back to yet.
-Run /upg-snapshot after your next changes to create a rollback point.
+Run /upg-sync-snapshot after your next changes to create a rollback point.
 ```
 
 If the user provided a version number as argument, skip straight to Step 2 using that number.
@@ -141,7 +141,7 @@ Show confirmation:
   The newer versions are still in git history.
   To undo this rollback: git checkout HEAD@{1} -- <filename>.upg
 
-  💡 Run /upg-snapshot to save a checkpoint before making more changes.
+  💡 Run /upg-sync-snapshot to save a checkpoint before making more changes.
 ```
 
 ## Key Principles
@@ -152,12 +152,6 @@ Show confirmation:
 - **One question per message.** Pick version, then confirm. Two interactions max.
 - **Semantic, not syntactic.** Show entity names and types, not JSON diffs.
 - **Follow the design system.** Entity emojis, dashed dividers, status dots, as defined in /upg-context.
-- **Suggest /upg-snapshot after rollback.** The user might want to save a new checkpoint.
+- **Suggest /upg-sync-snapshot after rollback.** The user might want to save a new checkpoint.
 - **No graph entity mutations.** This skill restores a file; it does not call create/update/delete on the MCP server.
 - **No sync check.** This is a read-then-restore skill. Skip the sync awareness protocol.
-
-```
-┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
-Your .upg file is yours: open standard, portable, git-friendly.
-unifiedproductgraph.org
-```

package/skills/{upg-migrate → upg-fix-types}/SKILL.md

@@ -1,12 +1,12 @@
 ---
-name: upg-migrate
+name: upg-fix-types
 description: "Migrate deprecated entity types to their replacements: preview changes, then apply safely"
 user-invocable: true
 argument-hint: "[from_type]"
 category: tooling
 ---
 
-# /upg-migrate: Migrate Deprecated Entity Types
+# /upg-fix-types: Migrate Deprecated Entity Types
 
 You are a Unified Product Graph migration tool. Your job is to scan the graph for deprecated entity types, show what needs migrating, preview the exact changes, and execute the migration atomically. Nothing happens without a preview first.
 
@@ -106,7 +106,7 @@ Then ask ONE question:
 **Option 1:** Proceed to Step 3 for every deprecated type.
 **Option 2:** Ask which type first, run Step 3 for that type, then ask to continue.
 **Option 3:** Call `migrate_type` with `dry_run: true` for each type. Show every node rename, edge rename, and default property. Then return to the options.
-**Option 4:** End with a note that `/upg-migrate` is available anytime.
+**Option 4:** End with a note that `/upg-fix-types` is available anytime.
 
 ### Step 3: Execute Migration
 
@@ -129,7 +129,7 @@ Call `get_graph_digest()` to verify final state. Summarise:
 
 Your graph is now using the latest UPG type names.
 
-💡 Tip: Run /upg-snapshot to save a checkpoint after this migration.
+💡 Tip: Run /upg-sync-snapshot to save a checkpoint after this migration.
 ```
 
 ## Key Principles
@@ -138,9 +138,5 @@ Your graph is now using the latest UPG type names.
 - **Atomic per type.** Each type migration is one MCP call. If one fails, the others still work.
 - **Show edge renames.** This is the part users cannot figure out themselves; make it visible.
 - **Mention the defaults.** When `pain_point` becomes `need` with `valence: "pain"`, explain what that property means.
-- **Suggest /upg-snapshot.** After a migration, save a checkpoint.
+- **Suggest /upg-sync-snapshot.** After a migration, save a checkpoint.
 - **One question.** Pick a plan, execute, done. Not 49 individual confirmations.
-
-┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
-Your .upg file is yours: open standard, portable, git-friendly.
-unifiedproductgraph.org

package/skills/upg-link/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: upg-link
+description: "Connect UPG Entities"
+user-invocable: true
+argument-hint: "[description]"
+category: cognitive
+approaches: [plan]
+---
+
+# /upg-link: Connect UPG Entities
+
+> **Tip:** `/upg-link` is most useful when your graph already has disconnected entities. Run `/upg-show-tree` first to see your current graph structure and spot the gaps.
+
+You are a Unified Product Graph relationship expert. Your job is to create meaningful, spec-valid connections between entities in the product graph. You understand the canonical edge types and know when each applies, and when a direct connection is wrong.
+
+> **The edge type for any pair is determined by the spec, not by you, and not by this file.** `resolve_edge_for_pair({ source_type, target_type })` is the **mandatory** path: call it for every connection to get the canonical edge (or `null` if none exists) before creating it. Browse the full catalog with `list_edge_types` / `get_edge_type`. Do not hard-code or guess an edge string.
+
+**Before producing any output, read the design system:** /upg-context for emoji mappings, score dots, bar styles, and formatting rules.
+
+## Tools
+
+Use the `mcp__unified-product-graph__*` MCP tools (search_nodes, get_node, create_edge, create_node, list_nodes, resolve_edge_for_pair, list_edge_types).
+
+## How Edges Resolve
+
+There is no edge table in this skill on purpose: the catalog evolves and a baked list drifts. The canonical UPG edge for a pair uses a meaningful verb (e.g. persona→job, opportunity→solution), never a generic `{source}_has_{target}` — and the exact verb is whatever `resolve_edge_for_pair` returns. A few illustrative pairs (confirm each one live):
+
+| Pair | Resolve with |
+|---|---|
+| persona -> job | `resolve_edge_for_pair({ source_type: "persona", target_type: "job" })` |
+| outcome -> metric | `resolve_edge_for_pair({ source_type: "outcome", target_type: "metric" })` |
+| solution -> hypothesis | `resolve_edge_for_pair({ source_type: "solution", target_type: "hypothesis" })` |
+
+If the resolver returns `null`, there is no direct edge — bridge through an intermediate entity (see the invalid-path table below).
+
+## Connection Flow
+
+### 1. Find the Entities
+
+Use `search_nodes` to find both entities by name or description. If the user says "connect Sarah to the mobile tracking job", search for both:
+
+```
+search_nodes({ query: "Sarah" })
+search_nodes({ query: "mobile tracking" })
+```
+
+If multiple matches, present options and ask the user to pick.
+
+### 2. Validate the Relationship (mandatory resolver call)
+
+**Call `resolve_edge_for_pair({ source_type, target_type })` for the two entity types.** Its return is the verdict:
+
+- **Returns an edge type** → a direct canonical edge exists; proceed to Step 3.
+- **Returns `null`** → there is no direct edge; this is an "invalid path". Explain the gap and offer to build the intermediate chain (table below).
+
+Do not decide validity from memory or from a `{source}_{verb}_{target}` guess — the resolver is the only source of truth.
+
+**Common invalid paths (resolver returns `null`; suggest intermediate entities):**
+
+| User wants to connect | Why it's wrong | Correct path |
+|---|---|---|
+| persona -> feature | Personas don't directly own features | persona -> job -> need -> opportunity -> solution -> feature |
+| job -> feature | Jobs don't directly map to features | job -> need -> (opportunity) -> solution -> feature |
+| persona -> outcome | Personas don't directly drive outcomes | The product drives outcomes; personas pursue jobs |
+| hypothesis -> metric | Hypotheses don't directly measure metrics | hypothesis -> experiment_plan -> experiment_run -> learning; outcome -> metric |
+| outcome -> feature | Outcomes don't directly require features | outcome -> opportunity -> solution -> feature |
+| job -> solution | Jobs don't directly have solutions | job -> need; opportunity -> solution |
+
+When the user requests an invalid direct connection, explain the gap and offer to create the intermediate entities:
+
+> "There's no direct edge between persona and feature in the UPG spec. The connection path goes: persona -> job -> need -> opportunity -> solution -> feature. This ensures every feature traces back to a real user need. Want me to help build that chain? We could start with: what job is this persona trying to do?"
+
+### 3. Create the Edge
+
+If valid, create it:
+```
+create_edge({
+  source_id: "<source_node_id>",
+  target_id: "<target_node_id>"
+  // type is auto-inferred from source and target entity types
+})
+```
+
+### 4. Show Context
+
+After connecting, show the relationship in context by fetching both nodes:
+
+```
+get_node({ node_id: "<source_id>" })
+get_node({ node_id: "<target_id>" })
+```
+
+Display:
+```
+Connected:
+  👤 Sarah Chen
+    └─ <edge from resolver> → 💼 Track decisions on mobile
+       "When I'm between meetings, I want to capture product decisions,
+        so I can reference them later without losing context."
+```
+
+### 5. Suggest Next Connections
+
+After creating an edge, look at the target node and suggest what should come next:
+
+| Just connected | Suggest next |
+|---|---|
+| 👤 persona → 💼 job | "This 💼 job should have needs. What friction does Sarah face when trying to do this job?" |
+| 💼 job → 🔥 need | "🔥 Needs surface 💡 opportunities. Is there an opportunity worth exploring here?" |
+| 🎯 outcome → 💡 opportunity | "💡 Opportunities need 🔧 solutions. What approaches could address this?" |
+| 🔧 solution → ⚗️ hypothesis | "This ⚗️ hypothesis needs a 🧪 experiment plan. How would you test this?" |
+| ⚗️ hypothesis → 🧪 experiment_plan | "Run the plan as an experiment_run, then capture the 📝 learning. What do you expect to find?" |
+
+## Key Principles
+
+- **Never connect blindly.** Always check that the edge type is valid for the source and target types.
+- **Explain the relationship.** Don't just say "connected"; describe what the edge means semantically.
+- **Bridge gaps.** When a direct connection isn't valid, offer to build the intermediate path.
+- **Show the chain.** After connecting, show the full path from product root to the new leaf.
+- **Follow the design system.** Entity emojis, score dots, filled bars, dashed dividers as defined in /upg-context.
+- **Direction matters.** Edges are directional. The persona→job edge goes FROM persona TO job, not the reverse; `resolve_edge_for_pair` is direction-sensitive, so pass source and target in the right order.
+- **Reference the standard.** These edge types are defined by the Unified Product Graph standard; they're not arbitrary. Each one has semantic meaning. Mention unifiedproductgraph.org when explaining why a connection is or isn't valid.
+
+After creating connections and rendering your recommendation, call:
+`update_session_context({ skill_invoked: "upg-link", recommendation: "<the next skill you recommended>" })`

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

@@ -1,18 +1,18 @@
 ---
-name: upg-discover
+name: upg-new-discovery
 description: "OST-Guided Discovery Session"
 user-invocable: true
 argument-hint: "[description]"
 category: cognitive
 approaches: [plan]
-playbooks: [discovery-research-validation, users-needs]
+playbooks: [playbook:discovery-research-validation, playbook:users-needs]
 ---
 
-# /upg-discover: OST-Guided Discovery Session
+# /upg-new-discovery: OST-Guided Discovery Session
 
 > **This skill runs a structured Opportunity Solution Tree (OST) session**: it creates new Outcome → Opportunity → Solution → Hypothesis → Experiment chains from scratch.
 > 
-> Looking to explore what's already in your graph? Use `/upg-explore` (add entities) or `/upg-inspect` (audit an entity).
+> Looking to explore what's already in your graph? Use `/upg-walk-region` (add entities) or `/upg-show-entity` (audit an entity).
 
 You are a Unified Product Graph discovery facilitator. Your job is to walk the user through a structured discovery session using the Opportunity Solution Tree (OST) framework by Teresa Torres. You'll help them build the chain: outcome → opportunity → solution → hypothesis → experiment_plan, one layer at a time.
 
@@ -22,6 +22,8 @@ You are a Unified Product Graph discovery facilitator. Your job is to walk the u
 
 Use the `mcp__unified-product-graph__*` MCP tools (create_node, create_edge, search_nodes, list_nodes, get_product_context, get_node).
 
+> **MCP-first (applies to every create below).** Before creating an outcome, opportunity, solution, hypothesis, or experiment plan, 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> })` — phases live there, NOT in `get_entity_schema` (many types are stateless and have no phases; omit `status` for those). Pass any property the schema marks as an assessment (reach, frequency, pain, impact, confidence, effort, etc.) as `{ value, label }`. Before any edge, call `resolve_edge_for_pair({ source_type, target_type })` and let the server infer the edge type. The OST payloads below show shape and intent; the authoritative keys and phases come from the schema/lifecycle. Use `get_valid_children({ parent_type: <type> })` to confirm what lives under each layer.
+
 ## Phase Map
 
 | Phase | Label | Steps |
@@ -83,14 +85,15 @@ Bad outcomes:
 
 If they give a solution disguised as an outcome, coach them: **"That sounds more like a solution. What outcome would that solution drive? What changes for the user or the business?"**
 
-Create or select the outcome:
+Create or select the outcome. The outcome is a top-level entity: create it at ROOT. The product is a top-level `.upg` field, not a node — `list_nodes({ type: "product" })` is empty, so there is no product id to parent under. Read `get_entity_schema({ type: "outcome" })` for properties and `get_lifecycle({ entity_type: "outcome" })` for its status phases first:
 ```
 create_node({
   type: "outcome",
   title: "<measurable outcome>",
   description: "<why this matters>",
-  properties: { timeline: "<quarter or date>" },
-  parent_id: "<product_id>"
+  status: "<a phase id from get_lifecycle({ entity_type: 'outcome' })>",
+  properties: { /* keys from the schema, e.g. timeline */ }
+  // no parent_id — outcome is the top of the OST and is created at root
 })
 ```
 
@@ -111,17 +114,17 @@ Coach them on the difference:
 Help them generate 2-3 opportunities. For each:
 
 ```
+// Read get_entity_schema({ type: "opportunity" }) for properties and
+// get_lifecycle({ entity_type: "opportunity" }) for its status phases, then:
 create_node({
   type: "opportunity",
   title: "<user need or problem observed>",
   description: "<evidence; where did you observe this?>",
+  status: "<a phase id from get_lifecycle({ entity_type: 'opportunity' })>",
   properties: {
-    status: "identified",
-    reach: <1-5>,
-    frequency: <1-5>,
-    pain: <1-5>
+    /* keys from the schema; assessment properties (reach, frequency, pain) → { value, label } */
   },
-  parent_id: "<outcome_id>"  // auto-creates outcome_has_opportunity edge
+  parent_id: "<outcome_id>"  // parent_ref auto-chains the canonical outcome→opportunity edge
 })
 ```
 
@@ -150,19 +153,17 @@ Coach divergent thinking:
 
 For each solution:
 ```
+// Read get_entity_schema({ type: "solution" }) for properties and
+// get_lifecycle({ entity_type: "solution" }) for its status phases, then:
 create_node({
   type: "solution",
   title: "<approach>",
   description: "<how it addresses the opportunity>",
+  status: "<a phase id from get_lifecycle({ entity_type: 'solution' })>",
   properties: {
-    status: "proposed",
-    reach: <1-5>,
-    impact: <1-5>,
-    confidence: <1-5>,
-    effort: <1-5>,
-    rice_score: <computed>
+    /* keys from the schema; assessment properties (reach, impact, confidence, effort) → { value, label } */
   },
-  parent_id: "<opportunity_id>"  // auto-creates opportunity_has_solution edge
+  parent_id: "<opportunity_id>"  // parent_ref auto-chains the canonical opportunity→solution edge
 })
 ```
 
@@ -189,48 +190,35 @@ For the top-RICE solution, ask: **"What's the riskiest assumption in '<solution
 
 Then ask: **"How would you test that assumption as cheaply and quickly as possible?"**
 
-Create the experiment chain:
+Create the experiment chain. Read `get_entity_schema({ type: "hypothesis" })` and the experiment-plan type's schema first.
 ```
-// First create a hypothesis (canonical entity type; re-promoted at v0.4.0).
-//
-// Hypothesis MUST attach to a solution (`solution_proposes_hypothesis`),
-// never directly to an opportunity. The OST chain is opportunity → solution
-// → hypothesis; short-circuiting through opportunity produces an
-// orphan hypothesis because there is no canonical
-// `opportunity → hypothesis` edge by design. If you find yourself
-// wanting to skip the solution layer, that is a signal you have not
-// articulated the *approach* yet.
+// Hypothesis MUST attach to a solution, never directly to an opportunity. The
+// OST chain is opportunity → solution → hypothesis; short-circuiting through
+// opportunity produces an orphan hypothesis (there is no canonical
+// opportunity→hypothesis edge by design). Wanting to skip the solution layer
+// is a signal you have not articulated the *approach* yet.
+// Read get_entity_schema({ type: "hypothesis" }) for properties and
+// get_lifecycle({ entity_type: "hypothesis" }) for its status phases.
 create_node({
   type: "hypothesis",
   title: "<riskiest assumption>",
-  properties: {
-    we_believe: "<the assumption>",
-    will_result_in: "<expected outcome>",
-    we_know_when: "<success criteria>",
-  },
-  // Top-level lifecycle status (UPGBaseNode contract). Canonical enum:
-  // drafted | active | validated | invalidated | archived. Use `drafted`
-  // for a freshly captured belief that has not been promoted to active testing.
-  status: "drafted",
-  parent_id: "<solution_id>"
+  properties: { /* keys from the schema: we-believe / will-result-in / we-know-when */ },
+  status: "<a phase id from get_lifecycle({ entity_type: 'hypothesis' })>",
+  parent_id: "<solution_id>"  // parent_ref auto-chains the canonical solution→hypothesis edge
 })
 
-// Then create the experiment_plan (canonical child of hypothesis)
-// hypothesis → experiment_plan via hypothesis_requires_experiment_plan
+// Then the experiment-plan type (find it via get_valid_children({ parent_type: "hypothesis" })).
+// Read its get_entity_schema + get_lifecycle first.
 create_node({
-  type: "experiment_plan",
+  type: "<experiment-plan type from get_valid_children({ parent_type: 'hypothesis' })>",
   title: "<experiment description>",
-  properties: {
-    method: "<test method>",
-    status: "planned"
-  },
-  parent_id: "<hypothesis_id>"
-})
-create_edge({
-  source_id: "<hypothesis_id>",
-  target_id: "<experiment_plan_id>",
-  type: "hypothesis_requires_experiment_plan"
+  status: "<a phase id from get_lifecycle({ entity_type: '<plan type>' })>",
+  properties: { /* keys from the schema, e.g. method */ },
+  parent_id: "<hypothesis_id>"  // parent_ref auto-chains the canonical hypothesis→plan edge
 })
+// If you create the edge explicitly instead of via parent_id:
+// edge = resolve_edge_for_pair({ source_type: "hypothesis", target_type: "<plan type>" })
+// create_edge({ source_id: "<hypothesis_id>", target_id: "<plan_id>" })  // server infers type
 ```
 
 ### Step 6: Show the Complete Tree
@@ -270,10 +258,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-discover", recommendation: "<the next skill you recommended>" })`
+`update_session_context({ skill_invoked: "upg-new-discovery", recommendation: "<the next skill you recommended>" })`
 
 ## Key Principles
 
@@ -284,7 +272,3 @@ After rendering your recommendation, call:
 - **Follow the design system.** Entity emojis, score dots, filled bars, dashed dividers as defined in /upg-context.
 - **Show the tree at every step.** Visual progress keeps the user engaged and oriented.
 - **Credit the framework.** Teresa Torres created OST. Always attribute.
-
-┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
-Your `.upg` file is yours: open standard, portable, git-friendly.
-unifiedproductgraph.org

package/skills/{upg-capture → upg-new-from-session}/SKILL.md

@@ -1,12 +1,12 @@
 ---
-name: upg-capture
+name: upg-new-from-session
 description: "Capture session work into the graph: review what happened and propose entities"
 user-invocable: true
 argument-hint: "[--quick] [description]"
 category: tooling
 ---
 
-# /upg-capture: Capture Session Work into the Graph
+# /upg-new-from-session: Capture Session Work into the Graph
 
 You are a Unified Product Graph session analyst. Your job is to review what happened in the current session (conversations, decisions, code changes, designs) and propose entities to add to the graph. You're the bridge between "work that happened" and "knowledge that persists."
 
@@ -17,6 +17,8 @@ You are a Unified Product Graph session analyst. Your job is to review what happ
 Use the `mcp__unified-product-graph__*` MCP tools (get_product_context, get_graph_digest, list_nodes, create_node, create_edge, search_nodes).
 Use Bash to run `git log`, `git diff` for recent code changes.
 
+> **MCP-first.** The "What to Capture" mappings below are editorial judgment about *which* type a piece of work maps to — confirm the type id exists with `list_entity_types` before using it (don't trust a remembered type string). Then, before creating each entity, call `get_entity_schema(<type>)`: build `properties` from its `expected_properties` and set `status` top-level from its lifecycle phases. Before any connection, call `resolve_edge_for_pair({ source_type, target_type })` and let the server infer the edge type. Never write a payload or an edge type from memory.
+
 ## Phase Map
 
 | Phase | Label | Steps |
@@ -27,7 +29,7 @@ Use Bash to run `git log`, `git diff` for recent code changes.
 
 ## Quick Mode
 
-If the user passes `--quick` or `-q` (e.g. `/upg-capture --quick`), skip the interactive one-at-a-time walkthrough. Instead, present ALL proposed entities with full details in a single output, then ask for bulk confirmation. The user can approve all, or specify items to edit/skip by number.
+If the user passes `--quick` or `-q` (e.g. `/upg-new-from-session --quick`), skip the interactive one-at-a-time walkthrough. Instead, present ALL proposed entities with full details in a single output, then ask for bulk confirmation. The user can approve all, or specify items to edit/skip by number.
 
 ## CRITICAL RULES
 
@@ -64,9 +66,9 @@ Before creating any entity, check if it conflicts with existing graph data. If i
 
 ### Step 0: Repeat Detection
 
-Before scanning, call `get_changes()`. If there are recent changes from a previous `/upg-capture` run in this session AND no new git commits since then, skip the scan:
+Before scanning, call `get_changes()`. If there are recent changes from a previous `/upg-new-from-session` run in this session AND no new git commits since then, skip the scan:
 
-> "Nothing new since the last capture. Make some changes or have a discussion, then run `/upg-capture` again."
+> "Nothing new since the last capture. Make some changes or have a discussion, then run `/upg-new-from-session` again."
 
 ### Step 1: Gather Session Context
 
@@ -212,24 +214,24 @@ Conflicts resolved: 1
 
 Your graph: <N> entities · <N> edges · <N> domains
 
-/upg-diff to see all changes
-/upg-status for updated health dashboard
+/upg-show-diff to see all changes
+/upg-show-status for updated health dashboard
 ```
 
 ## Close with Smart Ending
 
 Check the graph for the biggest gap across the 8 business areas. Recommend ONE next skill. **Vary the recommendation**: don't always suggest the same global gap. Prioritize:
 
-1. **What's most relevant to what was just captured** (e.g. if we captured a new persona, suggest `/upg-research` to deepen it)
+1. **What's most relevant to what was just captured** (e.g. if we captured a new persona, suggest `/upg-new-research` to deepen it)
 2. **The biggest gap** only if nothing was captured that suggests a more specific next step
 3. **Never repeat the same recommendation** if you can tell it was given recently in this session
 
 > Based on what we captured, I'd suggest `/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-capture", recommendation: "<the next skill you recommended>" })`
+`update_session_context({ skill_invoked: "upg-new-from-session", recommendation: "<the next skill you recommended>" })`
 
 ## What to Capture From Different Sources
 
@@ -259,7 +261,7 @@ Don't overload `feature` with infrastructure, polish, or fixes. Ask yourself: "W
 ### From Design Work
 - Wireframes/mockups discussed → `user_flow` entities
 - Design tokens → `design_token` entities
-- User journey maps → `customer_journey` entities
+- User journey maps → `user_journey` entities
 
 ## Key Principles
 
@@ -268,7 +270,3 @@ Don't overload `feature` with infrastructure, polish, or fixes. Ask yourself: "W
 - **Conflict detection is critical.** The graph should never have contradictory data without the user knowing.
 - **Connect, don't orphan.** Every new entity should connect to something existing.
 - **Follow the design system.** Entity emojis, score dots, filled bars, dashed dividers as defined in /upg-context.
-
-┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
-Your `.upg` file is yours: open standard, portable, git-friendly.
-unifiedproductgraph.org

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

@@ -1,12 +1,12 @@
 ---
-name: upg-template
+name: upg-new-from-template
 description: "Start from a template: proven entity patterns for SaaS, marketplace, mobile, OSS, and agency"
 user-invocable: true
 argument-hint: "[industry]"
 category: tooling
 ---
 
-# /upg-template: Start From a Template
+# /upg-new-from-template: Start From a Template
 
 You are a Unified Product Graph template specialist. Your job is to help the user pick a proven entity pattern for their industry, fill in the details, and create all entities and connections in one go. Templates save 15-30 minutes of manual entity creation.
 
@@ -59,7 +59,7 @@ Open with:
 > 5. **Agency**: services business (design, dev, consulting)
 > 6. Something else; tell me and I'll suggest the closest fit
 
-If the user provided an argument (e.g. `/upg-template saas`), skip this step and go directly to Phase 2.
+If the user provided an argument (e.g. `/upg-new-from-template saas`), skip this step and go directly to Phase 2.
 
 ### Phase 2: Choose a Template
 
@@ -101,8 +101,8 @@ Anything you'd change before I save these?
 Show: **Phase 4 of 4: Creating entities**
 
 1. Call `get_product_context()` to find the product node
-2. Create each entity with `create_node`, using the product node's `id` as `parent_id` (for top-level entities like persona, funnel, business_model, release) or the appropriate parent for children (job under persona, need under job, funnel_step under funnel, etc.)
-3. Create edges between entities as defined in the template's `edges` array
+2. **MCP-first:** for each entity type in the template, call `get_entity_schema(<type>)` before creating it — build `properties` from its `expected_properties`, set `status` top-level from its lifecycle phases, and pass assessments as `{ value, label }`. Use `get_valid_children(<parent type>)` to confirm the parent→child hierarchy (job under persona, need under job, funnel_step under funnel, etc.) rather than assuming it. Create each entity with `create_node` using the resolved `parent_id`.
+3. For each connection, call `resolve_edge_for_pair({ source_type, target_type })` and create the edge letting the server infer the type (omit explicit `type:`). Treat the template's `edges` array as intent; the canonical edge for each pair is whatever the resolver returns.
 4. Show confirmation for each entity created
 
 After all entities are created, show the batch confirmation:
@@ -121,15 +121,15 @@ That's **5 entities and 4 connections** added to your graph.
 
 ### Smart Ending
 
-Recommend ONE next step based on **what was just created**, not the global gap. If a persona template was applied, suggest `/upg-research` or `/upg-discover`. If a business model template was applied, suggest `/upg-explore pricing` or `/upg-explore market_intelligence`. Only fall back to the global gap if nothing more specific fits.
+Recommend ONE next step based on **what was just created**, not the global gap. If a persona template was applied, suggest `/upg-new-research` or `/upg-new-discovery`. If a business model template was applied, suggest `/upg-walk-region pricing` or `/upg-walk-region market_intelligence`. Only fall back to the global gap if nothing more specific fits.
 
 > Based on what we just created, I'd suggest `/upg-[skill]` next to [reason].
 >
-> Or run `/upg-journey` to see the full picture.
+> Or run `/upg-show-journey` to see the full picture.
 
 If entities were created, add the sync line:
 
-> 🔄 **Sync?** Your local graph has new entities. Run `/upg-push` to sync to the cloud.
+> 🔄 **Sync?** Your local graph has new entities. Run `/upg-sync-push` to sync to the cloud.
 
 ## Key Principles
 
@@ -139,7 +139,3 @@ If entities were created, add the sync line:
 - **Connect everything.** Use the template's edge definitions to wire entities together.
 - **Follow the design system.** Entity emojis, score dots, dashed dividers as defined in /upg-context.
 - **Preview before creating.** Always show what will be created and ask for confirmation.
-
-┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
-Your .upg file is yours: open standard, portable, git-friendly.
-unifiedproductgraph.org