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

package/skills/upg-context/SKILL.md

@@ -13,24 +13,38 @@ This is the shared brain for all `/upg-*` skills. When you load this, you unders
 
 ## What Is the Unified Product Graph?
 
-The Unified Product Graph is an **open standard for structured product thinking**. It defines how product knowledge connects: **310 entity types** organised into **10 canonical regions** (Strategy, Users & Needs, Discovery, Market, Experience, Delivery, Engineering, Business GTM, Analytics, Operations), with typed properties and semantic relationships.
+The Unified Product Graph is an **open standard for structured product thinking**. It defines how product knowledge connects: a catalogue of entity types organised into canonical regions (Strategy, Users & Needs, Discovery, Market, Experience, Delivery, Engineering, Business GTM, Analytics, Operations), with typed properties and semantic relationships. The live catalogue is the source of truth: call `list_entity_types` for the current types and `list_regions` for the current regions rather than relying on any count quoted here.
 
 It's not a tool. It's a vocabulary. A shared language for product decisions.
 
 The graph captures everything a product team thinks about: who the users are, what problems exist, what solutions are proposed, how the business works, how to reach people, what to build, and whether any of it is working. Instead of scattering this across Notion docs, Slack threads, and slide decks, the graph connects it all.
 
-A `.upg` file is a portable JSON file that holds an entire product graph. It's git-friendly, diffable, open source, and belongs to whoever created it. No vendor lock-in. No cloud required.
+A `.upg` file is a JSON file that holds an entire product graph. You can read it, edit it, diff it, and commit it like any other file in your repo; it belongs to whoever created it.
 
 **Standard:** unifiedproductgraph.org
 
 ---
 
+## MCP-First Rule (the default for every skill)
+
+The spec evolves: entity types, status/phase enums, property keys, valid children, and canonical edges all change between versions. **Do not write payloads from memory.** Before you create or change anything, fetch the live spec from the MCP server. This is the documented default for all `/upg-*` skills:
+
+- **Before creating or updating any entity:** call `get_entity_schema({ type: <type> })` and drive the form from its `expected_properties` and valid parent→child hierarchy. (`list_entity_types` lists what types exist; `get_valid_children({ parent_type: <type> })` answers "what can live under this?")
+- **For a node's top-level lifecycle `status`:** read the phases from `get_lifecycle({ entity_type: <type> })`. The phases live there — `get_entity_schema` does not return a `status` descriptor for stateless types (e.g. persona), so don't try to derive top-level `status` from it. Set top-level `status` to one of the phase ids `get_lifecycle` returns (e.g. objective → `draft`/`active`/`achieved`/`missed`/`deferred`). Many types are stateless and take no `status` at all; if `get_lifecycle` returns no phases, omit `status`.
+- **`*_status` PROPERTIES are NOT the node's lifecycle `status`.** Some types carry a property such as `objective_status` or `kr_status` (an enum inside `expected_properties`). These are distinct fields from the node's top-level lifecycle `status` and use their own enum values — never copy a lifecycle phase into a `*_status` property or vice versa.
+- **Before creating any edge:** call `resolve_edge_for_pair({ source_type, target_type })` to get the canonical edge for that pair, then let the server infer `type` (omit an explicit `type:` where you can).
+- **Before quoting a number** (how many types, frameworks, regions, lenses, playbooks, anti-patterns): derive it from the relevant `list_*` call or `get_spec_version`, or don't quote it. Counts written into a skill drift the moment the spec moves.
+
+Any catalogue table reproduced in this file (entity emojis, framework-label Rosetta, region/lens/stage names) is a **display convenience, not the authoritative spec**. The live MCP introspection tools (`get_type_label({ entity_type })`, `list_regions`, `get_region`, `list_lenses`, `get_lens`, `list_product_stages`, `list_playbooks`, `get_playbook`, `list_frameworks`, `get_framework`) are always the source of truth, and these tables are codegen-from-core candidates that may lag the spec.
+
+---
+
 ## The Cartographic Frame
 
-UPG v0.3 is a **chart** of product knowledge. Two orthogonal organising principles:
+UPG is a **chart** of product knowledge. Two orthogonal organising principles:
 
 **Regions**: *where* knowledge lives.
-Ten canonical regions roll up 36 atomic domains. Each region has an anchor entity, a shape archetype, a mental model, and a canonical playbook that walks its creation sequence.
+The canonical regions roll up atomic domains (enumerate them live with `list_regions` / `list_domains`). Each region has an anchor entity, a shape archetype, a mental model, and a canonical playbook that walks its creation sequence.
 
 **Approaches**: *how* you read the chart.
 Five paths of arrival, each answering one question:
@@ -46,13 +60,13 @@ Five paths of arrival, each answering one question:
 Approaches are the **agent's vocabulary**, not the user's menu. Users speak natural language; the LLM translates intent into one of the five approaches and routes to the fitting skill.
 
 **Playbooks**: region-anchored creation sequences.
-23 in v0.3 (10 canonical, one per region; 13 specialised; e.g. `business-model-bmc`, `experience-design-system`). A playbook says: "If you're filling out the Strategy region, do this in this order, with these entities."
+Canonical playbooks (enumerate via `list_playbooks`, load one via `get_playbook`; roughly one per region plus a few cross-region). A playbook says: "If you're filling out the Strategy region, do this in this order, with these entities." Reference them by their prefixed id (e.g. `playbook:strategy-outcomes`).
 
 **Frameworks**: named techniques inside an approach.
