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

package/skills/{upg-push → upg-sync-push}/SKILL.md

@@ -1,12 +1,12 @@
 ---
-name: upg-push
+name: upg-sync-push
 description: "Push your local product graph to The Product Creator cloud"
 user-invocable: true
 argument-hint: "[product-name]"
 category: tooling
 ---
 
-# /upg-push: Push Local Graph to Cloud
+# /upg-sync-push: Push Local Graph to Cloud
 
 You are a Unified Product Graph sync engine. Your job is to push the user's local `.upg` graph to The Product Creator cloud, enabling visual canvas, framework trees, team collaboration, and all the features that go beyond what the CLI can offer.
 
@@ -63,7 +63,7 @@ list_nodes({ limit: 200 })
 If the local graph is empty or has no product:
 ```
 Your local graph is empty; nothing to push yet.
-Run /upg-init to bootstrap your first product graph.
+Run /upg-new-graph to bootstrap your first product graph.
 ```
 
 ### Step 2: Check Cloud Connection
@@ -83,7 +83,7 @@ To push your graph to The Product Creator, you need an API key.
 
    In .mcp.json, update the upg-cloud server with your API key.
 
-Once configured, run /upg-push again.
+Once configured, run /upg-sync-push again.
 ```
 
 ### Step 3: Check for .upg-sync File

package/skills/{upg-snapshot → upg-sync-snapshot}/SKILL.md

@@ -1,12 +1,12 @@
 ---
-name: upg-snapshot
+name: upg-sync-snapshot
 description: "Save a named checkpoint of your product graph: version your thinking"
 user-invocable: true
 argument-hint: "[message]"
 category: tooling
 ---
 
-# /upg-snapshot: Version Your Thinking
+# /upg-sync-snapshot: Version Your Thinking
 
 You are a Unified Product Graph versioning tool. Your job is to save a named checkpoint of the product graph; a git commit plus version metadata in the .upg file. Fast, no questions beyond the message.
 
@@ -102,7 +102,3 @@ Rollback:     git checkout HEAD~1 -- product.upg
 - **Silent on success.** Don't explain what versioning is. Just confirm.
 - **Graceful on failure.** If git isn't available, still patch the version and say so.
 - **No graph entity mutations.** This skill versions the file; it does not create or modify graph entities.
-
-┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
-Your `.upg` file is yours: open standard, portable, git-friendly.
-unifiedproductgraph.org

package/skills/upg-trace/SKILL.md

@@ -45,9 +45,9 @@ These are examples. The user may want to trace any path in the graph; canonical
 
 Before starting the trace, call `get_graph_digest()` and `resolve_edge_for_pair({ source_type, target_type })` for the first hop of the requested path. If:
 - The canonical edge for the first hop doesn't exist in the graph (zero matching edges): surface:
-  > Your graph has no `[source_type] → [target_type]` connections yet; the trace would stop at hop 1. Run `/upg-connect` or `/upg-explore` to add the missing links first.
+  > Your graph has no `[source_type] → [target_type]` connections yet; the trace would stop at hop 1. Run `/upg-link` or `/upg-walk-region` to add the missing links first.
 - The graph has fewer than 10 nodes total: surface:
-  > Your graph is quite sparse. Traces are most useful once you have at least a few connected entities. Run `/upg-init` or `/upg-discover` to build out the foundation.
+  > Your graph is quite sparse. Traces are most useful once you have at least a few connected entities. Run `/upg-new-graph` or `/upg-new-discovery` to build out the foundation.
 
 If the user wants to proceed despite sparse data, proceed, but note "limited graph depth" in the output.
 
@@ -152,7 +152,7 @@ has no documented route to a potential solution.
 
 For each gap, offer:
 - "Want me to create a stub opportunity node here so the chain is complete?"
-- "Want to flag this for `/upg-gaps` to include in a full graph gap analysis?"
+- "Want to flag this for `/upg-check-gaps` to include in a full graph gap analysis?"
 
 ### Step 6: Capture What the Trace Revealed
 
@@ -173,10 +173,10 @@ Always confirm before writing. Never silently create nodes or edges.
 
 Pick ONE next move based on what the trace found:
 
-- **If the path was complete and well-connected:** "Clean chain from [anchor] to [destination]. Want to `/upg-snapshot` to preserve this as a known-good state?"
-- **If one or more gaps were found:** "Found [N] gap(s) in the chain. Want to run `/upg-gaps` for a full structural gap audit across the product?"
+- **If the path was complete and well-connected:** "Clean chain from [anchor] to [destination]. Want to `/upg-sync-snapshot` to preserve this as a known-good state?"
+- **If one or more gaps were found:** "Found [N] gap(s) in the chain. Want to run `/upg-check-gaps` for a full structural gap audit across the product?"
 - **If the trace revealed a strategic disconnect:** "The chain breaks before it reaches [destination]. That might mean the strategy isn't wired to execution yet. Want to run `/upg-reflect` to examine why?"
-- **If a hypothesis or experiment was the anchor and no learning exists:** "This hypothesis has no learning yet; the experiment hasn't landed. Want to run `/upg-hypothesis` to check on its test design?"
+- **If a hypothesis or experiment was the anchor and no learning exists:** "This hypothesis has no learning yet; the experiment hasn't landed. Want to run `/upg-new-hypothesis` to check on its test design?"
 - **If the user discovered they want to walk a different path:** "Want to start a new trace from a different anchor?"
 
 After rendering your recommendation, call:
@@ -194,4 +194,4 @@ After rendering your recommendation, call:
 
 Trace is one of the 5 canonical UPG approaches (`get_approach({ approach_id: "trace" })`). The approach had no skill home; the MCP `trace` tool existed but no conversational surface orchestrated a guided, multi-hop walk through the graph with gap detection and capture. This skill closes that gap.
 
-It is the only canonical entry point for the Trace approach in the user-invocable surface. Other skills use tracing implicitly (a good `/upg-impact` walks downstream edges), but `/upg-trace` is where the user goes when they explicitly want to plot a route; to test whether the product graph is coherent from anchor to destination.
+It is the only canonical entry point for the Trace approach in the user-invocable surface. Other skills use tracing implicitly (a good `/upg-show-impact` walks downstream edges), but `/upg-trace` is where the user goes when they explicitly want to plot a route; to test whether the product graph is coherent from anchor to destination.

package/skills/{upg-workspace → upg-use-workspace}/SKILL.md

@@ -1,12 +1,12 @@
 ---
-name: upg-workspace
+name: upg-use-workspace
 description: "Manage your UPG workspace: list products, switch between them, add new ones"
 user-invocable: true
 argument-hint: "[list|switch|add|init]"
 category: tooling
 ---
 
-# /upg-workspace: Manage Your Product Workspace
+# /upg-use-workspace: Manage Your Product Workspace
 
 Manage multiple product graphs. Fast, direct, sub-commands keep it tight. Read `/upg-context` before producing output.
 
@@ -27,8 +27,8 @@ Check if `.upg/workspace.json` exists (Bash). Call `list_local_products` for ent
   1. ● My SaaS (active); 42 entities, mvp stage
   2. ○ Client Project; 12 entities, idea stage
   3. ○ Internal Tools; 8 entities, idea stage
-  Switch: /upg-workspace switch <number>
-  Add:    /upg-workspace add
+  Switch: /upg-use-workspace switch <number>
+  Add:    /upg-use-workspace add
 ```
 
 **Single-file mode** (no workspace.json, 1+ files):
@@ -36,9 +36,9 @@ Check if `.upg/workspace.json` exists (Bash). Call `list_local_products` for ent
 ## Your UPG Workspace
   📄 Single-file mode (product.upg)
   ● My SaaS; 42 entities, mvp stage
-  Want multiple products? Run /upg-workspace init
+  Want multiple products? Run /upg-use-workspace init
 ```
-If multiple loose files, number them and suggest `init`. If zero files, point to `/upg-init`.
+If multiple loose files, number them and suggest `init`. If zero files, point to `/upg-new-graph`.
 
 ---
 
@@ -69,8 +69,8 @@ If multiple loose files, number them and suggest `init`. If zero files, point to
 
 Upgrades loose .upg files to `.upg/` workspace mode.
 
-- If workspace.json already exists: "You're already in workspace mode. Run `/upg-workspace` to see your products." Done.
-- If no .upg files exist: "No .upg files found. Run `/upg-init` first." Done.
+- If workspace.json already exists: "You're already in workspace mode. Run `/upg-use-workspace` to see your products." Done.
+- If no .upg files exist: "No .upg files found. Run `/upg-new-graph` first." Done.
 
 Otherwise:
 1. `mkdir -p .upg` and `mv *.upg .upg/` for each file.
@@ -95,9 +95,3 @@ Otherwise:
 - Show entity count (nodes) and stage for each product.
 - No unnecessary questions: `list` and `switch` need zero extra input.
 - Standard footer on every output:
-
-```
-┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
-Your .upg file is yours: open standard, portable, git-friendly.
-unifiedproductgraph.org
-```

package/skills/{upg-run → upg-walk-playbook}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: upg-run
+name: upg-walk-playbook
 description: "Run any UPG playbook: generic driver for canonical playbooks"
 user-invocable: true
 argument-hint: "[playbook-id] (e.g. playbook:strategy-outcomes, playbook:business-gtm-growth, playbook:experience-design-brand)"
@@ -7,23 +7,23 @@ category: cognitive
 approaches: [plan]
 ---
 
-# /upg-run: Generic Playbook Driver
+# /upg-walk-playbook: Generic Playbook Driver
 
 You are a UPG playbook runner. You take any canonical `UPGPlaybook` record from `@unified-product-graph/core` and walk the user through it; without a hand-crafted skill per playbook.
 
-> Plan called this `/upg-explore` but that name is taken by the single-entity creation skill. `/upg-run` is the playbook driver.
+> Plan called this `/upg-walk-region` but that name is taken by the single-entity creation skill. `/upg-walk-playbook` is the playbook driver.
 
 **Before producing any output, read the design system:** `/upg-context` for emoji mappings, formatting rules, and shared interaction patterns.
 
 ## How this skill works
 
-Unlike hand-crafted skills, `/upg-run` reads playbook structure at runtime. You do not carry domain-specific conversational voice for each playbook; instead, each step's `prompt_hint` and `name` are your script.
+Unlike hand-crafted skills, `/upg-walk-playbook` reads playbook structure at runtime. You do not carry domain-specific conversational voice for each playbook; instead, each step's `prompt_hint` and `name` are your script.
 
 For `kind: 'domain_guide'` steps, the runtime expands them via `DomainUsageGuide[domain_id]`; you then walk the user through the creation sequence, surfacing the domain's anti-patterns and required cross-domain bridges.
 
 ## Argument parsing
 
-The user invokes this skill with a playbook id, e.g. `/upg-run playbook:business-gtm-growth`.
+The user invokes this skill with a playbook id, e.g. `/upg-walk-playbook playbook:business-gtm-growth`.
 
 If no argument is given, list the canonical ids and ask the user to pick one. Use `mcp__unified-product-graph__list_playbooks` (optionally with `canonical_only: true` to surface the 10 region defaults). v0.3.0 ships 12 playbooks across 10 regions:
 
@@ -68,7 +68,7 @@ Create each of `step.entity_types` in order. Use `batch_create_nodes` with `pare
 
 #### `kind: 'sub_sequence'`
 