-346 framework definitions (Five Whys lives inside Reflect; RICE lives inside Prioritise; Wardley Map lives inside Plan). The approach is the cognitive operation; the framework is one specific shape of that operation.
+Framework definitions served by `list_frameworks` / `get_framework` (RICE lives inside Prioritise; Wardley Map lives inside Plan). The approach is the cognitive operation; the framework is one specific shape of that operation. (The broader frameworks package catalogues more; the MCP surface exposes the canonical subset; enumerate it live rather than quoting a count.)
 
 **Anti-patterns**: curated audit catalogue.
-12 anti-patterns codify what *bad* product thinking looks like (personas without jobs, opportunities without needs, etc.). They run inside the Inspect approach.
+Anti-patterns codify what *bad* product thinking looks like (personas without jobs, opportunities without needs, etc.). Enumerate via `list_anti_patterns`; they run inside the Inspect approach.
 
 ---
 
@@ -73,7 +87,7 @@ When you're running a UPG skill, you are a **product thinking partner**. Not a c
 
 ## The 8 Business Areas
 
-Every entity in the graph maps to one of 8 areas. These are the questions every product must answer.
+Every entity in the graph maps to one of 8 areas. These are the questions every product must answer. The areas themselves are an editorial grouping (stable); the **Key Entities** column is illustrative, not exhaustive: when you actually need the types in an area, confirm against `list_entity_types` rather than treating this column as the spec.
 
 | Area | Emoji | Question | Key Entities |
 |---|---|---|---|
@@ -111,31 +125,31 @@ After creating entities, check the graph and recommend ONE next step. **Use sess
 **Prioritise recommendations in this order:**
 1. What's most relevant to what was just created/discussed
 2. The biggest business area gap that **hasn't been recommended yet this session**
-3. `/upg-journey` as fallback
+3. `/upg-show-journey` as fallback
 
 Map gaps to skills:
-- Identity → `/upg-strategy`
-- Understanding → `/upg-persona`
-- Discovery → `/upg-discover`
-- Reaching → `/upg-launch` or `/upg-explore marketing`
-- Converting → `/upg-explore business_model`
-- Building → `/upg-explore product_spec`
-- Sustaining → `/upg-explore business_model`
-- Learning → `/upg-okr` or `/upg-explore team_org`
+- Identity → `/upg-new-strategy`
+- Understanding → `/upg-new-persona`
+- Discovery → `/upg-new-discovery`
+- Reaching → `/upg-new-launch` or `/upg-walk-region marketing`
+- Converting → `/upg-walk-region business_model`
+- Building → `/upg-walk-region product_spec`
+- Sustaining → `/upg-walk-region business_model`
+- Learning → `/upg-new-okr` or `/upg-walk-region team_org`
 
 **Sync suggestion:** If the skill created or modified entities during the session, add a sync line after the recommendation:
 
 ```
-🔄 **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.
 ```
 
 Only show this line when:
 1. At least one entity was created or updated during the session
 2. The cloud MCP tools exist (i.e. `mcp__upg-cloud__*` tools are available)
-3. The user did NOT just run `/upg-pull` (they just synced FROM cloud; pushing back immediately makes no sense)
+3. The user did NOT just run `/upg-sync-pull` (they just synced FROM cloud; pushing back immediately makes no sense)
 
 Do NOT show the sync line when:
-- The skill was read-only (e.g. `/upg-status`, `/upg-gaps`, `/upg-tree`, `/upg-diff`)
+- The skill was read-only (e.g. `/upg-show-status`, `/upg-check-gaps`, `/upg-show-tree`, `/upg-show-diff`)
 - No entities were created or modified
 
 ### Progress Indicators
@@ -214,7 +228,7 @@ After reading the .upg file, if the user mentions a product that doesn't match t
 
 > I see **[existing product]** in your graph. Are we working on that, or starting something new?
 
-If new: guide to `/upg-init` first. If same: continue.
+If new: guide to `/upg-new-graph` first. If same: continue.
 
 ### parent_id Clarification
 
@@ -226,7 +240,7 @@ Skills should narrate the graph like a story, not recite a spreadsheet. The grap
 
 **When to narrate:**
 - Session start: orient the user in their product world, not a database
-- Status checks (`/upg-status`, `/upg`); show the shape of thinking, not row counts
+- Status checks (`/upg-show-status`, `/upg`); show the shape of thinking, not row counts
 - Recommending next steps: ground the suggestion in a character or relationship
 - After capture: show what changed and why it matters
 
@@ -254,27 +268,27 @@ Skills should narrate the graph like a story, not recite a spreadsheet. The grap
 
 Skills must adapt to where the product actually is, not where it could theoretically be. A solo builder sketching their first idea doesn't need compliance frameworks.
 
-**Detecting the stage:** Read `product.stage` from `get_product_context()`. If missing, default to `idea`. The stage governs how the session adapts.
+**Detecting the stage:** Read `product.stage` from `get_product_context()`. The value is a canonical `UPGProductStage`; the canonical list is served by `list_product_stages` (source of truth). At time of writing the stages are `concept | validation | build | beta | launch | growth | mature | maintenance | sunset` (a static convenience for the table below; if it disagrees with `list_product_stages`, trust the tool). If missing, default to `concept`. The stage governs how the session adapts.
 
 | Stage | Tone | Focus |
 |-------|------|-------|
-| `idea` | Simple, encouraging | Identity + Understanding |
-| `mvp` | Practical, momentum-focused | Building + Converting |
-| `growth` | Strategic, structured | Reaching + Sustaining |
-| `scale` | Precise, systems-aware | All 8 areas active |
+| `concept`, `validation` | Simple, encouraging | Identity + Understanding |
+| `build`, `beta` | Practical, momentum-focused | Building + Converting |
+| `launch`, `growth` | Strategic, structured | Reaching + Sustaining |
+| `mature`, `maintenance`, `sunset` | Precise, systems-aware | All 8 areas active |
 
 **What to adapt:**
 - **Type pickers and suggestions:** Surface entity types proportional to stage. Early-stage products don't need governance, compliance, or platform-tier types yet.
-- **Framework recommendations:** `idea`/`mvp` get lightweight frameworks (Lean Canvas, simple persona cards). `growth` gets structured ones (JTBD, growth funnels). `scale` gets the full catalogue.
-- **Language complexity:** `idea` = plain language. `mvp` = some product terminology. `growth`/`scale` = assume fluency.
-- **Gap analysis:** Only flag missing entities appropriate to the current stage. A solo builder at `idea` with no `compliance_framework` is not a gap.
+- **Framework recommendations:** `concept`/`validation`/`build` get lightweight frameworks (Lean Canvas, simple persona cards). `launch`/`growth` get structured ones (JTBD, growth funnels). `mature`+ gets the full catalogue.
+- **Language complexity:** `concept` = plain language. `build`/`beta` = some product terminology. `growth`/`mature` = assume fluency.
+- **Gap analysis:** Only flag missing entities appropriate to the current stage. A solo builder at `concept` with no `compliance_framework` is not a gap.
 
 **When to suggest graduating:**
 - The current stage's entities are well-populated AND the user is reaching for concepts beyond the stage
 - Never push. Frame it as unlocking: *"Your graph is getting rich; want to unlock the growth-stage entity types?"*
 - Never auto-upgrade. Stage changes are explicit; the user decides.
 
-**Hard rule:** When in doubt, show less. An empty graph with 40 thoughtful types feels like possibility. An empty graph with 310 types feels like homework.
+**Hard rule:** When in doubt, show less. An empty graph with a few dozen thoughtful types feels like possibility. An empty graph with the entire type catalogue dumped on it feels like homework.
 
 ### Proactive Intelligence
 
@@ -292,7 +306,7 @@ Check these conditions against the current graph and surface the most relevant o
 | Features without persona connection | "'{feature}' isn't connected to any persona. Who is this for?" | Teresa Torres: every feature should trace to a user need |
 | Personas without evidence | "'{persona}' has no research evidence linked. Right now this is an assumption, not a validated persona." | Discovery: personas without evidence are fiction |
 | Needs without opportunities | "{N} needs have no connected opportunity. Pain without a response is just a complaint list." | OST: needs should surface opportunities |
-| Business model missing at mvp/growth stage | "Your product is at {stage} stage but has no business model entities. Strategy without economics is a hobby." | BMC: viability matters |
+| Business model missing at build/launch/growth stage | "Your product is at {stage} stage but has no business model entities. Strategy without economics is a hobby." | BMC: viability matters |
 | No hypotheses at all | "You have {N} features but zero hypotheses. Everything you're building is an untested bet." | Lean: build-measure-learn requires hypotheses |
 | Validated hypothesis → no feature | "'{hypothesis}' was validated but has no connected feature. You proved it works; now build it." | Discovery→Delivery gap |
 | High orphan rate (>30%) | "{N} of your {total} entities ({pct}%) have no connections. Isolated entities don't compound." | Graph value comes from connections |
@@ -307,7 +321,7 @@ Check these conditions against the current graph and surface the most relevant o
 
 **Examples:**
 
-During `/upg-explore feature`:
+During `/upg-walk-region feature`:
 > 💡 "Quick note: '{feature}' isn't connected to a persona yet. Want to link it to one of your existing personas?"
 
 During smart ending:
@@ -329,7 +343,7 @@ Skills should prefer **depth before breadth**: three rich personas teach the gra
 **When to nudge:**
 1. **After creating an entity.** If completeness is below 50%, surface it: *"Kai is only 40% complete; want to add their motivation and tech comfort before we move on?"* Pick the 2–3 most impactful missing fields, not the full list.
 2. **Before creating another entity of the same type.** If existing instances average below 60% completeness: *"Your 4 existing pain points average 45%; want to enrich those first, or keep drafting new ones?"*
-3. **During `/upg-status` or `/upg-gaps`.** Flag sparse entity types as a first-class finding.
+3. **During `/upg-show-status` or `/upg-check-gaps`.** Flag sparse entity types as a first-class finding.
 
 **How to phrase it:**
 - Warm, not nagging. One mention per type per interaction is enough.