-Recursively run `/upg-run` with `step.sub_sequence_id` (which is namespace-prefixed: `playbook:*` or `technique:*`).
+Recursively run `/upg-walk-playbook` with `step.sub_sequence_id` (which is namespace-prefixed: `playbook:*` or `technique:*`).
 
 ### 4. Use the step's labels
 
@@ -104,7 +104,7 @@ When the domain guide's `anti_patterns` match what the user is doing, name it. G
 
 ## Boundaries
 
-Playbook definitions are read-only from `@unified-product-graph/core`; use step metadata as the script rather than hand-crafting voice per playbook. The keeper skills (`/upg-persona`, `/upg-research`) keep their own SKILL.md for narrative synthesis the generic driver can't match. Single-entity creation is `/upg-explore`'s job.
+Playbook definitions are read-only from `@unified-product-graph/core`; use step metadata as the script rather than hand-crafting voice per playbook. The keeper skills (`/upg-new-persona`, `/upg-new-research`) keep their own SKILL.md for narrative synthesis the generic driver can't match. Single-entity creation is `/upg-walk-region`'s job.
 
 ## End of run
 
@@ -119,8 +119,8 @@ If the final step (or any completed step) declared `next_sequence_on_gap` **and*
 
 > "Done with `playbook:strategy-outcomes`. I noticed discovery research isn't modelled yet; want me to run `playbook:discovery-research-validation` next?"
 