@@ -339,14 +353,14 @@ Skills should prefer **depth before breadth**: three rich personas teach the gra
 **When NOT to nudge:**
 - **Rapid brainstorming.** If the user is firing off multiple creates, stay out of the way. Offer a batch-enrichment pass at the end.
 - **Explicit opt-out.** If the user says "just titles for now" or "skeleton first", skip nudges for the rest of that interaction.
-- **Bulk imports.** `/upg-capture` and `/upg-discover` often create many entities at once. Nudge once at the end, not per entity.
+- **Bulk imports.** `/upg-new-from-session` and `/upg-new-discovery` often create many entities at once. Nudge once at the end, not per entity.
 
 ### Cross-Skill Awareness
 
-Skills don't run in isolation. A user might run `/upg-persona` → `/upg-discover` → `/upg-explore business_model` in a single session. Each skill must build on what came before, not start fresh.
+Skills don't run in isolation. A user might run `/upg-new-persona` → `/upg-new-discovery` → `/upg-walk-region business_model` in a single session. Each skill must build on what came before, not start fresh.
 
 **Detecting what happened earlier:**
-1. **Scan the conversation** for prior `/upg-*` skill invocations. If the user ran `/upg-persona` earlier, personas were created.
+1. **Scan the conversation** for prior `/upg-*` skill invocations. If the user ran `/upg-new-persona` earlier, personas were created.
 2. **Check the graph** for recently-added entities. Reference them by name, not generically.
 3. **Read the thread, not just the graph.** The user may have discussed insights or rejected options during a prior skill run.
 
@@ -375,18 +389,20 @@ The UPG stores canonical types (`need`, `hypothesis`, `opportunity`). Users thin
 
 **How to detect context:** Explicit mention ("lean canvas", "JTBD", "design thinking", "shape up"), or the skill's natural framework home. If no framework is evident, use plain English (canonical UPG names are fine).
 
-**High-frequency type → framework label mapping:**
+**High-frequency type → framework label mapping** *(static display reference / codegen-from-core candidate; not authoritative):*
+
+Framework label keys are `lean_canvas`, `bmc`, `jtbd`, `design_thinking`, `lean_startup`. A blank cell means the spec defines no label for that type under that framework; fall back to the canonical UPG name. These values were taken verbatim from core's `framework_labels` at a point in time; do not improvise, and treat `get_type_label({ entity_type }).framework_labels` as the live source of truth (this table may lag the spec).
 
-| UPG Type | Lean Canvas | BMC | JTBD | Design Thinking | Lean Startup |
+| UPG Type | Lean Canvas (`lean_canvas`) | BMC (`bmc`) | JTBD (`jtbd`) | Design Thinking (`design_thinking`) | Lean Startup (`lean_startup`) |
 |----------|-------------|-----|------|-----------------|--------------|
-| `need` | Problem | Customer Problem | Pain Point | Struggle | Problem |
-| `solution` | Solution | Value Proposition | Solution | Idea | MVP |
-| `hypothesis` | Assumption | Assumption | | | Riskiest Assumption |
-| `opportunity` | Opportunity | | Opportunity | How Might We | Pivot Option |
-| `persona` | Customer Segment | Customer Segment | Job Performer | User | Early Adopter |
-| `metric` | Key Metric | | Success Metric | | Pirate Metric |
+| `need` | Problem | | Struggle | Pain Point | |
+| `solution` | Solution | | | Solution | |
+| `hypothesis` | Riskiest Assumption | | | | Hypothesis |
+| `opportunity` | | | | | |
+| `persona` | Customer Segment | Customer Archetype | | Persona | |
+| `metric` | Key Metric | | | | |
 
-Full mapping lives in `packages/upg-spec/src/type-labels.ts`; the Rosetta Stone.
+For labels under other frameworks (OST, VPC, AARRR, DORA, etc.), call `get_type_label({ entity_type })` and read `framework_labels`; the resolver is the source of truth. Full mapping lives in `packages/upg-spec/src/type-labels.ts`; the Rosetta Stone.
 
 **Rules:**
 1. **Store canonical, display contextual.** Never change the underlying type. A "Problem" in Lean Canvas is stored as `need`. Always.
@@ -401,7 +417,7 @@ Full mapping lives in `packages/upg-spec/src/type-labels.ts`; the Rosetta Stone.
 ### Brand
 - **Name:** Always "Unified Product Graph" in full; never just "UPG" in user-facing text
 
-- **Logo:** Dot cluster + H1; only on `/upg`, `/upg-status`, `/upg-export`
+- **Logo:** Dot cluster + H1; only on `/upg`, `/upg-show-status`, `/upg-sync-export`
 
 ```
   · ·
@@ -412,6 +428,8 @@ Full mapping lives in `packages/upg-spec/src/type-labels.ts`; the Rosetta Stone.
 
 ### Entity Emojis
 
+*Static display reference (codegen-from-core candidate; the authoritative emoji for a type is `get_type_label({ entity_type }).emoji`). Use this table for quick rendering; if a type is missing or disagrees, trust `get_type_label`.*
+
 | Type | Emoji | Type | Emoji |
 |---|---|---|---|
 | product, outcome, objective, key_result | 🎯 | feature | 📦 |
@@ -448,30 +466,26 @@ Full mapping lives in `packages/upg-spec/src/type-labels.ts`; the Rosetta Stone.
 - **Bold** for key values, *italic* for quotes/attributions, `code` for commands/values
 - > Blockquotes for insights and coaching
 
-### Footer
-
-Every skill ends with:
-
-```
-┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
-Your .upg file is yours: open standard, portable, git-friendly.
-unifiedproductgraph.org
-```
-
 ---
 
 ## Lens System
 
-UPG has 4 lenses that change what is surfaced first, recommended, and how gaps are framed. The lens is stored in `sessionContext.lens`. Check it via `get_session_context()`.
+UPG has a set of **lenses** that change what is surfaced first, recommended, and how gaps are framed. The lens is stored in `sessionContext.lens`. Check it via `get_session_context()`. The canonical lens ids are served by `list_lenses` / `get_lens` (source of truth); at time of writing they are `product`, `ux_design`, `engineering`, `growth`, `business`, `research`, `marketing`, `full`. **The design lens id is `ux_design`, not `design`** — `update_session_context({ lens: "ux_design" })`.
 
 ### Lenses
 
-| Lens | Protagonist | Session-start skill | Key entity types |
-|------|-------------|--------------------|--------------------|
-| **product** | The user/persona | `/upg-journey` | persona, job, need, outcome, hypothesis |
-| **engineering** | The codebase | `/upg-status` | bug, feature, task, technical_debt_item, investigation, root_cause, fix |
-| **design** | The interface | `/upg-explore ux_design` | screen, design_component, user_flow, design_token, decision (layer: design) |
-| **growth** | The funnel | `/upg-explore growth` | funnel, acquisition_channel, growth_campaign, positioning |
+*Static display reference (codegen-from-core candidate). The **Key entity types** column is illustrative; for the authoritative per-lens visible types call `get_lens(<id>).visible_types`.*
+
+| Lens id | Name | Protagonist | Session-start skill | Key entity types |
+|------|------|-------------|--------------------|--------------------|
+| `product` | Product | The user/persona | `/upg-show-journey` | persona, job, need, outcome, hypothesis |
+| `ux_design` | Design | The interface | `/upg-walk-region ux_design` | screen, design_component, user_flow, design_token, decision (layer: design) |
+| `engineering` | Engineering | The codebase | `/upg-show-status` | bug, feature, task, technical_debt_item, investigation, root_cause, fix |
+| `growth` | Growth | The funnel | `/upg-walk-region growth` | funnel, acquisition_channel, growth_campaign, positioning |
+| `business` | Business | The viability | `/upg-walk-region business_model` | value_proposition, revenue_stream, cost_structure, unit_economics, gtm_strategy |
+| `research` | Research | The evidence | `/upg-new-research` | research_study, insight, observation, opportunity, evidence |
+| `marketing` | Marketing | The audience | `/upg-new-launch` | positioning, messaging, marketing_channel, content_piece, launch |
+| `full` | Full | Everything | `/upg-show-journey` | all types, canonical vocabulary |
 
 ### Lens-Aware Behavior
 
@@ -480,26 +494,36 @@ When `sessionContext.lens` is set, adapt your behavior:
 **Narration style:**
 - **product:** Lead with persona threads. "Kai has 3 jobs and 2 needs."
 - **engineering:** Lead with implementation state. "Auth flow has 2 bugs and 1 blocker."
-- **design:** Lead with coverage. "12 screens mapped, 3 missing flows."
+- **ux_design:** Lead with coverage. "12 screens mapped, 3 missing flows."
 - **growth:** Lead with funnel health. "2 funnels, 3 channels, no campaigns yet."
+- **business:** Lead with viability. "Revenue modeled, no unit economics yet."
+- **research:** Lead with evidence state. "20 observations, 4 insights, 1 open study."
+- **marketing:** Lead with audience reach. "Positioning set, 2 channels, no launch plan."
+- **full:** Canonical vocabulary, no lens-specific framing.
 
 **Recommendations:**
-- **product:** Prioritize discovery and validation. `/upg-discover`, `/upg-hypothesis`
-- **engineering:** Prioritize resolution. `/upg-impact --upstream`, `/upg-impact`, `/upg-explore engineering`
-- **design:** Prioritize coverage. `/upg-explore ux_design` (covers screens, flows, wireframes, audit)
-- **growth:** Prioritize reach. `/upg-explore growth`, `/upg-explore marketing`, `/upg-launch`
+- **product:** Prioritize discovery and validation. `/upg-new-discovery`, `/upg-new-hypothesis`
+- **engineering:** Prioritize resolution. `/upg-show-impact --upstream`, `/upg-show-impact`, `/upg-walk-region engineering`
+- **ux_design:** Prioritize coverage. `/upg-walk-region ux_design` (covers screens, flows, wireframes, audit)
+- **growth:** Prioritize reach. `/upg-walk-region growth`, `/upg-walk-region marketing`, `/upg-new-launch`
+- **business:** Prioritize viability. `/upg-walk-region business_model`, `/upg-new-strategy`
+- **research:** Prioritize evidence. `/upg-new-research`, `/upg-new-discovery`
+- **marketing:** Prioritize messaging. `/upg-new-launch`, `/upg-walk-region marketing`
 
 **Gap framing:**
 - **product:** "Missing personas", "untested hypotheses", "no validation"
 - **engineering:** "Unresolved blockers", "disconnected work items", "bugs without fixes"
-- **design:** "Screens without flows", "orphan components", "no design system"
+- **ux_design:** "Screens without flows", "orphan components", "no design system"
 - **growth:** "No funnels", "channels without campaigns", "no positioning"
+- **business:** "No revenue model", "missing unit economics", "no GTM plan"
+- **research:** "Observations without insights", "insights without opportunities", "thin participant pool"
+- **marketing:** "No positioning", "features without messaging", "channels without content"
 
 ### Lens Entity Emojis
 
-In addition to the standard emojis above, use these for lens-specific types:
+*Static display reference (codegen-from-core candidate; authoritative source is `get_type_label({ entity_type }).emoji`).* In addition to the standard emojis above, use these for lens-specific types:
 
-**Engineering:** 🐛 bug, 📋 task, 🔴 blocker, 🔧 technical_debt_item, 🔍 investigation, 🌿 root_cause, 💊 fix, 🚩 feature_flag, 🚀 deployment
+**Engineering:** 🐛 bug, 📋 task, 🔧 technical_debt_item, 🔍 investigation, 🌿 root_cause, 💊 fix, 🚩 feature_flag, 🚀 deployment
 
 **Design:** 🖼 screen, 🧩 design_component, 🎨 design_token, ✏️ wireframe, 🔄 user_flow, 📐 design_system, 📝 decision (layer: design)
 

package/skills/upg-context-intelligence/SKILL.md

@@ -44,7 +44,7 @@ These people are already in the terminal. They don't need another app; they need
 - Building a first real product; background in engineering, new to product thinking
 - Needs: a structured way to think about users before jumping to code; validation before build
 - Fears: building the wrong thing, shipping features nobody asked for
-- UPG entry point: `/upg-init` → `/upg-research` → `/upg-hypothesis`
+- UPG entry point: `/upg-new-graph` → `/upg-new-research` → `/upg-new-hypothesis`
 - Language: responds to frameworks and structure; likes "the canonical way to do X"
 
 These users often discover UPG through visual tools rather than the CLI.
@@ -77,21 +77,17 @@ If any of these are empty, there's a blind spot. The graph makes blind spots vis
 
 Every assumption is a hypothesis. Every hypothesis needs an experiment. Every experiment produces a learning. This isn't academic; it's the difference between building something people want and building something you think they want.
 
-### 4. Open beats locked
-
-The `.upg` file is yours. MIT licensed. Portable. Git-friendly. Your thinking is your data.
-
-### 5. The graph compounds over time.
+### 4. The graph compounds over time.
 
 Every entity you add makes the next decision easier. A persona without connections is a note. A persona connected to jobs, needs, and outcomes is a lens. The graph gets more valuable the more it reflects how your product actually thinks.
 
-### 6. Collaborate, don't interrogate
+### 5. Collaborate, don't interrogate
 
 Every question should feel like brainstorming with a partner, not filling out a form. Offer options. Suggest. React. Build on what the user says. One question at a time; never dump a wall of prompts.
 
-### 7. Start simple, scale when ready
+### 6. Start simple, scale when ready
 
-The graph grows with the product. A solo builder at the `idea` stage uses a small fraction of the 310 entity types; most surface only when the product is mature enough to need them. Don't overwhelm an early-stage builder with concepts that belong at scale.
+The graph grows with the product. A solo builder at the `concept` stage uses a small fraction of the entity catalogue; most types surface only when the product is mature enough to need them. Don't overwhelm an early-stage builder with concepts that belong at scale.
 
 ---
 
@@ -101,31 +97,31 @@ Every UPG skill follows one of three patterns:
 
 ### Pattern 1: Discovery (guided conversation)
 Ask → discuss → create entities → connect. The user provides the thinking, you structure it. One question at a time, numbered options, vibe check before creating.
-Skills: `/upg-persona`, `/upg-discover`, `/upg-strategy`, `/upg-explore engineering`, `/upg-explore growth`, `/upg-explore ux_design`
+Skills: `/upg-new-persona`, `/upg-new-discovery`, `/upg-new-strategy`, `/upg-walk-region engineering`, `/upg-walk-region growth`, `/upg-walk-region ux_design`
 
 ### Pattern 2: Analysis (read and map)
 Scan external sources (codebase, docs, tools) → infer entities → present for confirmation → create. The skill does the reading, the user validates. Fast, automated, high-leverage.
-Skills: `/upg-explore engineering` (codebase / api / debt / deps), `/upg-explore ux_design` (screens / design-audit), `/upg-verify`, `/upg-explore marketing` (SEO).
+Skills: `/upg-walk-region engineering` (codebase / api / debt / deps), `/upg-walk-region ux_design` (screens / design-audit), `/upg-find-untracked`, `/upg-walk-region marketing` (SEO).
 
 ### Pattern 3: Workshop (think together)
 Interactive decision-making with frameworks, scoring, and trade-offs. Not just Q&A; actual collaborative problem-solving with comparison tables, ranking, and "why this matters" coaching.
-Skills: `/upg-explore pricing`, `/upg-explore content`, `/upg-explore ux_design` (flows / wireframes), `/upg-explore growth`.
+Skills: `/upg-walk-region pricing`, `/upg-walk-region content`, `/upg-walk-region ux_design` (flows / wireframes), `/upg-walk-region growth`.
 
 ---
 
 ## The Journey: 7 Phases
 
 ```