-The user picks yes/no/different playbook. On yes, invoke `/upg-run <chained-id>` directly.
+The user picks yes/no/different playbook. On yes, invoke `/upg-walk-playbook <chained-id>` directly.
 
-If no chain is declared, fall back to suggesting based on graph gaps from `/upg-gaps`.
+If no chain is declared, fall back to suggesting based on graph gaps from `/upg-check-gaps`.
 
-Invite the user to `/upg-status` or `/upg-gaps` to see what changed.
+Invite the user to `/upg-show-status` or `/upg-check-gaps` to see what changed.

package/skills/upg-walk-region/SKILL-DETAIL.md

@@ -0,0 +1,320 @@
+---
+name: upg-explore-detail
+description: "Full property schemas and edge type reference for /upg-walk-region"
+---
+
+# /upg-walk-region: Property Schemas & Edge Types (Detail)
+
+This file is an **illustrative reference**, not the spec. It is loaded on demand by /upg-walk-region. The authoritative properties and valid children for any type come from **`get_entity_schema({ type: <type> })`** at runtime; the authoritative lifecycle phases (the top-level `status` enum) come from **`get_lifecycle({ entity_type: <type> })`** (not `get_entity_schema`); and the canonical edge for any pair comes from **`resolve_edge_for_pair({ source_type, target_type })`**. Where this file disagrees with those live calls, the live calls win. Use the blocks below to shape your questions, then confirm against the schema before writing.
+
+## Full Property Schemas
+
+When creating an entity, actively prompt for the key properties. Do not just set title and description.
+
+> **Two conventions these schemas follow (and you must too):**
+> 1. **Lifecycle `status` is a TOP-LEVEL field on the node, not a property.** Where a block below shows `status (top-level ...)`, pass it as a top-level `status:` argument to `create_node`, alongside (not inside) `properties`. The shown enum is illustrative — confirm the live phase set with `get_lifecycle({ entity_type: <type> })`, which is the source of truth (`get_entity_schema` does not return it). Note: a `*_status` PROPERTY (e.g. `objective_status`, `kr_status`) is a SEPARATE enum field that lives inside `properties` and is distinct from the top-level lifecycle `status` — never copy one into the other.
+> 2. **Assessments (`reach`, `frequency`, `pain`, `impact`, `confidence`, `effort`, `importance`, `current_satisfaction`) are `{ value, label }` objects on a 1-5 scale, NOT bare integers.** Where a block shows `1-5`, write `{ value: <1-5>, label: "<word>" }`.
+
+### outcome
+```json
+{
+  "timeline": "When this should be achieved"
+}
+```
+Ask: "What's the timeline for this outcome?"
+
+### metric (KPI)
+```json
+{
+  "designation": "kpi",
+  "current_value": 0,
+  "target_value": 100,
+  "unit": "%, users, seconds, etc.",
+  "range_min": 0,
+  "range_max": 100
+}
+```
+Ask: "What's the current value? What's the target? What unit?" (KPIs are `metric` nodes with `designation: "kpi"`; the `kpi` type was consolidated into `metric` in v0.1.0.)
+
+### objective
+```json
+{
+  "timeframe": "Q1 2026, H2 2026, etc.",
+  "objective_status": "active | achieved | deferred",
+  "status (top-level lifecycle)": "draft | active | achieved | missed | deferred"
+}
+```
+
+### key_result
+```json
+{
+  "current_value": 0,
+  "target_value": 100,
+  "unit": "metric unit",
+  "kr_status": "on_track | at_risk | behind | achieved",
+  "status (top-level lifecycle)": "on_track | at_risk | behind | achieved"
+}
+```
+
+### opportunity
+```json
+{
+  "status (top-level)": "identified | validated | deferred",
+  "reach": "{ value: 1-5, label }",
+  "frequency": "{ value: 1-5, label }",
+  "pain": "{ value: 1-5, label }"
+}
+```
+Ask: "How many people does this affect (reach 1-5)? How often (frequency 1-5)? How painful (1-5)?"
+
+### solution
+```json
+{
+  "status (top-level)": "proposed | in_progress | shipped | deferred",
+  "reach": "{ value: 1-5, label }",
+  "impact": "{ value: 1-5, label }",
+  "confidence": "{ value: 1-5, label }",
+  "effort": "{ value: 1-5, label }",
+  "rice_score": "(reach x impact x confidence) / effort"
+}
+```
+Ask: "Let's RICE-score this. Reach (1-5)? Impact (1-5)? Confidence (1-5)? Effort (1-5)?"
+
+### experiment
+```json
+{
+  "method": "Description of the test method",
+  "status (top-level)": "planned | running | analysing | done",
+  "start_date": "ISO date",
+  "end_date": "ISO date"
+}
+```
+(For the hypothesis test chain, prefer `experiment_plan` -> `experiment_run`; `experiment` is the standalone test unit. There is no canonical `hypothesis -> experiment` edge.)
+
+### learning
+```json
+{
+  "result": "What happened",
+  "metric": "What was measured",
+  "result_value": 0,
+  "confidence_impact": "strengthens | weakens | neutral"
+}
+```
+
+### competitor
+```json
+{
+  "positioning": "How they position themselves",
+  "pricing_model": "Their pricing approach",
+  "strengths": ["What they do well"],
+  "weaknesses": ["Where they fall short"],
+  "website": "URL"
+}
+```
+
+### feature
+```json
+{
+  "status (top-level)": "proposed | in_progress | shipped | archived"
+}
+```
+
+### user_story
+```json
+{
+  "as_a": "persona name",
+  "i_want_to": "action",
+  "so_that": "outcome",
+  "effort": 0
+}
+```
+(`user_story` is lifecycle-free; it has no `status` phases. Track delivery state on the parent epic or via task entities, not a story `status`.)
+
+### need
+```json
+{
+  "valence": "pain | gap | constraint",
+  "frequency": "{ value: 1-5, label }",
+  "severity": "{ value: 1-5, label }"
+}
+```
+Ask: "How often does this happen (1-5)? How bad is it (1-5)? Is this a pain, gap, or constraint?" (The old `pain_point` type was consolidated into `need` with `valence: "pain"` in v0.1.0. `frequency` and `severity` are assessments; pass `{ value, label }`.)
+
+### research_study
+```json
+{
+  "method": "interview | usability | survey | diary | analytics",
+  "status (top-level)": "planned | in_progress | analysing | complete",
+  "participant_count": 0
+}
+```
+
+### insight (research insight)
+```json
+{
+  "insight_level": "pattern | finding | actionable | strategic",
+  "confidence": "{ value: 1-5, label }",
+  "source_method": "method from the study",
+  "evidence_count": 0,
+  "status (top-level)": "proposed | validated | applied | retired"
+}
+```
+(The old `research_insight`, `finding`, and `ux_insight` types were all consolidated into `insight` in v0.1.0.)
+
+### business_model
+```json
+{
+  "canvas_type": "lean | bmc | custom",
+  "customer_segments": ["Who you serve"],
+  "channels": ["How you reach them"],
+  "key_activities": ["What you do"],
+  "key_resources": ["What you need"],
+  "key_partners": ["Who helps you"],
+  "status (top-level)": "drafted | testing | validated | invalidated | pivoted"
+}
+```
+Ask: "What type of canvas is this; lean, BMC, or custom? Who are the customer segments? What are the key activities?"
+
+### value_proposition
+```json
+{
+  "for_segment": "Which customer segment this serves",
+  "gains": ["What gains you create"],
+  "pain_relievers": ["What pains you relieve"],
+  "products_and_services": ["What you offer"],
+  "differentiator": "Why this is unique vs. alternatives",
+  "status (top-level)": "drafted | testing | validated | invalidated"
+}
+```
+Ask: "Which customer segment is this for? What gains does it create? What pains does it relieve? What makes it different from alternatives?"
+
+### gtm_strategy
+```json
+{
+  "target_market": "Primary market",
+  "motion": "product_led | sales_led | community_led | hybrid",
+  "channels": ["Distribution channels"],
+  "timeline": "Launch timeline",
+  "success_metrics": ["How you'll measure success"],
+  "status (top-level)": "planning | active | paused | completed | sunset"
+}
+```
+Ask: "What's the target market? Is this product-led, sales-led, or community-led? What channels will you use?"
+
+### ideal_customer_profile
+```json
+{
+  "company_size": "1-10 | 11-50 | 51-200 | 201-1000 | 1000+",
+  "industry": "Target industry",
+  "budget_range": "Typical budget",
+  "buying_triggers": ["What causes them to look for a solution"],
+  "disqualifiers": ["Red flags; who is NOT a fit"],
+  "decision_makers": ["Roles involved in the buying decision"]
+}
+```
+Ask: "What size company is the ideal fit? What industry? What triggers them to start looking for a solution like yours?"
+
+### positioning
+```json
+{
+  "for_whom": "Target audience",
+  "who_need": "Their primary need",
+  "our_product_is": "Category or frame",
+  "that_provides": "Key benefit",
+  "unlike": "Primary alternative",
+  "we_differentiate_by": "Unique differentiator",
+  "framework": "april_dunford | moore | custom"
+}
+```
+Ask: "Let's use a positioning statement. For whom? Who need what? What category is your product? How do you differentiate?"
+
+### user_journey
+```json
+{
+  "persona": "Which persona takes this journey",
+  "scenario": "The specific context or trigger",
+  "stages": ["awareness", "consideration", "decision", "onboarding", "retention"],
+  "emotional_arc": "How feelings change across stages",
+  "status (top-level)": "draft | review | published | archived"
+}
+```
+Ask: "Which persona takes this journey? What's the scenario? What stages does it cover?"
+
+### decision (architecture / design / product)
+```json
+{
+  "layer": "engineering | design | product",
+  "context": "Why this decision was needed",
+  "decision": "What was decided",
+  "alternatives_considered": ["What else was evaluated"],
+  "consequences": ["Trade-offs and implications"],
+  "status (top-level)": "proposed | reviewing | approved | rejected | deprecated",
+  "decided_by": "Who made the decision",
+  "decided_on": "ISO date"
+}
+```
+Ask: "What's the context; why was this decision needed? What was decided? What alternatives were considered? Which layer does this belong to; engineering, design, or product?" (`architecture_decision`, `design_decision`, and `product_decision` were consolidated into the single `decision` type with a `layer` property in v0.2.0.)
+
+### growth_loop
+```json
+{
+  "loop_type": "viral | content | paid | product",
+  "trigger": "What starts the loop",
+  "action": "What the user does",
+  "output": "What the action produces",
+  "reinvestment": "How the output feeds back into the trigger",
+  "time_to_complete": "How long one cycle takes"
+}
+```
+Ask: "What type of loop; viral, content, paid, or product? What triggers it? What action does the user take? How does the output feed back into the trigger?" (`growth_loop` is lifecycle-free; no `status` phases.)
+
+### pricing_strategy
+```json
+{
+  "model": "freemium | free_trial | usage_based | flat_rate | per_seat | tiered | custom",
+  "anchor_price": "Primary price point",
+  "willingness_to_pay": "Researched WTP range",
+  "competitive_position": "cheaper | parity | premium",
+  "tiers": ["Tier names"],
+  "status (top-level)": "planning | active | paused | completed | sunset"
+}
+```
+Ask: "What pricing model; freemium, usage-based, per-seat, etc.? What's the anchor price? How does this compare to competitors; cheaper, parity, or premium?"
+
+### ai_model
+```json
+{
+  "model_type": "llm | classifier | recommender | generative | embedding | custom",
+  "provider": "openai | anthropic | google | huggingface | self_hosted | other",
+  "use_case": "What this model does in the product",
+  "input_type": "text | image | audio | structured | multimodal",
+  "output_type": "text | classification | embedding | structured | multimodal",
+  "latency_target": "Target response time",
+  "cost_per_call": "Estimated cost",
+  "status (top-level)": "evaluating | staging | production | deprecated | retired"
+}
+```
+Ask: "What type of model; LLM, classifier, recommender? Which provider? What's its use case in the product?"
+
+## Edge Types: Valid Connections
+
+After creating an entity, search for related entities and suggest connections.
+
+**The canonical edge for any pair is determined by the spec, not by a `{source}_has_{target}` pattern.** Most UPG edges use a meaningful verb (e.g. `product_pursues_outcome`, `job_surfaces_need`), and a `{source}_has_{target}` name is almost always wrong. Before you create an edge:
+
+1. Call `resolve_edge_for_pair({ source_type, target_type })` to get the canonical edge type (or `null` if no direct edge exists — then bridge through an intermediate entity).
+2. Or browse the full catalog with `list_edge_types` / `get_edge_type`.
+
+When you pass `parent_id` to `create_node`, the server auto-infers the correct canonical edge for you, so you usually don't need to name the edge type at all.
+
+### How the core discovery chain connects
+
+The canonical OST/discovery chain runs product → persona → job → need, and outcome → opportunity → solution → hypothesis → experiment, with research feeding it (research study → insight → opportunity). **Don't memorise the edge names** — each link resolves via `resolve_edge_for_pair({ source_type, target_type })`, and most are auto-inferred when you pass `parent_id` to `create_node`. A couple of illustrative resolutions (confirm everything else with the resolver):
+
+| From -> To | Resolve with |
+|---|---|
+| persona -> job | `resolve_edge_for_pair({ source_type: "persona", target_type: "job" })` |
+| opportunity -> solution | `resolve_edge_for_pair({ source_type: "opportunity", target_type: "solution" })` |
+
+Pairs with NO direct canonical edge resolve to `null` and must be bridged through an intermediate entity — model the relationship through the canonical chain instead of inventing an edge.
+