-Phase 1: Identity        /upg-init, /upg-strategy
-Phase 2: Understanding   /upg-persona, /upg-research, /upg-explore ux_design
-Phase 3: Discovery       /upg-discover, /upg-hypothesis
-Phase 4: Business        /upg-explore business_model, /upg-explore market_intelligence, /upg-okr, /upg-explore pricing
-Phase 5: Reaching        /upg-launch, /upg-explore market_intelligence, /upg-explore content, /upg-explore marketing, /upg-explore growth
-Phase 6: Building        /upg-explore product_spec, /upg-explore engineering, /upg-explore ux_design
-Phase 7: Learning        /upg-explore team_org, /upg-gaps, /upg-explore engineering (debt + deps)
+Phase 1: Identity        /upg-new-graph, /upg-new-strategy
+Phase 2: Understanding   /upg-new-persona, /upg-new-research, /upg-walk-region ux_design
+Phase 3: Discovery       /upg-new-discovery, /upg-new-hypothesis
+Phase 4: Business        /upg-walk-region business_model, /upg-walk-region market_intelligence, /upg-new-okr, /upg-walk-region pricing
+Phase 5: Reaching        /upg-new-launch, /upg-walk-region market_intelligence, /upg-walk-region content, /upg-walk-region marketing, /upg-walk-region growth
+Phase 6: Building        /upg-walk-region product_spec, /upg-walk-region engineering, /upg-walk-region ux_design
+Phase 7: Learning        /upg-walk-region team_org, /upg-check-gaps, /upg-walk-region engineering (debt + deps)
 ```
 
-`/upg-journey` tracks progress across all phases. Every skill points back to it.
+`/upg-show-journey` tracks progress across all phases. Every skill points back to it.
 
 ---
 
@@ -190,13 +186,13 @@ A benchmark is not "you have 1 persona, expected 2-4." A benchmark is a conversa
 > "You mapped a user journey for Kai but didn't mark any friction points. The whole reason to map a journey is to find where things break down; the moments of confusion, frustration, or abandonment. Go back and score each step: where does Kai struggle?"
 
 **Cross-domain (code exists but graph doesn't reflect it):**
-> "Your codebase has routes, components, and API endpoints, but your graph only has personas and features. The graph is meant to hold your whole product, not just the strategy side. Running `/upg-explore engineering` would bring your technical reality into the same picture as your product thinking."
+> "Your codebase has routes, components, and API endpoints, but your graph only has personas and features. The graph is meant to hold your whole product, not just the strategy side. Running `/upg-walk-region engineering` would bring your technical reality into the same picture as your product thinking."
 
 **The voice:** A coach who's been through this before. Not a linter flagging errors. Not a dashboard showing red/green. A thinking partner who says "here's what I've seen work" and lets you decide.
 
 **How to use the full benchmark set:**
 - The full benchmark data lives in `@unified-product-graph/core` (`benchmarks.ts`) with `getBenchmarksForStage()`, `getRelationshipBenchmarksForStage()`, `getRatioBenchmarksForStage()`, and `getExpectedDomainsForStage()`.
-- `/upg-gaps` runs ALL benchmarks (in its forward-looking signals section) and synthesises them into a narrative.
+- `/upg-check-gaps` runs ALL benchmarks (in its forward-looking signals section) and synthesises them into a narrative.
 - Individual skills surface the 1-2 benchmarks most relevant to what the user is doing.
 - Never show the raw benchmark table. Always narrate.
 
@@ -213,15 +209,15 @@ At the start of any graph-modifying skill session, detect the user's graph state
 
 | Local | Cloud | Action |
 |-------|-------|--------|
-| Exists | Available, same product | Note both are connected. Compare entity counts; if they differ by >20%, mention: "Local graph has {N} entities. Cloud has {M}. They may be out of sync; consider `/upg-push` or `/upg-pull`." |
+| Exists | Available, same product | Note both are connected. Compare entity counts; if they differ by >20%, mention: "Local graph has {N} entities. Cloud has {M}. They may be out of sync; consider `/upg-sync-push` or `/upg-sync-pull`." |
 | Exists | Available, different product | Ask: "Your local graph is **{local product}** but your cloud has **{cloud product}**. Which one are we working on?" |
 | Exists | Not available (tool doesn't exist or errors) | Proceed normally with local only. No sync suggestions at end. |
-| Doesn't exist | Available | Suggest: "You have a cloud graph but no local `.upg` file. Run `/upg-pull` to bring it down, or `/upg-init` to start fresh." |
-| Doesn't exist | Not available | Suggest `/upg-init` to get started. |
+| Doesn't exist | Available | Suggest: "You have a cloud graph but no local `.upg` file. Run `/upg-sync-pull` to bring it down, or `/upg-new-graph` to start fresh." |
+| Doesn't exist | Not available | Suggest `/upg-new-graph` to get started. |
 
 ### Rules
 
 - This check must be **QUICK**: just 2 tool calls. Do not block the user or force them to sync before working.
 - Surface the state briefly (one sentence) and move on to the skill's actual work.
-- Do NOT run this check for read-only skills (`/upg-status`, `/upg-gaps`, `/upg-tree`, `/upg-diff`, `/upg-export`).
-- Do NOT run this check for `/upg-push` or `/upg-pull` themselves; they already handle sync.
+- Do NOT run this check for read-only skills (`/upg-show-status`, `/upg-check-gaps`, `/upg-show-tree`, `/upg-show-diff`, `/upg-sync-export`).
+- Do NOT run this check for `/upg-sync-push` or `/upg-sync-pull` themselves; they already handle sync.

package/skills/upg-design-system/SKILL.md

@@ -12,7 +12,7 @@ This is the shared design reference for all `/upg-*` skills. Every skill that pr
 ## Brand
 
 - **Name:** Always write "Unified Product Graph" in full; never just "UPG" in user-facing text
-- **Logo mark:** Use on key screens (`/upg`, `/upg-status`, `/upg-export`)
+- **Logo mark:** Use on key screens (`/upg`, `/upg-show-status`, `/upg-sync-export`)
 - **Standard URL:** unifiedproductgraph.org
 
 ### Logo Mark
@@ -26,7 +26,7 @@ The dot cluster logo in a code block, followed by a bold H1 for the name:
 ```
 # Unified Product Graph
 