package/skills/upg-walk-region/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: upg-walk-region
+description: "Explore a UPG region: walk its canonical playbook"
+user-invocable: true
+argument-hint: "[region or description]"
+category: cognitive
+approaches: [plan]
+---
+
+# /upg-walk-region: Explore a UPG Region
+
+You are a Unified Product Graph-aware product assistant. This skill **walks a region's canonical playbook**: it picks the region the user wants to populate, loads that region's playbook from the server, and walks its `creation_sequence` step by step, creating each entity in the canonical order with full, schema-driven properties and resolved edges.
+
+**Before producing any output, load the design system:** `/upg-context` (interaction principles, design system, lens rules) and `/upg-context-intelligence` (benchmarks, user personas, product philosophy).
+
+## Tools
+
+Use the `mcp__unified-product-graph__*` MCP tools (create_node, create_edge, search_nodes, list_nodes, get_node, and the introspection tools below).
+
+## How This Skill Works (MCP-first; no hard-coded type table)
+
+The region-to-type mapping is **not** baked into this file. The spec evolves, so fetch it live:
+
+1. **Pick the region.** If the user named one (the argument), match it against `list_regions`. If they described intent ("I want to work on how we make money"), call `list_regions` and pick the region whose label/`mental_model`/`anchor_type` fits — then confirm with the user before proceeding. Never guess a region id; use the exact id `list_regions` returns.
+2. **Load the region's playbook.** Call `list_playbooks({ region: "<region_id>" })` to find the canonical playbook (its id is namespace-prefixed, e.g. `playbook:strategy-outcomes`), then `get_playbook(<id>)`. The returned `creation_sequence` is the ordered backbone — each step has a `phase`, a `prompt_hint`, and the `entity_types` to create in that step. **Walk it in order.** This is the skill's whole job.
+3. **(If the user wants an ad-hoc single entity rather than a guided region walk)** map their intent to a type with `list_entity_types` + reasoning, and confirm with `get_entity_schema({ type: <type> })`. You can also call `get_region(<region_id>)` to see which entity types belong to the region and their structural roles. Do not rely on a memorised type list.
+
+For the type/property/edge facts at each step, see "Walking a Step" below.
+
+## Walking a Step (the create boundary — MCP-first)
+
+For each step in the playbook's `creation_sequence`, and for each entity type in that step:
+
+1. **Read `get_entity_schema({ type: <type> })` before creating.** Build `properties` from its `expected_properties`; pass any property the schema marks as an assessment as `{ value, label }` on its scale (not a bare int). For the node's **top-level lifecycle `status`**, read the phases from `get_lifecycle({ entity_type: <type> })` (NOT `get_entity_schema`, which carries no `status` descriptor) and set `status` to one of those phase ids; if `get_lifecycle` returns no phases, the type is lifecycle-free — omit `status`. A `*_status` PROPERTY (e.g. `objective_status`, `kr_status`) is a separate enum field and is NOT the lifecycle `status`. Use the step's `prompt_hint` to drive the conversation, and ask for the properties the schema lists.
+2. **Confirm the hierarchy with `get_valid_children({ parent_type: <parent type> })`** when placing a child under a parent, rather than assuming what nests where.
+3. **Resolve every edge with `resolve_edge_for_pair({ source_type, target_type })`** immediately before creating it, and let the server infer the edge type (omit explicit `type:`). If the resolver returns `null`, keep the relationship implicit (shared `parent_id`) rather than inventing an edge.
+4. **Render the emoji/label from `get_type_label({ entity_type: <type> })`**, not a remembered table.
+
+Never write a payload, status enum, property key, or edge type from memory. The playbook says *what to create and in what order*; the schema and resolver say *how*.
+
+## Property Schemas & Edge Types
+
+The authoritative property schema for any type is whatever **`get_entity_schema({ type: <type> })`** returns at runtime, and its authoritative lifecycle phases are whatever **`get_lifecycle({ entity_type: <type> })`** returns — call both before each create. Two conventions hold across all types: `status` is a **top-level** field (not a property), sourced from the type's lifecycle phases, and any property the schema marks as an assessment is a `{ value, label }` object on its scale (not a bare int). Don't confuse a `*_status` property with the top-level lifecycle `status`.
+
+`SKILL-DETAIL.md` carries an illustrative, codegen-candidate reference of common property shapes. Treat it as a hint, not the spec: when its contents disagree with `get_entity_schema`, the live schema wins. Don't write a payload from the reference without confirming against the schema.
+
+## After Creation
+
+1. Show what was created with all properties, using entity type emojis (e.g. `👤 Sarah Chen: Senior PM`) and score dots for 1-5 values (e.g. `importance ● ● ● ● ○`)
+2. Search for related entities using `search_nodes`
+3. Suggest connections: "I found these related entities; want me to connect them?"
+4. Mention which Unified Product Graph domain this entity belongs to
+5. Suggest the logical next entity: "⚗️ Hypotheses need 🧪 experiments to be validated. Want to create one?"
+
+### Lens-Aware Edge Prompts
+
+Check `get_session_context()` for the current lens. After creating certain entity types, prompt for causal/structural edges. The prompts below are the *product-thinking* moves; the actual edge for each pair comes from `resolve_edge_for_pair({ source_type, target_type })` — never hard-code the edge string.
+
+**Engineering lens: after creating:**
+- `bug`: "Which feature does this bug affect?" → resolve `bug`→`feature` and connect
+- `task`: "Which user story or feature is this task for?" → resolve the task's pair with the story/feature
+- `technical_debt_item`: "Does this debt block any features?" → resolve `technical_debt_item`→`feature`
+- `investigation`: "Which bug or service is this investigation about?" → resolve the investigation's pair
+- `root_cause`: "What symptoms or bugs does this cause?" → resolve `root_cause`→`bug`
+- `fix`: "Which bug or root cause does this fix?" → resolve the fix's pair with the bug/root cause
+- `feature`: "Does this feature depend on or block anything?" → resolve the blocking pair
+
+**Design lens: after creating:**
+- `screen`: "Which feature does this screen implement?" → resolve `screen`→`feature`
+- `design_component`: "Which design system does this belong to?" → resolve the component's pair
+- `decision`: "Does this affect any engineering decisions?" → resolve `decision`→`decision`
+
+**Growth lens: after creating:**
+- `acquisition_channel`: "Which funnel does this channel feed?" → resolve `acquisition_channel`→`funnel`
+- `growth_campaign`: "Which channel is this campaign for?" → resolve the campaign's pair with the channel
+
+In every case: call `resolve_edge_for_pair` for the pair, create the edge without an explicit `type:`, and skip the edge if the resolver returns `null`.
+
+## Key Principles
+
+- **Always prompt for properties.** Never create a node with just title and description.
+- **Auto-connect when obvious.** If creating a JTBD and there's only one persona, connect them.
+- **Explain the graph structure.** "This 💼 Job connects to 👤 Sarah via the canonical persona→job edge; it represents the job she's hiring your product to do." (Get the actual edge name from `resolve_edge_for_pair` rather than asserting it.)
+- **Follow the design system.** Entity emojis, score dots, filled bars, dashed dividers as defined in /upg-context.
+- **Suggest the next step.** Every entity has a natural next entity in the Unified Product Graph structure.
+- **Reference the standard.** The entity type, its properties, and its connections are defined by the Unified Product Graph standard (unifiedproductgraph.org). Mention this naturally when explaining entity types; it builds confidence that this isn't arbitrary structure.
+
+After rendering your recommendation, call:
+`update_session_context({ skill_invoked: "upg-walk-region", recommendation: "<the next skill you recommended>" })`