-The logo is the dot cluster (renders in monospace). The name is a markdown H1 (renders large and bold). Use at the top of `/upg`, `/upg-status`, and `/upg-export`. Other skills don't need the logo; keep it special.
+The logo is the dot cluster (renders in monospace). The name is a markdown H1 (renders large and bold). Use at the top of `/upg`, `/upg-show-status`, and `/upg-sync-export`. Other skills don't need the logo; keep it special.
 
 ## Section Dividers
 
@@ -194,7 +194,7 @@ After creating entities, the skill should:
 1. Call `get_graph_digest()` to check the current state
 2. Determine which of the 8 business areas has the biggest gap
 3. Recommend ONE specific next skill based on that gap
-4. Always offer `/upg-journey` as the "see full picture" fallback
+4. Always offer `/upg-show-journey` as the "see full picture" fallback
 
 **Good ending (smart, contextual):**
 ```
@@ -203,19 +203,19 @@ After creating entities, the skill should:
 Your graph now covers 6 of 8 business areas.
 The biggest gap: 📣 Reaching; you haven't thought about how people find your product.
 
-→ Run /upg-launch to define your positioning and channels.
+→ Run /upg-new-launch to define your positioning and channels.
 
-Or /upg-journey to see your full progress across all 7 phases.
+Or /upg-show-journey to see your full progress across all 7 phases.
 ```
 
 **Bad ending (menu dump; DON'T DO THIS):**
 ```
 Next steps:
-- /upg-persona: Add more personas
-- /upg-discover: Run a discovery session
-- /upg-hypothesis: Structure a bet
-- /upg-gaps: Check for gaps
-- /upg-status: Health dashboard
+- /upg-new-persona: Add more personas
+- /upg-new-discovery: Run a discovery session
+- /upg-new-hypothesis: Structure a bet
+- /upg-check-gaps: Check for gaps
+- /upg-show-status: Health dashboard
 ```
 
 The business areas to check (in priority order):
@@ -229,31 +229,26 @@ The business areas to check (in priority order):
 8. 📊 **Learning**: outcome, metric, objective, key_result, retrospective
 
 Map each empty/thin area to a skill:
-- Identity → `/upg-strategy`
-- Understanding → `/upg-persona`
-- Discovery → `/upg-discover`
-- Reaching → `/upg-launch` or `/upg-explore marketing`
-- Converting → `/upg-explore business_model`
-- Building → `/upg-explore product_spec`
-- Sustaining → `/upg-explore business_model`
-- Learning → `/upg-okr` or `/upg-explore team_org`
+- Identity → `/upg-new-strategy`
+- Understanding → `/upg-new-persona`
+- Discovery → `/upg-new-discovery`
+- Reaching → `/upg-new-launch` or `/upg-walk-region marketing`
+- Converting → `/upg-walk-region business_model`
+- Building → `/upg-walk-region product_spec`
+- Sustaining → `/upg-walk-region business_model`
+- Learning → `/upg-new-okr` or `/upg-walk-region team_org`
 
-If ALL areas are covered, celebrate and point to `/upg-journey`.
+If ALL areas are covered, celebrate and point to `/upg-show-journey`.
 
 ## Footer Pattern
 
 After the smart ending, add the standard footer with a dashed divider:
 
-```
-┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
-Your .upg file is yours: open standard, portable, git-friendly.
-unifiedproductgraph.org
-```
 
-On `/upg-status` and `/upg-gaps` (where maturity is 3+), the footer can be slightly more direct:
+On `/upg-show-status` and `/upg-check-gaps` (where maturity is 3+), the footer can be slightly more direct:
 
 ```
-can show patterns the CLI can't. → /upg-push to sync
+can show patterns the CLI can't. → /upg-sync-push to sync
 ```
 
 ## Tone